Man Linux: Main Page and Category List

NAME

       fcntl - file control

SYNOPSIS

       #include <unistd.h>
       #include <fcntl.h>

       int fcntl(int fildes, int cmd, ...);

DESCRIPTION

       The  fcntl()  function  shall perform the operations described below on
       open files. The fildes argument is a file descriptor.

       The available values for cmd  are  defined  in  <fcntl.h>  and  are  as
       follows:

       F_DUPFD
              Return  a new file descriptor which shall be the lowest numbered
              available (that is, not already open)  file  descriptor  greater
              than or equal to the third argument, arg, taken as an integer of
              type int. The new file descriptor shall refer to the  same  open
              file  description  as  the  original  file descriptor, and shall
              share any locks. The FD_CLOEXEC flag  associated  with  the  new
              file  descriptor  shall  be cleared to keep the file open across
              calls to one of the exec functions.

       F_GETFD
              Get the file descriptor flags  defined  in  <fcntl.h>  that  are
              associated  with  the  file  descriptor  fildes. File descriptor
              flags are associated with a single file descriptor  and  do  not
              affect other file descriptors that refer to the same file.

       F_SETFD
              Set  the  file  descriptor  flags defined in <fcntl.h>, that are
              associated with fildes, to the third  argument,  arg,  taken  as
              type int. If the FD_CLOEXEC flag in the third argument is 0, the
              file shall remain open across the exec functions; otherwise, the
              file  shall  be  closed  upon successful execution of one of the
              exec functions.

       F_GETFL
              Get the file status flags and  file  access  modes,  defined  in
              <fcntl.h>,  for the file description associated with fildes. The
              file access modes can be extracted from the return  value  using
              the  mask  O_ACCMODE, which is defined in <fcntl.h>. File status
              flags and  file  access  modes  are  associated  with  the  file
              description  and do not affect other file descriptors that refer
              to the same file with different open file descriptions.

       F_SETFL
              Set the file status flags, defined in <fcntl.h>,  for  the  file
              description  associated  with fildes from the corresponding bits
              in  the  third  argument,  arg,  taken   as   type   int.   Bits
              corresponding  to  the  file  access  mode and the file creation
              flags, as defined in <fcntl.h>, that are set  in  arg  shall  be
              ignored.  If any bits in arg other than those mentioned here are
              changed by the application, the result is unspecified.

       F_GETOWN
              If fildes refers to a socket, get the process or  process  group
              ID  specified to receive SIGURG signals when out-of-band data is
              available. Positive  values  indicate  a  process  ID;  negative
              values,  other  than  -1, indicate a process group ID. If fildes
              does not refer to a socket, the results are unspecified.

       F_SETOWN
              If fildes refers to a socket, set the process or  process  group
              ID  specified to receive SIGURG signals when out-of-band data is
              available, using the value of the third argument, arg, taken  as
              type  int.  Positive  values  indicate  a  process  ID; negative
              values, other than -1, indicate a process group  ID.  If  fildes
              does not refer to a socket, the results are unspecified.

       The following values for cmd are available for advisory record locking.
       Record locking shall  be  supported  for  regular  files,  and  may  be
       supported for other files.

       F_GETLK
              Get  the first lock which blocks the lock description pointed to
              by the third argument, arg, taken as a pointer  to  type  struct
              flock,  defined  in  <fcntl.h>.  The information retrieved shall
              overwrite the information passed to  fcntl()  in  the  structure
              flock.  If  no  lock  is found that would prevent this lock from
              being created, then the structure shall be left unchanged except
              for the lock type which shall be 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 type struct flock, defined in <fcntl.h>. F_SETLK can
              establish shared (or read)  locks  (F_RDLCK)  or  exclusive  (or
              write) locks (F_WRLCK), as well as to remove either type of lock
              (F_UNLCK).  F_RDLCK,  F_WRLCK,  and  F_UNLCK  are   defined   in
              <fcntl.h>.  If a shared or exclusive lock cannot be set, fcntl()
              shall return immediately with a return value of -1.

       F_SETLKW
              This command shall be equivalent to F_SETLK  except  that  if  a
              shared  or  exclusive lock is blocked by other locks, the thread
              shall wait until the request can be satisfied. If a signal  that
              is  to  be  caught  is  received  while fcntl() is waiting for a
              region, fcntl() shall  be  interrupted.  Upon  return  from  the
              signal  handler,  fcntl()  shall  return  -1  with  errno set to
              [EINTR], and the lock operation shall not be done.

       Additional implementation-defined values for  cmd  may  be  defined  in
       <fcntl.h>. Their names shall start with F_.

       When a shared lock is set on a segment of a file, other processes shall
       be able to 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 portion of the protected area. A request for a shared lock shall
       fail if the file descriptor was not opened with read access.

       An exclusive lock shall prevent 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 shall fail if the file descriptor was not
       opened with write access.

       The structure flock describes the type (  l_type),  starting  offset  (
       l_whence),  relative offset ( l_start), size ( l_len), and process ID (
       l_pid) of the segment of the file to be affected.

       The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END,  to  indicate
       that the relative offset l_start bytes shall 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. The
       value of l_len may be negative (where the definition of  off_t  permits
       negative values of l_len). 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, when a blocking lock is found, the values
       returned in the flock structure shall be as follows:

       l_type Type of blocking lock found.

       l_whence
              SEEK_SET.

       l_start
              Start of the blocking lock.

       l_len  Length of the blocking lock.

       l_pid  Process ID of the process that holds the blocking lock.

       If the command is F_SETLKW  and  the  process  must  wait  for  another
       process  to  release a lock, then the range of bytes to be locked shall
       be determined before the fcntl() function blocks. If the file  size  or
       file descriptor seek offset change while fcntl() is blocked, this shall
       not affect the range of bytes locked.

       If l_len is positive, the area affected shall start at l_start and  end
       at  l_start+  l_len-1.  If  l_len  is negative, the area affected shall
       start at l_start+ l_len and end  at  l_start-1.  Locks  may  start  and
       extend  beyond  the  current end of a file, but shall not extend before
       the beginning of the file. A lock shall be set to extend to the largest
       possible  value of the file offset for that file by setting l_len to 0.
       If such a lock also has l_start  set  to  0  and  l_whence  is  set  to
       SEEK_SET, the whole file shall be locked.

       There  shall be 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  shall  be 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 (respectively) shall fail or
       block 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.

       All locks associated with a file for a given process shall  be  removed
       when  a  file descriptor for that file is closed by that process or the
       process  holding  that  file  descriptor  terminates.  Locks  are   not
       inherited by a child process.

       A  potential  for  deadlock  occurs  if  a process controlling a locked
       region is put to sleep by attempting to lock  another  process’  locked
       region.  If  the  system detects that sleeping until a locked region is
       unlocked would cause a deadlock, fcntl() shall fail with  an  [EDEADLK]
       error.

       An  unlock  (F_UNLCK) request in which l_len is non-zero and the offset
       of the last byte of the requested segment is the maximum value  for  an
       object  of  type  off_t, when the process has an existing lock in which
       l_len is 0 and which includes the last byte of the  requested  segment,
       shall be treated as a request to unlock from the start of the requested
       segment with an l_len  equal  to  0.  Otherwise,  an  unlock  (F_UNLCK)
       request shall attempt to unlock only the requested segment.

       When  the  file descriptor fildes refers to a shared memory object, the
       behavior of fcntl() shall be the same as for a regular file except  the
       effect   of  the  following  values  for  the  argument  cmd  shall  be
       unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.

       If fildes refers to a typed memory object, the result  of  the  fcntl()
       function is unspecified.

RETURN VALUE

       Upon  successful  completion, the value returned shall depend on cmd as
       follows:

       F_DUPFD
              A new file descriptor.

       F_GETFD
              Value of flags defined in <fcntl.h>. The return value shall  not
              be negative.

       F_SETFD
              Value other than -1.

       F_GETFL
              Value of file status flags and access modes. The return value is
              not negative.

       F_SETFL
              Value other than -1.

       F_GETLK
              Value other than -1.

       F_SETLK
              Value other than -1.

       F_SETLKW
              Value other than -1.

       F_GETOWN
              Value of the socket owner process or process  group;  this  will
              not be -1.

       F_SETOWN
              Value other than -1.

       Otherwise, -1 shall be returned and errno set to indicate the error.

ERRORS

       The fcntl() function shall fail if:

       EACCES or EAGAIN

              The  cmd  argument  is  F_SETLK; the type of lock ( l_type) is a
              shared (F_RDLCK) or exclusive (F_WRLCK) lock 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  The fildes argument is not a valid open file descriptor, or  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, or the type of lock, l_type, is an
              exclusive lock  (F_WRLCK),  and  fildes  is  not  a  valid  file
              descriptor open for writing.

       EINTR  The cmd argument is F_SETLKW and the function was interrupted by
              a signal.

       EINVAL The cmd argument is invalid, or the cmd argument is F_DUPFD  and
              arg  is  negative or greater than or equal to {OPEN_MAX}, or the
              cmd argument is F_GETLK,  F_SETLK,  or  F_SETLKW  and  the  data
              pointed  to by arg is not valid, or fildes refers to a file that
              does not support locking.

       EMFILE The argument cmd is F_DUPFD and {OPEN_MAX} file descriptors  are
              currently  open  in  the calling process, 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.

       EOVERFLOW
              One  of  the  values  to  be  returned  cannot  be   represented
              correctly.

       EOVERFLOW
              The  cmd  argument  is  F_GETLK,  F_SETLK,  or  F_SETLKW and the
              smallest or, if l_len is non-zero, the  largest  offset  of  any
              byte in the requested segment cannot be represented correctly in
              an object of type off_t.

       The fcntl() function may fail if:

       EDEADLK
              The cmd argument is F_SETLKW, the lock is blocked by a lock from
              another  process,  and  putting  the calling process to sleep to
              wait for that lock to become free would cause a deadlock.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       The ellipsis in the SYNOPSIS is  the  syntax  specified  by  the  ISO C
       standard  for a variable number of arguments. It is used because System
       V uses pointers for the implementation of file locking functions.

       The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all  represent
       flag  values  to  allow  for  future  growth.  Applications using these
       functions should do a read-modify-write operation on them, rather  than
       assuming   that   only   the   values   defined   by   this  volume  of
       IEEE Std 1003.1-2001 are valid. It is a common error  to  forget  this,
       particularly in the case of F_SETFD.

       This  volume  of IEEE Std 1003.1-2001 permits concurrent read and write
       access to file data using the fcntl() function; this is a  change  from
       the  1984  /usr/group standard and early proposals. Without concurrency
       controls, this feature may not be  fully  utilized  without  occasional
       loss of data.

       Data  losses  occur  in  several  ways.  One  case  occurs when several
       processes try to update the same record, without  sequencing  controls;
       several  updates  may  occur  in  parallel  and the last writer "wins".
       Another case is a bit-tree or other internal list-based  database  that
       is undergoing reorganization. Without exclusive use to the tree segment
       by the updating process, other reading processes chance getting lost in
       the  database  when the index blocks are split, condensed, inserted, or
       deleted. While fcntl() is useful  for  many  applications,  it  is  not
       intended  to be overly general and does not handle the bit-tree example
       well.

       This facility is only required for regular  files  because  it  is  not
       appropriate for many devices such as terminals and network connections.

       Since fcntl() works with "any  file  descriptor  associated  with  that
       file,  however  it  is  obtained",  the  file  descriptor may have been
       inherited through a fork() or exec operation and thus may affect a file
       that another process also has open.

       The  use of the open file description to identify what to lock requires
       extra calls and presents problems if several processes are  sharing  an
       open  file  description,  but there are too many implementations of the
       existing mechanism for  this  volume  of  IEEE Std 1003.1-2001  to  use
       different specifications.

       Another  consequence  of this model is that closing any file descriptor
       for a given file (whether or not it is the same open  file  description
       that created the lock) causes the locks on that file to be relinquished
       for that process. Equivalently, any close  for  any  file/process  pair
       relinquishes  the  locks  owned on that file for that process. But note
       that while an open file description may be shared through fork(), locks
       are  not  inherited through fork().  Yet locks may be inherited through
       one of the exec functions.

       The identification of a machine in a network environment is outside the
       scope of this volume of IEEE Std 1003.1-2001.  Thus, an l_sysid member,
       such as found in System V, is not included in the locking structure.

       Changing of lock types can result in a previously locked  region  being
       split into smaller regions.

       Mandatory  locking was a major feature of the 1984 /usr/group standard.

       For advisory file record locking to be effective,  all  processes  that
       have  access  to  a  file must cooperate and use the advisory mechanism
       before doing I/O  on  the  file.  Enforcement-mode  record  locking  is
       important when it cannot be assumed that all processes are cooperating.
       For example, if one user uses an editor to update a file  at  the  same
       time  that a second user executes another process that updates the same
       file and if only one of the two processes is  using  advisory  locking,
       the  processes  are  not  cooperating.  Enforcement-mode record locking
       would protect against accidental collisions.

       Secondly, advisory record locking requires a process using  locking  to
       bracket  each  I/O operation with lock (or test) and unlock operations.
       With enforcement-mode file and record locking, a process can  lock  the
       file  once  and  unlock  when  all  I/O operations have been completed.
       Enforcement-mode record locking provides a base that can  be  enhanced;
       for  example,  with  sharable  locks.  That  is, the mechanism could be
       enhanced to allow a process to lock a file  so  other  processes  could
       read it, but none of them could write it.

       Mandatory locks were omitted for several reasons:

        1. Mandatory  lock  setting  was done by multiplexing the set-group-ID
           bit in most implementations; this was confusing, at best.

        2. The relationship to file truncation as supported in 4.2 BSD was not
           well specified.

        3. Any  publicly  readable  file  could  be  locked  by  anyone.  Many
           historical implementations keep the password database in a publicly
           readable file. A malicious user could thus prohibit logins. Another
           possibility would be to hold open a long-distance telephone line.

        4. Some demand-paged historical implementations  offer  memory  mapped
           files, and enforcement cannot be done on that type of file.

       Since  sleeping on a region is interrupted with any signal, alarm() may
       be used to provide a timeout facility  in  applications  requiring  it.
       This  is  useful  in  deadlock  detection. Since implementation of full
       deadlock detection is not always feasible, the [EDEADLK] error was made
       optional.

FUTURE DIRECTIONS

       None.

SEE ALSO

       alarm()  ,  close()  ,  exec()  ,  open()  ,  sigaction()  ,  the  Base
       Definitions  volume  of  IEEE Std 1003.1-2001,  <fcntl.h>,  <signal.h>,
       <unistd.h>

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .