Man Pages

fcntl(3p) - phpMan fcntl(3p) - phpMan

Command: man perldoc info search(apropos)  


FCNTL(3P)                  POSIX Programmer's Manual                 FCNTL(3P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

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 descrip-
              tors 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  argu-
              ment,  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 associ-
              ated 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 unspec-
              ified.

       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. Posi-
              tive  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 infor-
              mation  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 por-
       tion 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 por-
       tion 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 nega-
       tive, 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  call-
              ing 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, with-
       out 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  termi-
       nals 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 con-
           fusing, 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 detec-
       tion 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, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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 .



IEEE/The Open Group                  2003                            FCNTL(3P)