This is libc.info, produced by makeinfo version 4.2 from libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.3.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.


File: libc.info,  Node: Synchronizing AIO Operations,  Next: Cancel AIO Operations,  Prev: Status of AIO Operations,  Up: Asynchronous I/O

Getting into a Consistent State
-------------------------------

   When dealing with asynchronous operations it is sometimes necessary
to get into a consistent state.  This would mean for AIO that one wants
to know whether a certain request or a group of request were processed.
This could be done by waiting for the notification sent by the system
after the operation terminated, but this sometimes would mean wasting
resources (mainly computation time).  Instead POSIX.1b defines two
functions which will help with most kinds of consistency.

   The `aio_fsync' and `aio_fsync64' functions are only available if
the symbol `_POSIX_SYNCHRONIZED_IO' is defined in `unistd.h'.

 - Function: int aio_fsync (int OP, struct aiocb *AIOCBP)
     Calling this function forces all I/O operations operating queued
     at the time of the function call operating on the file descriptor
     `aiocbp->aio_fildes' into the synchronized I/O completion state
     (*note Synchronizing I/O::).  The `aio_fsync' function returns
     immediately but the notification through the method described in
     `aiocbp->aio_sigevent' will happen only after all requests for this
     file descriptor have terminated and the file is synchronized.
     This also means that requests for this very same file descriptor
     which are queued after the synchronization request are not
     affected.

     If OP is `O_DSYNC' the synchronization happens as with a call to
     `fdatasync'.  Otherwise OP should be `O_SYNC' and the
     synchronization happens as with `fsync'.

     As long as the synchronization has not happened, a call to
     `aio_error' with the reference to the object pointed to by AIOCBP
     returns `EINPROGRESS'.  Once the synchronization is done
     `aio_error' return 0 if the synchronization was not successful.
     Otherwise the value returned is the value to which the `fsync' or
     `fdatasync' function would have set the `errno' variable.  In this
     case nothing can be assumed about the consistency for the data
     written to this file descriptor.

     The return value of this function is 0 if the request was
     successfully enqueued.  Otherwise the return value is -1 and
     `errno' is set to one of the following values:

    `EAGAIN'
          The request could not be enqueued due to temporary lack of
          resources.

    `EBADF'
          The file descriptor `aiocbp->aio_fildes' is not valid or not
          open for writing.

    `EINVAL'
          The implementation does not support I/O synchronization or
          the OP parameter is other than `O_DSYNC' and `O_SYNC'.

    `ENOSYS'
          This function is not implemented.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' this
     function is in fact `aio_fsync64' since the LFS interface
     transparently replaces the normal implementation.

 - Function: int aio_fsync64 (int OP, struct aiocb64 *AIOCBP)
     This function is similar to `aio_fsync' with the only difference
     that the argument is a reference to a variable of type `struct
     aiocb64'.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' this
     function is available under the name `aio_fsync' and so
     transparently replaces the interface for small files on 32 bit
     machines.

   Another method of synchronization is to wait until one or more
requests of a specific set terminated.  This could be achieved by the
`aio_*' functions to notify the initiating process about the
termination but in some situations this is not the ideal solution.  In
a program which constantly updates clients somehow connected to the
server it is not always the best solution to go round robin since some
connections might be slow.  On the other hand letting the `aio_*'
function notify the caller might also be not the best solution since
whenever the process works on preparing data for on client it makes no
sense to be interrupted by a notification since the new client will not
be handled before the current client is served.  For situations like
this `aio_suspend' should be used.

 - Function: int aio_suspend (const struct aiocb *const LIST[], int
          NENT, const struct timespec *TIMEOUT)
     When calling this function, the calling thread is suspended until
     at least one of the requests pointed to by the NENT elements of the
     array LIST has completed.  If any of the requests has already
     completed at the time `aio_suspend' is called, the function returns
     immediately.  Whether a request has terminated or not is
     determined by comparing the error status of the request with
     `EINPROGRESS'.  If an element of LIST is `NULL', the entry is
     simply ignored.

     If no request has finished, the calling process is suspended.  If
     TIMEOUT is `NULL', the process is not woken until a request has
     finished.  If TIMEOUT is not `NULL', the process remains suspended
     at least as long as specified in TIMEOUT.  In this case,
     `aio_suspend' returns with an error.

     The return value of the function is 0 if one or more requests from
     the LIST have terminated.  Otherwise the function returns -1 and
     `errno' is set to one of the following values:

    `EAGAIN'
          None of the requests from the LIST completed in the time
          specified by TIMEOUT.

    `EINTR'
          A signal interrupted the `aio_suspend' function.  This signal
          might also be sent by the AIO implementation while signalling
          the termination of one of the requests.

    `ENOSYS'
          The `aio_suspend' function is not implemented.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' this
     function is in fact `aio_suspend64' since the LFS interface
     transparently replaces the normal implementation.

 - Function: int aio_suspend64 (const struct aiocb64 *const LIST[], int
          NENT, const struct timespec *TIMEOUT)
     This function is similar to `aio_suspend' with the only difference
     that the argument is a reference to a variable of type `struct
     aiocb64'.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64' this
     function is available under the name `aio_suspend' and so
     transparently replaces the interface for small files on 32 bit
     machines.


File: libc.info,  Node: Cancel AIO Operations,  Next: Configuration of AIO,  Prev: Synchronizing AIO Operations,  Up: Asynchronous I/O

Cancellation of AIO Operations
------------------------------

   When one or more requests are asynchronously processed, it might be
useful in some situations to cancel a selected operation, e.g., if it
becomes obvious that the written data is no longer accurate and would
have to be overwritten soon.  As an example, assume an application,
which writes data in files in a situation where new incoming data would
have to be written in a file which will be updated by an enqueued
request.  The POSIX AIO implementation provides such a function, but
this function is not capable of forcing the cancellation of the
request.  It is up to the implementation to decide whether it is
possible to cancel the operation or not.  Therefore using this function
is merely a hint.

 - Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP)
     The `aio_cancel' function can be used to cancel one or more
     outstanding requests.  If the AIOCBP parameter is `NULL', the
     function tries to cancel all of the outstanding requests which
     would process the file descriptor FILDES (i.e., whose `aio_fildes'
     member is FILDES).  If AIOCBP is not `NULL', `aio_cancel' attempts
     to cancel the specific request pointed to by AIOCBP.

     For requests which were successfully canceled, the normal
     notification about the termination of the request should take
     place.  I.e., depending on the `struct sigevent' object which
     controls this, nothing happens, a signal is sent or a thread is
     started.  If the request cannot be canceled, it terminates the
     usual way after performing the operation.

     After a request is successfully canceled, a call to `aio_error'
     with a reference to this request as the parameter will return
     `ECANCELED' and a call to `aio_return' will return -1.  If the
     request wasn't canceled and is still running the error status is
     still `EINPROGRESS'.

     The return value of the function is `AIO_CANCELED' if there were
     requests which haven't terminated and which were successfully
     canceled.  If there is one or more requests left which couldn't be
     canceled, the return value is `AIO_NOTCANCELED'.  In this case
     `aio_error' must be used to find out which of the, perhaps
     multiple, requests (in AIOCBP is `NULL') weren't successfully
     canceled.  If all requests already terminated at the time
     `aio_cancel' is called the return value is `AIO_ALLDONE'.

     If an error occurred during the execution of `aio_cancel' the
     function returns -1 and sets `errno' to one of the following
     values.

    `EBADF'
          The file descriptor FILDES is not valid.

    `ENOSYS'
          `aio_cancel' is not implemented.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64', this
     function is in fact `aio_cancel64' since the LFS interface
     transparently replaces the normal implementation.

 - Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP)
     This function is similar to `aio_cancel' with the only difference
     that the argument is a reference to a variable of type `struct
     aiocb64'.

     When the sources are compiled with `_FILE_OFFSET_BITS == 64', this
     function is available under the name `aio_cancel' and so
     transparently replaces the interface for small files on 32 bit
     machines.


File: libc.info,  Node: Configuration of AIO,  Prev: Cancel AIO Operations,  Up: Asynchronous I/O

How to optimize the AIO implementation
--------------------------------------

   The POSIX standard does not specify how the AIO functions are
implemented.  They could be system calls, but it is also possible to
emulate them at userlevel.

   At the point of this writing, the available implementation is a
userlevel implementation which uses threads for handling the enqueued
requests.  While this implementation requires making some decisions
about limitations, hard limitations are something which is best avoided
in the GNU C library.  Therefore, the GNU C library provides a means
for tuning the AIO implementation according to the individual use.

 - Data Type: struct aioinit
     This data type is used to pass the configuration or tunable
     parameters to the implementation.  The program has to initialize
     the members of this struct and pass it to the implementation using
     the `aio_init' function.

    `int aio_threads'
          This member specifies the maximal number of threads which may
          be used at any one time.

    `int aio_num'
          This number provides an estimate on the maximal number of
          simultaneously enqueued requests.

    `int aio_locks'
          Unused.

    `int aio_usedba'
          Unused.

    `int aio_debug'
          Unused.

    `int aio_numusers'
          Unused.

    `int aio_reserved[2]'
          Unused.

 - Function: void aio_init (const struct aioinit *INIT)
     This function must be called before any other AIO function.
     Calling it is completely voluntary, as it is only meant to help
     the AIO implementation perform better.

     Before calling the `aio_init', function the members of a variable
     of type `struct aioinit' must be initialized.  Then a reference to
     this variable is passed as the parameter to `aio_init' which itself
     may or may not pay attention to the hints.

     The function has no return value and no error cases are defined.
     It is a extension which follows a proposal from the SGI
     implementation in Irix 6.  It is not covered by POSIX.1b or Unix98.


File: libc.info,  Node: Control Operations,  Next: Duplicating Descriptors,  Prev: Asynchronous I/O,  Up: Low-Level I/O

Control Operations on Files
===========================

   This section describes how you can perform various other operations
on file descriptors, such as inquiring about or setting flags describing
the status of the file descriptor, manipulating record locks, and the
like.  All of these operations are performed by the function `fcntl'.

   The second argument to the `fcntl' function is a command that
specifies which operation to perform.  The function and macros that name
various flags that are used with it are declared in the header file
`fcntl.h'.  Many of these flags are also used by the `open' function;
see *Note Opening and Closing Files::.

 - Function: int fcntl (int FILEDES, int COMMAND, ...)
     The `fcntl' function performs the operation specified by COMMAND
     on the file descriptor FILEDES.  Some commands require additional
     arguments to be supplied.  These additional arguments and the
     return value and error conditions are given in the detailed
     descriptions of the individual commands.

     Briefly, here is a list of what the various commands are.

    `F_DUPFD'
          Duplicate the file descriptor (return another file descriptor
          pointing to the same open file).  *Note Duplicating
          Descriptors::.

    `F_GETFD'
          Get flags associated with the file descriptor.  *Note
          Descriptor Flags::.

    `F_SETFD'
          Set flags associated with the file descriptor.  *Note
          Descriptor Flags::.

    `F_GETFL'
          Get flags associated with the open file.  *Note File Status
          Flags::.

    `F_SETFL'
          Set flags associated with the open file.  *Note File Status
          Flags::.

    `F_GETLK'
          Get a file lock.  *Note File Locks::.

    `F_SETLK'
          Set or clear a file lock.  *Note File Locks::.

    `F_SETLKW'
          Like `F_SETLK', but wait for completion.  *Note File Locks::.

    `F_GETOWN'
          Get process or process group ID to receive `SIGIO' signals.
          *Note Interrupt Input::.

    `F_SETOWN'
          Set process or process group ID to receive `SIGIO' signals.
          *Note Interrupt Input::.

     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
     `fcntl' is called.  If the thread gets canceled these resources
     stay allocated until the program ends.  To avoid this calls to
     `fcntl' should be protected using cancellation handlers.


File: libc.info,  Node: Duplicating Descriptors,  Next: Descriptor Flags,  Prev: Control Operations,  Up: Low-Level I/O

Duplicating Descriptors
=======================

   You can "duplicate" a file descriptor, or allocate another file
descriptor that refers to the same open file as the original.  Duplicate
descriptors share one file position and one set of file status flags
(*note File Status Flags::), but each has its own set of file descriptor
flags (*note Descriptor Flags::).

   The major use of duplicating a file descriptor is to implement
"redirection" of input or output:  that is, to change the file or pipe
that a particular file descriptor corresponds to.

   You can perform this operation using the `fcntl' function with the
`F_DUPFD' command, but there are also convenient functions `dup' and
`dup2' for duplicating descriptors.

   The `fcntl' function and flags are declared in `fcntl.h', while
prototypes for `dup' and `dup2' are in the header file `unistd.h'.

 - Function: int dup (int OLD)
     This function copies descriptor OLD to the first available
     descriptor number (the first number not currently open).  It is
     equivalent to `fcntl (OLD, F_DUPFD, 0)'.

 - Function: int dup2 (int OLD, int NEW)
     This function copies the descriptor OLD to descriptor number NEW.

     If OLD is an invalid descriptor, then `dup2' does nothing; it does
     not close NEW.  Otherwise, the new duplicate of OLD replaces any
     previous meaning of descriptor NEW, as if NEW were closed first.

     If OLD and NEW are different numbers, and OLD is a valid
     descriptor number, then `dup2' is equivalent to:

          close (NEW);
          fcntl (OLD, F_DUPFD, NEW)

     However, `dup2' does this atomically; there is no instant in the
     middle of calling `dup2' at which NEW is closed and not yet a
     duplicate of OLD.

 - Macro: int F_DUPFD
     This macro is used as the COMMAND argument to `fcntl', to copy the
     file descriptor given as the first argument.

     The form of the call in this case is:

          fcntl (OLD, F_DUPFD, NEXT-FILEDES)

     The NEXT-FILEDES argument is of type `int' and specifies that the
     file descriptor returned should be the next available one greater
     than or equal to this value.

     The return value from `fcntl' with this command is normally the
     value of the new file descriptor.  A return value of -1 indicates
     an error.  The following `errno' error conditions are defined for
     this command:

    `EBADF'
          The OLD argument is invalid.

    `EINVAL'
          The NEXT-FILEDES argument is invalid.

    `EMFILE'
          There are no more file descriptors available--your program is
          already using the maximum.  In BSD and GNU, the maximum is
          controlled by a resource limit that can be changed; *note
          Limits on Resources::, for more information about the
          `RLIMIT_NOFILE' limit.

     `ENFILE' is not a possible error code for `dup2' because `dup2'
     does not create a new opening of a file; duplicate descriptors do
     not count toward the limit which `ENFILE' indicates.  `EMFILE' is
     possible because it refers to the limit on distinct descriptor
     numbers in use in one process.

   Here is an example showing how to use `dup2' to do redirection.
Typically, redirection of the standard streams (like `stdin') is done
by a shell or shell-like program before calling one of the `exec'
functions (*note Executing a File::) to execute a new program in a
child process.  When the new program is executed, it creates and
initializes the standard streams to point to the corresponding file
descriptors, before its `main' function is invoked.

   So, to redirect standard input to a file, the shell could do
something like:

     pid = fork ();
     if (pid == 0)
       {
         char *filename;
         char *program;
         int file;
         ...
         file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
         dup2 (file, STDIN_FILENO);
         TEMP_FAILURE_RETRY (close (file));
         execv (program, NULL);
       }

   There is also a more detailed example showing how to implement
redirection in the context of a pipeline of processes in *Note
Launching Jobs::.


File: libc.info,  Node: Descriptor Flags,  Next: File Status Flags,  Prev: Duplicating Descriptors,  Up: Low-Level I/O

File Descriptor Flags
=====================

   "File descriptor flags" are miscellaneous attributes of a file
descriptor.  These flags are associated with particular file
descriptors, so that if you have created duplicate file descriptors
from a single opening of a file, each descriptor has its own set of
flags.

   Currently there is just one file descriptor flag: `FD_CLOEXEC',
which causes the descriptor to be closed if you use any of the
`exec...' functions (*note Executing a File::).

   The symbols in this section are defined in the header file `fcntl.h'.

 - Macro: int F_GETFD
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should return the file descriptor flags associated with
     the FILEDES argument.

     The normal return value from `fcntl' with this command is a
     nonnegative number which can be interpreted as the bitwise OR of
     the individual flags (except that currently there is only one flag
     to use).

     In case of an error, `fcntl' returns -1.  The following `errno'
     error conditions are defined for this command:

    `EBADF'
          The FILEDES argument is invalid.

 - Macro: int F_SETFD
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set the file descriptor flags associated with the
     FILEDES argument.  This requires a third `int' argument to specify
     the new flags, so the form of the call is:

          fcntl (FILEDES, F_SETFD, NEW-FLAGS)

     The normal return value from `fcntl' with this command is an
     unspecified value other than -1, which indicates an error.  The
     flags and error conditions are the same as for the `F_GETFD'
     command.

   The following macro is defined for use as a file descriptor flag with
the `fcntl' function.  The value is an integer constant usable as a bit
mask value.

 - Macro: int FD_CLOEXEC
     This flag specifies that the file descriptor should be closed when
     an `exec' function is invoked; see *Note Executing a File::.  When
     a file descriptor is allocated (as with `open' or `dup'), this bit
     is initially cleared on the new file descriptor, meaning that
     descriptor will survive into the new program after `exec'.

   If you want to modify the file descriptor flags, you should get the
current flags with `F_GETFD' 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 `FD_CLOEXEC'
without altering any other flags:

     /* Set the `FD_CLOEXEC' flag of DESC if VALUE is nonzero,
        or clear the flag if VALUE is 0.
        Return 0 on success, or -1 on error with `errno' set. */
     
     int
     set_cloexec_flag (int desc, int value)
     {
       int oldflags = fcntl (desc, F_GETFD, 0);
       /* If reading the flags failed, return error indication now. */
       if (oldflags < 0)
         return oldflags;
       /* Set just the flag we want to set. */
       if (value != 0)
         oldflags |= FD_CLOEXEC;
       else
         oldflags &= ~FD_CLOEXEC;
       /* Store modified flag word in the descriptor. */
       return fcntl (desc, F_SETFD, oldflags);
     }


File: libc.info,  Node: File Status Flags,  Next: File Locks,  Prev: Descriptor Flags,  Up: Low-Level I/O

File Status Flags
=================

   "File status flags" are used to specify attributes of the opening of
a file.  Unlike the file descriptor flags discussed in *Note Descriptor
Flags::, the file status flags are shared by duplicated file descriptors
resulting from a single opening of the file.  The file status flags are
specified with the FLAGS argument to `open'; *note Opening and Closing
Files::.

   File status flags fall into three categories, which are described in
the following sections.

   * *Note Access Modes::, specify what type of access is allowed to the
     file: reading, writing, or both.  They are set by `open' and are
     returned by `fcntl', but cannot be changed.

   * *Note Open-time Flags::, control details of what `open' will do.
     These flags are not preserved after the `open' call.

   * *Note Operating Modes::, affect how operations such as `read' and
     `write' are done.  They are set by `open', and can be fetched or
     changed with `fcntl'.

   The symbols in this section are defined in the header file `fcntl.h'.

* Menu:

* Access Modes::                Whether the descriptor can read or write.
* Open-time Flags::             Details of `open'.
* Operating Modes::             Special modes to control I/O operations.
* Getting File Status Flags::   Fetching and changing these flags.


File: libc.info,  Node: Access Modes,  Next: Open-time Flags,  Up: File Status Flags

File Access Modes
-----------------

   The file access modes allow a file descriptor to be used for reading,
writing, or both.  (In the GNU system, they can also allow none of
these, and allow execution of the file as a program.)  The access modes
are chosen when the file is opened, and never change.

 - Macro: int O_RDONLY
     Open the file for read access.

 - Macro: int O_WRONLY
     Open the file for write access.

 - Macro: int O_RDWR
     Open the file for both reading and writing.

   In the GNU system (and not in other systems), `O_RDONLY' and
`O_WRONLY' are independent bits that can be bitwise-ORed together, and
it is valid for either bit to be set or clear.  This means that
`O_RDWR' is the same as `O_RDONLY|O_WRONLY'.  A file access mode of
zero is permissible; it allows no operations that do input or output to
the file, but does allow other operations such as `fchmod'.  On the GNU
system, since "read-only" or "write-only" is a misnomer, `fcntl.h'
defines additional names for the file access modes.  These names are
preferred when writing GNU-specific code.  But most programs will want
to be portable to other POSIX.1 systems and should use the POSIX.1
names above instead.

 - Macro: int O_READ
     Open the file for reading.  Same as `O_RDONLY'; only defined on
     GNU.

 - Macro: int O_WRITE
     Open the file for writing.  Same as `O_WRONLY'; only defined on
     GNU.

 - Macro: int O_EXEC
     Open the file for executing.  Only defined on GNU.

   To determine the file access mode with `fcntl', you must extract the
access mode bits from the retrieved file status flags.  In the GNU
system, you can just test the `O_READ' and `O_WRITE' bits in the flags
word.  But in other POSIX.1 systems, reading and writing access modes
are not stored as distinct bit flags.  The portable way to extract the
file access mode bits is with `O_ACCMODE'.

 - Macro: int O_ACCMODE
     This macro stands for a mask that can be bitwise-ANDed with the
     file status flag value to produce a value representing the file
     access mode.  The mode will be `O_RDONLY', `O_WRONLY', or `O_RDWR'.
     (In the GNU system it could also be zero, and it never includes the
     `O_EXEC' bit.)


File: libc.info,  Node: Open-time Flags,  Next: Operating Modes,  Prev: Access Modes,  Up: File Status Flags

Open-time Flags
---------------

   The open-time flags specify options affecting how `open' will behave.
These options are not preserved once the file is open.  The exception to
this is `O_NONBLOCK', which is also an I/O operating mode and so it
_is_ saved.  *Note Opening and Closing Files::, for how to call `open'.

   There are two sorts of options specified by open-time flags.

   * "File name translation flags" affect how `open' looks up the file
     name to locate the file, and whether the file can be created.

   * "Open-time action flags" specify extra operations that `open' will
     perform on the file once it is open.

   Here are the file name translation flags.

 - Macro: int O_CREAT
     If set, the file will be created if it doesn't already exist.

 - Macro: int O_EXCL
     If both `O_CREAT' and `O_EXCL' are set, then `open' fails if the
     specified file already exists.  This is guaranteed to never
     clobber an existing file.

 - Macro: int O_NONBLOCK
     This prevents `open' from blocking for a "long time" to open the
     file.  This is only meaningful for some kinds of files, usually
     devices such as serial ports; when it is not meaningful, it is
     harmless and ignored.  Often opening a port to a modem blocks
     until the modem reports carrier detection; if `O_NONBLOCK' is
     specified, `open' will return immediately without a carrier.

     Note that the `O_NONBLOCK' flag is overloaded as both an I/O
     operating mode and a file name translation flag.  This means that
     specifying `O_NONBLOCK' in `open' also sets nonblocking I/O mode;
     *note Operating Modes::.  To open the file without blocking but do
     normal I/O that blocks, you must call `open' with `O_NONBLOCK' set
     and then call `fcntl' to turn the bit off.

 - Macro: int O_NOCTTY
     If the named file is a terminal device, don't make it the
     controlling terminal for the process.  *Note Job Control::, for
     information about what it means to be the controlling terminal.

     In the GNU system and 4.4 BSD, opening a file never makes it the
     controlling terminal and `O_NOCTTY' is zero.  However, other
     systems may use a nonzero value for `O_NOCTTY' and set the
     controlling terminal when you open a file that is a terminal
     device; so to be portable, use `O_NOCTTY' when it is important to
     avoid this.

   The following three file name translation flags exist only in the
GNU system.

 - Macro: int O_IGNORE_CTTY
     Do not recognize the named file as the controlling terminal, even
     if it refers to the process's existing controlling terminal
     device.  Operations on the new file descriptor will never induce
     job control signals.  *Note Job Control::.

 - Macro: int O_NOLINK
     If the named file is a symbolic link, open the link itself instead
     of the file it refers to.  (`fstat' on the new file descriptor will
     return the information returned by `lstat' on the link's name.)

 - Macro: int O_NOTRANS
     If the named file is specially translated, do not invoke the
     translator.  Open the bare file the translator itself sees.

   The open-time action flags tell `open' to do additional operations
which are not really related to opening the file.  The reason to do them
as part of `open' instead of in separate calls is that `open' can do
them atomically.

 - Macro: int O_TRUNC
     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
     `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 `open',
     instead of by calling `ftruncate' afterwards.  The `O_TRUNC' flag
     existed in Unix before `ftruncate' was invented, and is retained
     for backward compatibility.

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

 - Macro: int O_SHLOCK
     Acquire a shared lock on the file, as with `flock'.  *Note File
     Locks::.

     If `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.

 - Macro: int O_EXLOCK
     Acquire an exclusive lock on the file, as with `flock'.  *Note
     File Locks::.  This is atomic like `O_SHLOCK'.


File: libc.info,  Node: Operating Modes,  Next: Getting File Status Flags,  Prev: Open-time Flags,  Up: File Status Flags

I/O Operating Modes
-------------------

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

 - Macro: int O_APPEND
     The bit that enables append mode for the file.  If set, then all
     `write' operations write the data at the end of the file, extending
     it, regardless of the current file position.  This is the only
     reliable way to append to a file.  In append mode, you are
     guaranteed that the data you write will always go to the current
     end of the file, regardless of other processes writing to the
     file.  Conversely, if you simply set the file position to the end
     of file and write, then another process can extend the file after
     you set the file position but before you write, resulting in your
     data appearing someplace before the real end of file.

 - Macro: int O_NONBLOCK
     The bit that enables nonblocking mode for the file.  If this bit
     is set, `read' requests on the file can return immediately with a
     failure status if there is no input immediately available, instead
     of blocking.  Likewise, `write' requests can also return
     immediately with a failure status if the output can't be written
     immediately.

     Note that the `O_NONBLOCK' flag is overloaded as both an I/O
     operating mode and a file name translation flag; *note Open-time
     Flags::.

 - Macro: int O_NDELAY
     This is an obsolete name for `O_NONBLOCK', provided for
     compatibility with BSD.  It is not defined by the POSIX.1 standard.

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

 - Macro: int O_ASYNC
     The bit that enables asynchronous input mode.  If set, then `SIGIO'
     signals will be generated when input is available.  *Note
     Interrupt Input::.

     Asynchronous input mode is a BSD feature.

 - Macro: int O_FSYNC
     The bit that enables synchronous writing for the file.  If set,
     each `write' call will make sure the data is reliably stored on
     disk before returning.  Synchronous writing is a BSD feature.

 - Macro: int O_SYNC
     This is another name for `O_FSYNC'.  They have the same value.

 - Macro: int O_NOATIME
     If this bit is set, `read' will not update the access time of the
     file.  *Note File Times::.  This is used by programs that do
     backups, so that backing a file up does not count as reading it.
     Only the owner of the file or the superuser may use this bit.

     This is a GNU extension.


File: libc.info,  Node: Getting File Status Flags,  Prev: Operating Modes,  Up: File Status Flags

Getting and Setting File Status Flags
-------------------------------------

   The `fcntl' function can fetch or change file status flags.

 - Macro: int F_GETFL
     This macro is used as the COMMAND argument to `fcntl', to read the
     file status flags for the open file with descriptor FILEDES.

     The normal return value from `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 `O_ACCMODE' to compare them.

     In case of an error, `fcntl' returns -1.  The following `errno'
     error conditions are defined for this command:

    `EBADF'
          The FILEDES argument is invalid.

 - Macro: int F_SETFL
     This macro is used as the COMMAND argument to `fcntl', to set the
     file status flags for the open file corresponding to the FILEDES
     argument.  This command requires a third `int' argument to specify
     the new flags, so the call looks like this:

          fcntl (FILEDES, F_SETFL, NEW-FLAGS)

     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 `fcntl' with this command is an
     unspecified value other than -1, which indicates an error.  The
     error conditions are the same as for the `F_GETFL' command.

   If you want to modify the file status flags, you should get the
current flags with `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 `O_NONBLOCK'
without altering any other flags:

     /* Set the `O_NONBLOCK' flag of DESC if VALUE is nonzero,
        or clear the flag if VALUE is 0.
        Return 0 on success, or -1 on error with `errno' set. */
     
     int
     set_nonblock_flag (int desc, int value)
     {
       int oldflags = fcntl (desc, F_GETFL, 0);
       /* If reading the flags failed, return error indication now. */
       if (oldflags == -1)
         return -1;
       /* Set just the flag we want to set. */
       if (value != 0)
         oldflags |= O_NONBLOCK;
       else
         oldflags &= ~O_NONBLOCK;
       /* Store modified flag word in the descriptor. */
       return fcntl (desc, F_SETFL, oldflags);
     }


File: libc.info,  Node: File Locks,  Next: Interrupt Input,  Prev: File Status Flags,  Up: Low-Level I/O

File Locks
==========

   The remaining `fcntl' commands are used to support "record locking",
which permits multiple cooperating programs to prevent each other from
simultaneously accessing parts of a file in error-prone ways.

   An "exclusive" or "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.

   A "shared" or "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 `read' and `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 `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 `fork' (*note Creating a Process::).

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

 - Data Type: struct flock
     This structure is used with the `fcntl' function to describe a file
     lock.  It has these members:

    `short int l_type'
          Specifies the type of the lock; one of `F_RDLCK', `F_WRLCK',
          or `F_UNLCK'.

    `short int l_whence'
          This corresponds to the WHENCE argument to `fseek' or
          `lseek', and specifies what the offset is relative to.  Its
          value can be one of `SEEK_SET', `SEEK_CUR', or `SEEK_END'.

    `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 `l_whence' member.

    `off_t l_len'
          This specifies the length of the region to be locked.  A
          value of `0' is treated specially; it means the region
          extends to the end of the file.

    `pid_t l_pid'
          This field is the process ID (*note Process Creation
          Concepts::) of the process holding the lock.  It is filled in
          by calling `fcntl' with the `F_GETLK' command, but is ignored
          when making a lock.

 - Macro: int F_GETLK
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should get information about a lock.  This command
     requires a third argument of type `struct flock *' to be passed to
     `fcntl', so that the form of the call is:

          fcntl (FILEDES, F_GETLK, LOCKP)

     If there is a lock already in place that would block the lock
     described by the LOCKP argument, information about that lock
     overwrites `*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 `F_WRLCK' if you want to find out about both
     read and write locks, or `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 LOCKP argument, but `fcntl' only returns information about
     one of them.  The `l_whence' member of the LOCKP structure is set
     to `SEEK_SET' and the `l_start' and `l_len' fields set to identify
     the locked region.

     If no lock applies, the only change to the LOCKP structure is to
     update the `l_type' to a value of `F_UNLCK'.

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

    `EBADF'
          The FILEDES argument is invalid.

    `EINVAL'
          Either the LOCKP argument doesn't specify valid lock
          information, or the file associated with FILEDES doesn't
          support locks.

 - Macro: int F_SETLK
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set or clear a lock.  This command requires a third
     argument of type `struct flock *' to be passed to `fcntl', so that
     the form of the call is:

          fcntl (FILEDES, F_SETLK, LOCKP)

     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 `F_UNLCK'.

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

     The following `errno' error conditions are defined for this
     function:

    `EAGAIN'
    `EACCES'
          The lock cannot be set because it is blocked by an existing
          lock on the file.  Some systems use `EAGAIN' in this case,
          and other systems use `EACCES'; your program should treat
          them alike, after `F_SETLK'.  (The GNU system always uses
          `EAGAIN'.)

    `EBADF'
          Either: the FILEDES argument is invalid; you requested a read
          lock but the FILEDES is not open for read access; or, you
          requested a write lock but the FILEDES is not open for write
          access.

    `EINVAL'
          Either the LOCKP argument doesn't specify valid lock
          information, or the file associated with FILEDES doesn't
          support locks.

    `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 this error, as
          it could result from network access to a file system on
          another machine.

 - Macro: int F_SETLKW
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set or clear a lock.  It is just like the `F_SETLK'
     command, but causes the process to block (or wait) until the
     request can be specified.

     This command requires a third argument of type `struct flock *', as
     for the `F_SETLK' command.

     The `fcntl' return values and errors are the same as for the
     `F_SETLK' command, but these additional `errno' error conditions
     are defined for this command:

    `EINTR'
          The function was interrupted by a signal while it was waiting.
          *Note Interrupted Primitives::.

    `EDEADLK'
          The specified region is being locked by another process.  But
          that process is waiting to lock a region which the current
          process has locked, so waiting for the lock would result in
          deadlock.  The system does not guarantee that it will detect
          all such conditions, but it lets you know if it notices one.

   The following macros are defined for use as values for the `l_type'
member of the `flock' structure.  The values are integer constants.

`F_RDLCK'
     This macro is used to specify a read (or shared) lock.

`F_WRLCK'
     This macro is used to specify a write (or exclusive) lock.

`F_UNLCK'
     This macro is used to specify that the region is unlocked.

   As an example of a situation where file locking is useful, consider a
program that can be run simultaneously by several different users, that
logs status information to a common file.  One example of such a program
might be a game that uses a file to keep track of high scores.  Another
example might be a program that records usage or accounting information
for billing purposes.

   Having multiple copies of the program simultaneously writing to the
file could cause the contents of the file to become mixed up.  But you
can prevent this kind of problem by setting a write lock on the file
before actually writing to the file.

   If the program also needs to read the file and wants to make sure
that the contents of the file are in a consistent state, then it can
also use a read lock.  While the read lock is set, no other process can
lock that part of the file for writing.

   Remember that file locks are only a _voluntary_ protocol for
controlling access to a file.  There is still potential for access to
the file by programs that don't use the lock protocol.


File: libc.info,  Node: Interrupt Input,  Next: IOCTLs,  Prev: File Locks,  Up: Low-Level I/O

Interrupt-Driven Input
======================

   If you set the `O_ASYNC' status flag on a file descriptor (*note
File Status Flags::), a `SIGIO' signal is sent whenever input or output
becomes possible on that file descriptor.  The process or process group
to receive the signal can be selected by using the `F_SETOWN' command
to the `fcntl' function.  If the file descriptor is a socket, this also
selects the recipient of `SIGURG' signals that are delivered when
out-of-band data arrives on that socket; see *Note Out-of-Band Data::.
(`SIGURG' is sent in any situation where `select' would report the
socket as having an "exceptional condition".  *Note Waiting for I/O::.)

   If the file descriptor corresponds to a terminal device, then `SIGIO'
signals are sent to the foreground process group of the terminal.
*Note Job Control::.

   The symbols in this section are defined in the header file `fcntl.h'.

 - Macro: int F_GETOWN
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should get information about the process or process group
     to which `SIGIO' signals are sent.  (For a terminal, this is
     actually the foreground process group ID, which you can get using
     `tcgetpgrp'; see *Note Terminal Access Functions::.)

     The return value is interpreted as a process ID; if negative, its
     absolute value is the process group ID.

     The following `errno' error condition is defined for this command:

    `EBADF'
          The FILEDES argument is invalid.

 - Macro: int F_SETOWN
     This macro is used as the COMMAND argument to `fcntl', to specify
     that it should set the process or process group to which `SIGIO'
     signals are sent.  This command requires a third argument of type
     `pid_t' to be passed to `fcntl', so that the form of the call is:

          fcntl (FILEDES, F_SETOWN, PID)

     The PID argument should be a process ID.  You can also pass a
     negative number whose absolute value is a process group ID.

     The return value from `fcntl' with this command is -1 in case of
     error and some other value if successful.  The following `errno'
     error conditions are defined for this command:

    `EBADF'
          The FILEDES argument is invalid.

    `ESRCH'
          There is no process or process group corresponding to PID.


File: libc.info,  Node: IOCTLs,  Prev: Interrupt Input,  Up: Low-Level I/O

Generic I/O Control operations
==============================

   The GNU system can handle most input/output operations on many
different devices and objects in terms of a few file primitives -
`read', `write' and `lseek'.  However, most devices also have a few
peculiar operations which do not fit into this model. Such as:

   * Changing the character font used on a terminal.

   * Telling a magnetic tape system to rewind or fast forward.  (Since
     they cannot move in byte increments, `lseek' is inapplicable).

   * Ejecting a disk from a drive.

   * Playing an audio track from a CD-ROM drive.

   * Maintaining routing tables for a network.


   Although some such objects such as sockets and terminals (1) have
special functions of their own, it would not be practical to create
functions for all these cases.

   Instead these minor operations, known as "IOCTL"s, are assigned code
numbers and multiplexed through the `ioctl' function, defined in
`sys/ioctl.h'.  The code numbers themselves are defined in many
different headers.

 - Function: int ioctl (int FILEDES, int COMMAND, ...)
     The `ioctl' function performs the generic I/O operation COMMAND on
     FILEDES.

     A third argument is usually present, either a single number or a
     pointer to a structure.  The meaning of this argument, the
     returned value, and any error codes depends upon the command used.
     Often -1 is returned for a failure.


   On some systems, IOCTLs used by different devices share the same
numbers.  Thus, although use of an inappropriate IOCTL _usually_ only
produces an error, you should not attempt to use device-specific IOCTLs
on an unknown device.

   Most IOCTLs are OS-specific and/or only used in special system
utilities, and are thus beyond the scope of this document.  For an
example of the use of an IOCTL, see *Note Out-of-Band Data::.

   ---------- Footnotes ----------

   (1) Actually, the terminal-specific functions are implemented with
IOCTLs on many platforms.

