SAS/C Library Reference, Vol. 1

open -- Open a File for UNIX Style I/O

SYNOPSIS

 #include <sys/types.h>
 #include <sys/stat.h>
 #include <fcntl.h>

 int open(const char *name, int flags, mode_t mode);

DESCRIPTION

open opens a file for UNIX style I/O.

The name argument is the name of the file. The flags argument to open is a bit string formed by ORing option bits. The bits are defined symbolically; the header file fcntl.h should be included to obtain their definitions. The flags and their meanings are as follows:

O_RDONLY: opens for reading only.
O_WRONLY: opens for writing only.
O_RDWR: opens for both reading and writing.
O_APPEND: seeks to end of file before each write.
O_CREAT: creates a new file if it does not exist.
O_TRUNC: discards old data from existing file.
O_EXCL: does not accept an existing file.
O_TEXT: opens for text access.
O_BINARY: opens for binary access.
O_NOCTTY: does not make the terminal the controlling terminal of the process. This flag applies only to OpenEdition HFS files.
O_NONBLOCK: For an OpenEdition FIFO, does not delay completion of the open call until another process opens the FIFO. For other HFS files that support O_NONBLOCK, allows read and write calls to return immediately if no input is available. This flag only applies to OpenEdition HFS files.

Only one of the O_RDONLY, O_WRONLY, or O_RDWR flags should be set. O_EXCL is ignored if O_CREAT is also not set. If neither O_TEXT nor O_BINARY is specified, O_BINARY is assumed, unless the file to be opened is the terminal.

Note: The O_TEXT and O_BINARY flags have no effect when you open an OpenEdition HFS file.

The mode argument is optional and must be specified only when the flags argument specifies O_CREAT and name specifies an OpenEdition HFS file. In this case, mode indicates the permissions with which the file is created. For any other file type, or if the file to be opened already exists, the mode argument is ignored.

See Opening Files for more information on the filename and open mode specifications.

RETURN VALUE

open returns the file descriptor if the file was successfully opened. Otherwise, it returns - 1.

PORTABILITY

File numbers for OpenEdition files are allocated using the same strategy as that used by traditional UNIX compilers; that is, the smallest available file number is always used. File numbers for files other than OpenEdition files opened by open are assigned very large file numbers to avoid consuming file numbers in the range supported by OpenEdition.

IMPLEMENTATION

UNIX style I/O is implemented for files that do not have suitable attributes for the "rel" access method by copying the file contents to a temporary file and copying modified data back when the file is closed. See SAS/C I/O Concepts for further implementation information.

Standard I/O permits, at most, 256 files to be open at one time, including the three standard files. When UNIX style I/O is used with a non-HFS file whose attributes are not suitable for "rel" access, two file numbers are needed, one for the file specified by the program and one for a temporary file to which data are copied. For this reason, you might be limited to as few as 126 simultaneously-open, UNIX style files.

EXAMPLE

  #include <fcntl.h>

  main()
  {
     int datafile;
     datafile = open("MYDATA", O_WRONLY|O_CREAT|O_EXCL,S_IRUSR|S_IWUSR);
     if (datafile == -1)
        puts("Unable to create MYDATA");
  }

RELATED FUNCTIONS

aopen, cmsopen, fopen, opendir, osbopen, osopen, umask