DESCRIPTION

     fcntl performs one of various  miscellaneous  operations  on
     fd.  The operation in question is determined by cmd:

     F_DUPFD  Makes arg be a copy of  fd,  closing  fd  first  if
              necessary.

              The same functionality can be more easily  achieved
              by using dup2(2).

              The old and new  descriptors  may  be  used  inter-
              changeably.   They   share   locks,  file  position
              pointers and flags; for example, if the file  posi-
              tion  is  modified  by  using  lseek  on one of the
              descriptors, the position is also changed  for  the
              other.

              The two descriptors do not share the  close-on-exec
              flag,  however.  The close-on-exec flag of the copy
              is off, meaning that it will be closed on exec.

              On success, the new descriptor is returned.

     F_GETFD  Read the close-on-exec flag.  If the low-order  bit
              is 0, the file will remain open across exec, other-
              wise it will be closed.

     F_SETFD  Set the close-on-exec flag to the  value  specified
              by arg (only the least significant bit is used).


     F_GETFL  Read the descriptor's flags (all flags (as  set  by
              open(2)) are returned).

     F_SETFL  Set the descriptor's flags to the  value  specified
              by arg.  Only O_APPEND and O_NONBLOCK may be set.

              The flags are shared between copies (made with  dup
              etc.) of the same file descriptor.

              The flags and  their  semantics  are  described  in
              open(2).

     F_GETLK, F_SETLK and F_SETLKW
              Manage discretionary file locks.  The  third  argu-
              ment  arg  is a pointer to a struct flock (that may
              be overwritten by this call).

     F_GETLK  Return the flock structure that  prevents  us  from
              obtaining  the lock, or set the l_type field of the
              lock to F_UNLCK if there is no obstruction.

     F_SETLK  The lock is set (when l_type is F_RDLCK or F_WRLCK)
              or  cleared  (when  it is F_UNLCK).  If the lock is
              held by someone else, this call returns -1 and sets
              errno to EACCES or EAGAIN.

     F_SETLKW Like F_SETLK, but instead of returning an error  we
              wait for the lock to be released.  If a signal that
              is to be caught is received while fcntl() is  wait-
              ing,  it  is  interrupted  and  returns immediately
              (with return value -1 and errno set to EINTR).

     F_GETOWN Get the  process  ID  or  process  group  currently
              receiving  SIGIO  and  SIGURG signals for events on
              file descriptor fd.  Process groups are returned as
              negative values.

     F_SETOWN Set the process  ID  or  process  group  that  will
              receive SIGIO and SIGURG signals for events on file
              descriptor fd.  Process groups are specified  using
              negative values.

              If you set  the  O_ASYNC  status  flag  on  a  file
              descriptor  (either by providing this flag with the
              open call, or  by  using  the  F_SETFL  command  of
              fcntl),  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.  (SIGURG  is  sent  in  any
              situation  where  select would report the socket as
              having an "exceptional condition".)   If  the  file
              descriptor  corresponds  to a terminal device, then
              SIGIO signals are sent to  the  foreground  process
              group of the terminal.

              The use of  O_ASYNC,  F_GETOWN,  F_SETOWN  is  BSD-
              specific.   POSIX  has  asynchronous  I/O  and  the
              aio_sigevent structure to achieve similar things.

RETURN VALUE

     For a successful call,  the  return  value  depends  on  the
     operation:

     F_DUPFD  The new descriptor.

     F_GETFD  Value of flag.

     F_GETFL  Value of flags.

     F_GETOWN Value of descriptor owner.

     F_SETFD, F_SETFL, F_GETLK, F_SETLK, F_SETLKW Some value dif-
              ferent from -1.

     On error, -1 is returned, and errno is set appropriately.

ERRORS

     EACCES   Operation is prohibited  by  locks  held  by  other
              processes.

     EAGAIN   Operation is prohibited because the file  has  been
              memory-mapped by another process.

     EDEADLK  It was detected that the specified F_SETLKW command
              would cause a deadlock.

     EBADF    fd is not an open file descriptor.

     EINTR    The F_SETLKW command was interrupted by a signal.

     EINVAL   For F_DUPFD, arg is negative or is greater than the
              maximum allowable value.

     EMFILE   For F_DUPFD, the process already  has  the  maximum
              number of file descriptors open.

     ENOLCK   Too many segment locks open, lock table is full.

NOTES

     The  errors  returned  by  dup2  are  different  from  those
     returned by F_DUPFD.

CONFORMING TO

     SVr4, SVID, POSIX, X/OPEN, BSD  4.3.   Only  the  operations
     F_DUPFD,   F_GETFD,   F_SETFD,  F_GETFL,  F_SETFL,  F_GETLK,
     F_SETLK and F_SETLKW are specified in POSIX.1; F_GETOWN  and
     F_SETOWN  are BSDisms not supported in SVr4. The flags legal
     for F_GETFL/F_SETFL are those supported by open(2) and  vary
     between  these  systems; O_APPEND, O_NONBLOCK, O_RDONLY, and
     O_RDWR are specified  in  POSIX.1.   SVr4  supports  several
     other options and flags not documented here.
     POSIX.1 documents an additional EINTR condition.  SVr4 docu-
     ments  additional  EFAULT, EINTR, EIO, ENOLINK and EOVERFLOW
     error conditions.

SEE ALSO

     dup2(2), open(2), socket(2), flock(2)