llio.texi

一个C源代码分析器

Truncate the file to zero length.  This option is only useful for
regular files, not special files such as directories or FIFOs.  POSIX.1
requires that you open the file for writing to use @code{O_TRUNC}.  In
BSD and GNU you must have permission to write the file to truncate it,
but you need not open for write access.

This is the only open-time action flag specified by POSIX.1.  There is
no good reason for truncation to be done by @code{open}, instead of by
calling @code{ftruncate} afterwards.  The @code{O_TRUNC} flag existed in
Unix before @code{ftruncate} was invented, and is retained for backward
compatibility.
@end deftypevr

@comment fcntl.h
@comment BSD
@deftypevr Macro int O_SHLOCK
Acquire a shared lock on the file, as with @code{flock}.
@xref{File Locks}.

If @code{O_CREAT} is specified, the locking is done atomically when
creating the file.  You are guaranteed that no other process will get
the lock on the new file first.
@end deftypevr

@comment fcntl.h
@comment BSD
@deftypevr Macro int O_EXLOCK
Acquire an exclusive lock on the file, as with @code{flock}.
@xref{File Locks}.  This is atomic like @code{O_SHLOCK}.
@end deftypevr

@node Operating Modes
@subsection I/O Operating Modes

The operating modes affect how input and output operations using a file
descriptor work.  These flags are set by @code{open} and can be fetched
and changed with @code{fcntl}.

@comment fcntl.h
@comment POSIX.1
@deftypevr Macro int O_APPEND
The bit that enables append mode for the file.  If set, then all
@code{write} operations write the data at the end of the file, extending
it, regardless of the current file position.
@end deftypevr

@comment fcntl.h
@comment POSIX.1
@deftypevr O_NONBLOCK
The bit that enables nonblocking mode for the file.  If this bit is set,
@code{read} requests on the file can return immediately with a failure
status if there is no input immediately available, instead of blocking.
Likewise, @code{write} requests can also return immediately with a
failure status if the output can't be written immediately.

Note that the @code{O_NONBLOCK} flag is overloaded as both an I/O
operating mode and a file name translation flag; @pxref{Open-time Flags}.
@end deftypevr

@comment fcntl.h
@comment BSD
@deftypevr Macro int O_NDELAY
This is an obsolete name for @code{O_NONBLOCK}, provided for
compatibility with BSD.  It is not defined by the POSIX.1 standard.
@end deftypevr

The remaining operating modes are BSD and GNU extensions.  They exist only
on some systems.  On other systems, these macros are not defined.

@comment fcntl.h
@comment BSD
@deftypevr Macro int O_ASYNC
The bit that enables asynchronous input mode.  If set, then @code{SIGIO}
signals will be generated when input is available.  @xref{Interrupt Input}.

Asynchronous input mode is a BSD feature.
@end deftypevr

@comment fcntl.h
@comment BSD
@deftypevr Macro int O_FSYNC
The bit that enables synchronous writing for the file.  If set, each
@code{write} call will make sure the data is reliably stored on disk before
returning. @c !!! xref fsync

Synchronous writing is a BSD feature.
@end deftypevr

@comment fcntl.h
@comment BSD
@deftypevr Macro int O_SYNC
This is another name for @code{O_FSYNC}.  They have the same value.
@end deftypevr

@comment fcntl.h
@comment GNU
@deftypevr Macro int O_NOATIME
If this bit is set, @code{read} will not update the access time of the
file.  @xref{File Times}.  This is used by programs that do backups, so
that backing a file up does not count as reading it.

This is a GNU extension.
@end deftypevr

@node Getting File Status Flags
@subsection Getting and Setting File Status Flags

The @code{fcntl} function can fetch or change file status flags.

@comment fcntl.h
@comment POSIX.1
@deftypevr Macro int F_GETFL
This macro is used as the @var{command} argument to @code{fcntl}, to
read the file status flags for the open file with descriptor
@var{filedes}.

The normal return value from @code{fcntl} with this command is a
nonnegative number which can be interpreted as the bitwise OR of the
individual flags.  Since the file access modes are not single-bit values,
you can mask off other bits in the returned flags with @code{O_ACCMODE}
to compare them.

In case of an error, @code{fcntl} returns @code{-1}.  The following
@code{errno} error conditions are defined for this command:

@table @code
@item EBADF
The @var{filedes} argument is invalid.
@end table
@end deftypevr

@comment fcntl.h
@comment POSIX.1
@deftypevr Macro int F_SETFL
This macro is used as the @var{command} argument to @code{fcntl}, to set
the file status flags for the open file corresponding to the
@var{filedes} argument.  This command requires a third @code{int}
argument to specify the new flags, so the call looks like this:

@smallexample
fcntl (@var{filedes}, F_SETFL, @var{new-flags})
@end smallexample

You can't change the access mode for the file in this way; that is,
whether the file descriptor was opened for reading or writing.

The normal return value from @code{fcntl} with this command is an
unspecified value other than @code{-1}, which indicates an error.  The
error conditions are the same as for the @code{F_GETFL} command.
@end deftypevr

If you want to modify the file status flags, you should get the current
flags with @code{F_GETFL} and modify the value.  Don't assume that the
flags listed here are the only ones that are implemented; your program
may be run years from now and more flags may exist then.  For example,
here is a function to set or clear the flag @code{O_NONBLOCK} without
altering any other flags:

@smallexample
@group
/* @r{Set the @code{O_NONBLOCK} flag of @var{desc} if @var{value} is nonzero,}
   @r{or clear the flag if @var{value} is 0.}
   @r{Return 0 on success, or -1 on error with @code{errno} set.} */ 

int
set_nonblock_flag (int desc, int value)
@{
  int oldflags = fcntl (desc, F_GETFL, 0);
  /* @r{If reading the flags failed, return error indication now.} */
  if (oldflags == -1)
    return -1;
  /* @r{Set just the flag we want to set.} */
  if (value != 0)
    oldflags |= O_NONBLOCK;
  else
    oldflags &= ~O_NONBLOCK;
  /* @r{Store modified flag word in the descriptor.} */
  return fcntl (desc, F_SETFL, oldflags);
@}
@end group
@end smallexample

@node File Locks
@section File Locks

@cindex file locks
@cindex record locking
The remaining @code{fcntl} commands are used to support @dfn{record
locking}, which permits multiple cooperating programs to prevent each
other from simultaneously accessing parts of a file in error-prone
ways.

@cindex exclusive lock
@cindex write lock
An @dfn{exclusive} or @dfn{write} lock gives a process exclusive access
for writing to the specified part of the file.  While a write lock is in
place, no other process can lock that part of the file.

@cindex shared lock
@cindex read lock
A @dfn{shared} or @dfn{read} lock prohibits any other process from
requesting a write lock on the specified part of the file.  However,
other processes can request read locks.

The @code{read} and @code{write} functions do not actually check to see
whether there are any locks in place.  If you want to implement a
locking protocol for a file shared by multiple processes, your application
must do explicit @code{fcntl} calls to request and clear locks at the
appropriate points.

Locks are associated with processes.  A process can only have one kind
of lock set for each byte of a given file.  When any file descriptor for
that file is closed by the process, all of the locks that process holds
on that file are released, even if the locks were made using other
descriptors that remain open.  Likewise, locks are released when a
process exits, and are not inherited by child processes created using
@code{fork} (@pxref{Creating a Process}).

When making a lock, use a @code{struct flock} to specify what kind of
lock and where.  This data type and the associated macros for the
@code{fcntl} function are declared in the header file @file{fcntl.h}.
@pindex fcntl.h

@comment fcntl.h
@comment POSIX.1
@deftp {Data Type} {struct flock}
This structure is used with the @code{fcntl} function to describe a file
lock.  It has these members:

@table @code
@item short int l_type
Specifies the type of the lock; one of @code{F_RDLCK}, @code{F_WRLCK}, or
@code{F_UNLCK}.

@item short int l_whence
This corresponds to the @var{whence} argument to @code{fseek} or
@code{lseek}, and specifies what the offset is relative to.  Its value
can be one of @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}.

@item off_t l_start
This specifies the offset of the start of the region to which the lock
applies, and is given in bytes relative to the point specified by
@code{l_whence} member.

@item off_t l_len
This specifies the length of the region to be locked.  A value of
@code{0} is treated specially; it means the region extends to the end of
the file.

@item pid_t l_pid
This field is the process ID (@pxref{Process Creation Concepts}) of the
process holding the lock.  It is filled in by calling @code{fcntl} with
the @code{F_GETLK} command, but is ignored when making a lock.
@end table
@end deftp

@comment fcntl.h
@comment POSIX.1
@deftypevr Macro int F_GETLK
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should get information about a lock.  This command
requires a third argument of type @w{@code{struct flock *}} to be passed
to @code{fcntl}, so that the form of the call is:

@smallexample
fcntl (@var{filedes}, F_GETLK, @var{lockp})
@end smallexample

If there is a lock already in place that would block the lock described
by the @var{lockp} argument, information about that lock overwrites
@code{*@var{lockp}}.  Existing locks are not reported if they are
compatible with making a new lock as specified.  Thus, you should
specify a lock type of @code{F_WRLCK} if you want to find out about both
read and write locks, or @code{F_RDLCK} if you want to find out about
write locks only.

There might be more than one lock affecting the region specified by the
@var{lockp} argument, but @code{fcntl} only returns information about
one of them.  The @code{l_whence} member of the @var{lockp} structure is
set to @code{SEEK_SET} and the @code{l_start} and @code{l_len} fields
set to identify the locked region.

If no lock applies, the only change to the @var{lockp} structure is to
update the @code{l_type} to a value of @code{F_UNLCK}.

The normal return value from @code{fcntl} with this command is an
unspecified value other than @code{-1}, which is reserved to indicate an
error.  The following @code{errno} error conditions are defined for
this command:

@table @code
@item EBADF
The @var{filedes} argument is invalid.

@item EINVAL
Either the @var{lockp} argument doesn't specify valid lock information,
or the file associated with @var{filedes} doesn't support locks.
@end table
@end deftypevr

@comment fcntl.h
@comment POSIX.1
@deftypevr Macro int F_SETLK
This macro is used as the @var{command} argument to @code{fcntl}, to
specify that it should set or clear a lock.  This command requires a
third argument of type @w{@code{struct flock *}} to be passed to
@code{fcntl}, so that the form of the call is:

@smallexample
fcntl (@var{filedes}, F_SETLK, @var{lockp})
@end smallexample

If the process already has a lock on any part of the region, the old lock
on that part is replaced with the new lock.  You can remove a lock
by specifying a lock type of @code{F_UNLCK}.

If the lock cannot be set, @code{fcntl} returns immediately with a value
of @code{-1}.  This function does not block waiting for other processes
to release locks.  If @code{fcntl} succeeds, it return a value other
than @code{-1}.

The following @code{errno} error conditions are defined for this
function:

@table @code
@item EACCES
@itemx EAGAIN
The lock cannot be set because it is blocked by an existing lock on the
file.  Some systems use @code{EAGAIN} in this case, and other systems
use @code{EACCES}; your program should treat them alike, after
@code{F_SETLK}.

@item EBADF
Either: the @var{filedes} argument is invalid; you requested a read lock
but the @var{filedes} is not open for read access; or, you requested a
write lock but the @var{filedes} is not open for write access.

@item EINVAL
Either the @var{lockp} argument doesn't specify valid lock information,
or the file associated with @var{filedes} doesn't support locks.

@item ENOLCK
The system has run out of file lock resources; there are already too
many file locks in place.

Well-designed file systems never report this error, because they have no
limitation on the number of locks.  However, you must still take account
of the possibility of t