Node:Opening files at a low level, Next:, Previous:Usual file name errors, Up:Low-level file routines


Opening files at a low level

You can open a file, or create one if it does not already exist, with the open command, which creates and returns a new file descriptor for the file name passed to it. If the file is successfully opened, the file position indicator is initially set to zero (the beginning of the file). (Note that the open function is actually called at an underlying level by fopen.)

The first parameter of open is a string containing the filename of the file you wish to open. The second parameter is an integer argument created by the bitwise OR of the following file status flags. (Bitwise OR is a mathematical operator that we have not yet covered in this book. To perform bitwise OR on two variables a and b, you simply insert a pipe character between them, thus: a | b. Bitwise OR is similar to the way the expression "and/or" is used in English. See the code example below for the use of bitwise OR with file status flags. See Advanced operators, for a detailed explanation of bitwise OR and other bitwise operators.)

The following flags are the more important ones for a beginning C programmer to know. There are a number of file status flags which are relevant only to more advanced programmers; for more details, see File Status Flags.)

Note that these flags are defined in macros in the GNU C Library header file fcntl.h, so remember to insert the line #include <fcntl.h> at the beginning of any source code file that uses them.


O_RDONLY
Open the file for read access.
O_WRONLY
Open the file for write access.
O_RDWR
Open the file for both read and write access. Same as O_RDONLY | O_WRONLY.
O_READ

Same as O_RDWR. GNU systems only.

O_WRITE
Same as O_WRONLY. GNU systems only.
O_EXEC
Open the file for executing. GNU systems only.
O_CREAT
The file will be created if it doesn't already exist.
O_EXCL
If O_CREAT is set as well, then open fails if the specified file exists already. Set this flag if you want to ensure you will not clobber an existing file.
O_TRUNC
Truncate the file to a length of zero bytes. This option is not useful for directories or other such special files. You must have write permission for the file, but you do not need to open it for write access to truncate it (under GNU).
O_APPEND
Open the file for appending. All write operations then write the data at the end of the file. This is the only way to ensure that the data you write will always go to the end of the file, even if there are other write operations happening at the same time.

The open function normally returns a non-negative integer file descriptor connected to the specified file. If there is an error, open will return -1 instead. In that case, you can check the errno variable to see which error occurred. In addition to the usual file name errors, open can set errno to the following values. (It can also specify a few other errors of interest only to advanced C programmers. See Opening and Closing Files, for a full list of error values. See Usual file name errors, for a list of the usual file name errors.).


EACCES
The file exists but is cannot be does not have read or write access (as requested), or the file does not exist but cannot be created because the directory does not have write access.
EEXIST
Both O_CREAT and O_EXCL are set, and the named file already exists. To open it would clobber it, so it will not be opened.
EISDIR
Write access to the file was requested, but the file is actually a directory.
EMFILE
Your program has too many files open.
ENOENT
The file named does not exist, and O_CREAT was not specified, so the file will not be created.
ENOSPC
The file cannot be created, because the disk is out of space.
EROFS
The file is on a read-only file system, but either one of O_WRONLY, O_RDWR, or O_TRUNC was specified, or O_CREAT was set and the file does not exist.

See Closing files at a low level, for a code example using both the low-level file functions open and close.