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'.
open
function 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 section File Status Flags, for the parameters available.
The normal return value from open
is a non-negative integer file
descriptor. In the case of an error, a value of @math{-1} is returned
instead. In addition to the usual file name errors (see section File Name Errors), the following errno
error conditions are defined
for this function:
EACCES
EEXIST
O_CREAT
and O_EXCL
are set, and the named file already
exists.
EINTR
open
operation was interrupted by a signal.
See section Primitives Interrupted by Signals.
EISDIR
EMFILE
RLIMIT_NOFILE
resource limit; see section Limiting Resource Usage.
ENFILE
ENOENT
O_CREAT
is not specified.
ENOSPC
ENXIO
O_NONBLOCK
and O_WRONLY
are both set in the flags
argument, the file named by filename is a FIFO (see section Pipes and FIFOs), and no process has the file open for reading.
EROFS
O_WRONLY
,
O_RDWR
, and O_TRUNC
are set in the flags argument,
or O_CREAT
is set and the file does not already exist.
If on a 32 bit machine the sources are translated with
_FILE_OFFSET_BITS == 64
the function open
returns a file
descriptor opened in the large file mode which enables the file handling
functions to use files up to @math{2^63} bytes in size and offset from
@math{-2^63} to @math{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 open
is
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this calls to open
should be
protected using cancellation handlers.
The open
function is the underlying primitive for the fopen
and freopen
functions, that create streams.
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 == 64
this
function is actually available under the name open
. I.e., the
new, extended API using 64 bit file sizes and offsets transparently
replaces the old API.
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 == 64
the function creat
returns a file
descriptor opened in the large file mode which enables the file handling
functions to use files up to @math{2^63} in size and offset from
@math{-2^63} to @math{2^63}. This happens transparently for the user
since all of the lowlevel file handling functions are equally replaced.
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 == 64
this
function is actually available under the name open
. I.e., the
new, extended API using 64 bit file sizes and offsets transparently
replaces the old API.
close
closes the file descriptor filedes.
Closing a file has the following consequences:
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 close
is
called. If the thread gets cancelled these resources stay allocated
until the program ends. To avoid this, calls to close
should be
protected using cancellation handlers.
The normal return value from close
is @math{0}; a value of @math{-1}
is returned in case of failure. The following errno
error
conditions are defined for this function:
EBADF
EINTR
close
call was interrupted by a signal.
See section Primitives Interrupted by Signals.
Here is an example of how to handle EINTR
properly:
TEMP_FAILURE_RETRY (close (desc));
ENOSPC
EIO
EDQUOT
write
can sometimes
not be detected until close
. See section Input and Output Primitives, for details
on their meaning.
Please note that there is no separate close64
function.
This is not necessary since this function does not determine nor depend
on the mode of the file. The kernel which performs the close
operation knows which mode the descriptor is used for and can handle
this situation.
To close a stream, call fclose
(see section 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.
Go to the first, previous, next, last section, table of contents.