Next: I/O Primitives, Up: Low-Level I/O
This section describes the primitives for opening and closing files
using file descriptors. The open and creat functions are
declared in the header file fcntl.h, while close is
declared in unistd.h.
The
openfunction creates and returns a new file descriptor for the file named by filename. Initially, the file position indicator for the file is at the beginning of the file. The argument mode is used only when a file is created, but it doesn't hurt to supply the argument in any case.The flags argument controls how the file is to be opened. This is a bit mask; you create the value by the bitwise OR of the appropriate parameters (using the `|' operator in C). See File Status Flags, for the parameters available.
The normal return value from
openis a non-negative integer file descriptor. In the case of an error, a value of -1 is returned instead. In addition to the usual file name errors (see File Name Errors), the followingerrnoerror conditions are defined for this function:
EACCES- The file exists but is not readable/writable as requested by the flags argument, the file does not exist and the directory is unwritable so it cannot be created.
EEXIST- Both
O_CREATandO_EXCLare set, and the named file already exists.EINTR- The
openoperation was interrupted by a signal. See Interrupted Primitives.EISDIR- The flags argument specified write access, and the file is a directory.
EMFILE- The process has too many files open. The maximum number of file descriptors is controlled by the
RLIMIT_NOFILEresource limit; see Limits on Resources.ENFILE- The entire system, or perhaps the file system which contains the directory, cannot support any additional open files at the moment. (This problem cannot happen on the GNU system.)
ENOENT- The named file does not exist, and
O_CREATis not specified.ENOSPC- The directory or file system that would contain the new file cannot be extended, because there is no disk space left.
ENXIOO_NONBLOCKandO_WRONLYare both set in the flags argument, the file named by filename is a FIFO (see Pipes and FIFOs), and no process has the file open for reading.EROFS- The file resides on a read-only file system and any of
O_WRONLY,O_RDWR, andO_TRUNCare set in the flags argument, orO_CREATis set and the file does not already exist.If on a 32 bit machine the sources are translated with
_FILE_OFFSET_BITS == 64the functionopenreturns a file descriptor opened in the large file mode which enables the file handling functions to use files up to 2^63 bytes in size and offset from -2^63 to 2^63. This happens transparently for the user since all of the lowlevel file handling functions are equally replaced.This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time
openis called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this calls toopenshould be protected using cancellation handlers.The
openfunction is the underlying primitive for thefopenandfreopenfunctions, that create streams.
This function is similar to
open. It returns a file descriptor which can be used to access the file named by filename. The only difference is that on 32 bit systems the file is opened in the large file mode. I.e., file length and file offsets can exceed 31 bits.When the sources are translated with
_FILE_OFFSET_BITS == 64this function is actually available under the nameopen. I.e., the new, extended API using 64 bit file sizes and offsets transparently replaces the old API.
This function is obsolete. The call:
creat (filename, mode)is equivalent to:
open (filename, O_WRONLY | O_CREAT | O_TRUNC, mode)If on a 32 bit machine the sources are translated with
_FILE_OFFSET_BITS == 64the functioncreatreturns a file descriptor opened in the large file mode which enables the file handling functions to use files up to 2^63 in size and offset from -2^63 to 2^63. This happens transparently for the user since all of the lowlevel file handling functions are equally replaced.
This function is similar to
creat. It returns a file descriptor which can be used to access the file named by filename. The only the difference is that on 32 bit systems the file is opened in the large file mode. I.e., file length and file offsets can exceed 31 bits.To use this file descriptor one must not use the normal operations but instead the counterparts named
*64, e.g.,read64.When the sources are translated with
_FILE_OFFSET_BITS == 64this function is actually available under the nameopen. I.e., the new, extended API using 64 bit file sizes and offsets transparently replaces the old API.
The function
closecloses the file descriptor filedes. Closing a file has the following consequences:
- The file descriptor is deallocated.
- Any record locks owned by the process on the file are unlocked.
- When all file descriptors associated with a pipe or FIFO have been closed, any unread data is discarded.
This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time
closeis called. If the thread gets canceled these resources stay allocated until the program ends. To avoid this, calls tocloseshould be protected using cancellation handlers.The normal return value from
closeis 0; a value of -1 is returned in case of failure. The followingerrnoerror conditions are defined for this function:
EBADF- The filedes argument is not a valid file descriptor.
EINTR- The
closecall was interrupted by a signal. See Interrupted Primitives. Here is an example of how to handleEINTRproperly:TEMP_FAILURE_RETRY (close (desc));ENOSPCEIOEDQUOT- When the file is accessed by NFS, these errors from
writecan sometimes not be detected untilclose. See I/O Primitives, for details on their meaning.Please note that there is no separate
close64function. This is not necessary since this function does not determine nor depend on the mode of the file. The kernel which performs thecloseoperation knows which mode the descriptor is used for and can handle this situation.
To close a stream, call fclose (see Closing Streams) instead
of trying to close its underlying file descriptor with close.
This flushes any buffered output and updates the stream object to
indicate that it is closed.