FCNTL(2)                         System Calls                         FCNTL(2)




NAME

       fcntl - file control


SYNOPSIS

       #include <fcntl.h>

       int fcntl (int fd, int cmd, ... /* int arg */ );


DESCRIPTION

       See the BUGS section for caveats on the GNO implementation.

       Fcntl  provides  for  control  over  descriptors.  The argument fd is a
       descriptor to be operated on by cmd as follows:

              F_DUPFD
                     Return a new descriptor as follows:

                     Lowest numbered  available  descriptor  greater  than  or
                     equal to arg.

                     Same object references as the original descriptor.

                     New  descriptor shares the same file offset if the object
                     was a file.

                     Same access mode (read, write or read/write).

                     Same file status flags (i.e., both file descriptors share
                     the same file status flags).

                     The  close-on-exec  flag  associated  with  the  new file
                     descriptor is set to remain open across execve(2)  system
                     calls.

              F_GETFD
                     Get  the  close-on-exec  flag  associated  with  the file
                     descriptor fd.  If the  low-order  bit  of  the  returned
                     value is 0, the file will remain open across exec, other-
                     wise the file will be closed upon execution of exec  (arg
                     is ignored).

              F_SETFD
                     Set  the close-on-exec flag associated with fd to the low
                     order bit of arg (0 or 1 as above).

              F_GETFL
                     Get descriptor status flags, as described below  (arg  is
                     ignored).

              F_SETFL
                     Set descriptor status flags to arg.

              F_GETOWN
                     Get  the  process ID or process group currently receiving
                     SIGIO and SIGURG signals; process groups are returned  as
                     negative values (arg is ignored).

              F_SETOWN
                     Set  the  process  or  process group to receive SIGIO and
                     SIGURG signals; process groups are specified by supplying
                     arg  as  negative, otherwise arg is interpreted as a pro-
                     cess ID.

       The flags for the F_GETFL and F_SETFL flags are as follows:

              O_NONBLOCK
                     Non-blocking I/O; if no data is available  to  a  read(2)
                     call, or if a write(2) operation would block, the read or
                     write call returns -1 with the error EAGAIN.

              O_APPEND
                     Force each write to append at the  end  of  file;  corre-
                     sponds to the O_APPEND flag of open(2).

              O_ASYNC
                     Enable  the  SIGIO signal to be sent to the process group
                     when I/O is possible, e.g., upon availability of data  to
                     be read.

       Several  commands  are  available for doing advisory file locking; they
       all operate on the following structure:
       struct flock {
            off_t     l_start;  /* starting offset */
            off_t     l_len;         /* len = 0 means until end of file */
            pid_t     l_pid;         /* lock owner */
            short     l_type;        /* lock type: read/write, etc. */
            short     l_whence; /* type of l_start */
       };
       The commands available for advisory record locking are as follows:

              F_GETLK
                     Get the first  lock  that  blocks  the  lock  description
                     pointed to by the third argument, arg, taken as a pointer
                     to a struct flock (see above).  The information retrieved
                     overwrites  the  information passed to fcntl in the flock
                     structure.  If no lock is found that would  prevent  this
                     lock  from being created, the structure is left unchanged
                     by this function call except for the lock type  which  is
                     set to F_UNLCK.

              F_SETLK
                     Set  or  clear  a file segment lock according to the lock
                     description pointed to by the third argument, arg,  taken
                     as  a  pointer to a struct flock (see above).  F_SETLK is
                     used to establish shared (or  read)  locks  (F_RDLCK)  or
                     exclusive  (or write) locks, (F_WRLCK), as well as remove
                     either type of lock (F_UNLCK).  If a shared or  exclusive
                     lock  cannot  be set, fcntl returns immediately with EAC-
                     CES.

              F_SETLKW
                     This command is the same as  F_SETLK  except  that  if  a
                     shared  or  exclusive lock is blocked by other locks, the
                     process waits until the request can be satisfied.   If  a
                     signal  that  is  to be caught is received while fcntl is
                     waiting for a region, the fcntl will  be  interrupted  if
                     the  signal handler has not specified the SA_RESTART (see
                     sigaction(2)).

       When a shared lock has been set on a segment of a file, other processes
       can set shared locks on that segment or a portion of it.  A shared lock
       prevents any other process from setting an exclusive lock on  any  por-
       tion  of  the protected area.  A request for a shared lock fails if the
       file descriptor was not opened with read access.

       An exclusive lock prevents any other process from setting a shared lock
       or  an  exclusive lock on any portion of the protected area.  A request
       for an exclusive lock fails if the  file  was  not  opened  with  write
       access.

       The  value  of  l_whence is SEEK_SET, SEEK_CUR, or SEEK_END to indicate
       that the relative offset, l_start bytes,  will  be  measured  from  the
       start  of the file, current position, or end of the file, respectively.
       The value of l_len is the number of consecutive bytes to be locked.  If
       l_len  is  negative,  the result is undefined.  The l_pid field is only
       used with F_GETLK to return the process ID of  the  process  holding  a
       blocking  lock.   After  a  successful  F_GETLK  request,  the value of
       l_whence is SEEK_SET.

       Locks may start and extend beyond the current end of a  file,  but  may
       not start or extend before the beginning of the file.  A lock is set to
       extend to the largest possible value of the file offset for  that  file
       if l_len is set to zero. If l_whence and l_start point to the beginning
       of the file, and l_len is zero, the  entire  file  is  locked.   If  an
       application  wishes only to do entire file locking, the flock(2) system
       call is much more efficient.

       There is at most one type of lock  set  for  each  byte  in  the  file.
       Before  a successful return from an F_SETLK or an F_SETLKW request when
       the calling process has previously  existing  locks  on  bytes  in  the
       region  specified  by the request, the previous lock type for each byte
       in the specified region is replaced by the new lock type.  As specified
       above  under  the  descriptions of shared locks and exclusive locks, an
       F_SETLK or an  F_SETLKW  request  fails  or  blocks  respectively  when
       another process has existing locks on bytes in the specified region and
       the type of any of those locks conflicts with the type specified in the
       request.

       This  interface follows the completely stupid semantics of System V and
       POSIX 1003.1-88 that require that all locks associated with a file  for
       a  given  process are removed when any file descriptor for that file is
       closed by that process.  This semantic means that applications must  be
       aware  of  any files that a subroutine library may access.  For example
       if an application for updating the password  file  locks  the  password
       file  database  while  making the update, and then calls getpwnam(3) to
       retrieve a record, the lock will be  lost  because  getpwnam(3)  opens,
       reads,  and  closes  the  password  database.   The database close will
       release all locks that the process has associated  with  the  database,
       even  if  the  library  routine never requested a lock on the database.
       Another minor semantic problem with this interface is  that  locks  are
       not  inherited  by  a child process created using the fork(2) function.
       The flock(2) interface has much more rational last close semantics  and
       allows  locks  to  be inherited by child processes.  Flock(2) is recom-
       mended for applications that want to  ensure  the  integrity  of  their
       locks  when using library routines or wish to pass locks to their chil-
       dren.  Note that flock(2) and fcntl(2) locks may be safely used concur-
       rently.

       All  locks  associated with a file for a given process are removed when
       the process terminates.

       A potential for deadlock occurs  if  a  process  controlling  a  locked
       region  is  put  to  sleep  by  attempting to lock the locked region of
       another process.  This implementation detects  that  sleeping  until  a
       locked  region  is  unlocked  would  cause a deadlock and fails with an
       EDEADLK error.


IMPLEMENTATION NOTES

       In the non-threaded library fcntl is implemented as the fcntl  syscall.

       In   the   threaded   library,   the  fcntl  syscall  is  assembled  to
       _thread_sys_fcntl and fcntl is implemented as a function which disables
       thread   rescheduling,   locks  fd  for  read  and  write,  then  calls
       _thread_sys_fcntl.  Before returning,  fcntl  unlocks  fd  and  enables
       thread rescheduling.


RETURN VALUES

       Upon  successful  completion, the value returned depends on cmd as fol-
       lows:

              F_DUPFD
                     A new file descriptor.

              F_GETFD
                     Value of flag (only the low-order bit is defined).

              F_GETFL
                     Value of flags.

              F_GETOWN
                     Value of file descriptor owner.

              other  Value other than -1.

       Otherwise, a value of -1 is returned and errno is set to  indicate  the
       error.


ERRORS

       Fcntl will fail if:

              EACCES The argument arg is F_SETLK, the type of lock (l_type) is
                     a shared lock (F_RDLCK) or exclusive lock (F_WRLCK),  and
                     the  segment of a file to be locked is already exclusive-
                     locked by another process; or the type  is  an  exclusive
                     lock  and  some  portion  of  the segment of a file to be
                     locked is already shared-locked  or  exclusive-locked  by
                     another process.

              EBADF  Fildes is not a valid open file descriptor.

              The  argument  cmd  is  F_SETLK  or  F_SETLKW,  the type of lock
              (l_type) is a shared lock (F_RDLCK), and fildes is not  a  valid
              file descriptor open for reading.

              The  argument  cmd  is  F_SETLK  or  F_SETLKW,  the type of lock
              (l_type) is an exclusive lock (F_WRLCK), and  fildes  is  not  a
              valid file descriptor open for writing.

              EDEADLK
                     The  argument  cmd  is F_SETLKW, and a deadlock condition
                     was detected.

              EINTR  The argument cmd is F_SETLKW, and the function was inter-
                     rupted by a signal.

              EINVAL Cmd  is  F_DUPFD  and arg is negative or greater than the
                     maximum allowable number (see getdtablesize(2)).

              The argument cmd is F_GETLK, F_SETLK, or F_SETLKW, and the  data
              to  which  arg  points  is not valid, or fildes refers to a file
              that does not support locking.

              EMFILE The argument cmd is F_DUPFD and  the  maximum  number  of
                     file descriptors permitted for the process are already in
                     use, or no file descriptors greater than or equal to  arg
                     are available.

              ENOLCK The  argument  cmd is F_SETLK or F_SETLKW, and satisfying
                     the lock or unlock request would result in the number  of
                     locked  regions  in the system exceeding a system-imposed
                     limit.

              ESRCH  Cmd is F_SETOWN and the process ID given as  argument  is
                     not in use.

       In addition, if fd refers to a descriptor open on a terminal device (as
       opposed to a descriptor open on a socket), a cmd of F_SETOWN  can  fail
       for  the same reasons as in tcsetpgrp(3), and a cmd of F_GETOWN for the
       reasons as stated in tcgetpgrp(3).


BUGS

       Currently, the only cmds used by the GNO implementation are F_DUPFD and
       F_GETFL.   Any  other  values  will result in an error and set errno to
       EINVAL.


SEE ALSO

       close(2), execve(2), flock(2),  getdtablesize(2),  open(2),  sigvec(2),
       tcgetpgrp(3), tcsetpgrp(3)


HISTORY

       The fcntl function call appeared in 4.2BSD.



GNO                            15 September 1997                      FCNTL(2)

Man(1) output converted with man2html