unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

fcntl(2)                         System Calls                         fcntl(2)



NAME
       fcntl - file control

SYNOPSIS
       #include <sys/types.h>
       #include <unistd.h>
       #include <fcntl.h>

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

DESCRIPTION
       The  fcntl()  function provides for control over open files. The fildes
       argument is an open file descriptor.

       The fcntl() function can take a third argument, arg, whose  data  type,
       value, and use depend upon the value of cmd. The cmd argument specifies
       the operation to be performed by fcntl().

       The values for cmd are defined in <&lt;fcntl.h>&gt; and include:

       F_DUPFD         Return a new file descriptor which is the  lowest  num-
                       bered  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 refers to the same open file description  as
                       the original file descriptor, and shares any locks. The
                       FD_CLOEXEC flag associated with the new file descriptor
                       is cleared to keep the file open across calls to one of
                       the exec(2) functions.



       F_DUP2FD        Similar to F_DUPFD, but always  returns  arg.  F_DUP2FD
                       closes  arg  if  it  is  open  and not equal to fildes.
                       F_DUP2FD is equivalent to dup2(fildes, arg).



       F_FREESP        Free storage space associated with  a  section  of  the
                       ordinary  file  fildes.  The  section is specified by a
                       variable of data type struct flock pointed to  by  arg.
                       The  data type struct flock is defined in the <&lt;fcntl.h>&gt;
                       header (see fcntl.h(3HEAD))  and  is  described  below.
                       Note that all file systems might not support all possi-
                       ble variations of F_FREESP  arguments.  In  particular,
                       many  file  systems allow space to be freed only at the
                       end of a file.



       F_FREESP64      Equivalent to F_FREESP,  but  takes  a  struct  flock64
                       argument rather than a struct flock argument.



       F_GETFD         Get the file descriptor flags defined in <&lt;fcntl.h>&gt; 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_GETFL         Get  the  file  status  flags  and  file  access modes,
                       defined in <&lt;fcntl.h>&gt;, for the file descriptor specified
                       by  fildes. The file access modes can be extracted from
                       the return value using the  mask  O_ACCMODE,  which  is
                       defined in <&lt;fcntl.h>&gt;. File status flags and file access
                       modes do not affect other file descriptors  that  refer
                       to the same file with different open file descriptions.



       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_GETXFL        Get the file status flags, file access modes, and  file
                       creation  and  assignment  flags, defined in <&lt;fcntl.h>&gt;,
                       for the file descriptor specified by fildes.  The  file
                       access  modes  can  be  extracted from the return value
                       using  the  mask  O_ACCMODE,  which   is   defined   in
                       <&lt;fcntl.h>&gt;.  File  status  flags, file access modes, and
                       file creation and assignment flags do not affect  other
                       file  descriptors that refer to the same file with dif-
                       ferent open file descriptions.



       F_SETFD         Set the file descriptor  flags  defined  in  <&lt;fcntl.h>&gt;,
                       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 will remain open across
                       the exec() functions; otherwise the file will be closed
                       upon  successful  execution  of one of the exec() func-
                       tions.



       F_SETFL         Set the file status flags, defined  in  <&lt;fcntl.h>&gt;,  for
                       the file descriptor specified by fildes from the corre-
                       sponding bits in the arg argument, taken as  type  int.
                       Bits  corresponding  to  the  file access mode and file
                       creation and assignment flags that are set in  arg  are
                       ignored.  If any bits in arg other than those mentioned
                       here are changed by  the  application,  the  result  is
                       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  commands  are  available  for  advisory record locking.
       Record locking is 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 <&lt;fcntl.h>&gt;. The
                       information retrieved overwrites 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  will  be  left unchanged except for the
                       lock type which will be set to F_UNLCK.



       F_GETLK64       Equivalent to F_GETLK, but takes a struct flock64 argu-
                       ment rather than a struct flock argument.



       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
                       <&lt;fcntl.h>&gt;. F_SETLK is  used  to  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
                       <&lt;fcntl.h>&gt;. If a shared or exclusive lock cannot be set,
                       fcntl()  will return immediately with a return value of
                       -1.



       F_SETLK64       Equivalent to F_SETLK, but takes a struct flock64 argu-
                       ment rather than a struct flock argument.



       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  will  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() will be inter-
                       rupted. Upon return from the process'  signal  handler,
                       fcntl() will return -1 with errno set to EINTR, and the
                       lock operation will not be done.



       F_SETLKW64      Equivalent to F_SETLKW,  but  takes  a  struct  flock64
                       argument rather than a struct flock argument.



       When  a shared lock is set on a segment of a file, other processes will
       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  will
       fail if the file descriptor was not opened with read access.

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

       The flock structure contains at least the following elements:

       short   l_type;       /* lock operation type */
       short   l_whence;     /* lock base indicator */
       off_t   l_start;      /* starting offset from base */
       off_t   l_len;        /* lock length; l_len == 0 means
                                until end of file */
       int     l_sysid;      /* system ID running process holding lock */
       pid_t   l_pid;        /* process ID of process holding lock */



       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. The
       value of l_len may be negative (where the definition of  off_t  permits
       negative  values  of  l_len).  After  a successful F_GETLK or F_GETLK64
       request, that is, one in which a lock was found, the value of  l_whence
       will be SEEK_SET.

       The l_pid and l_sysid fields are used only with F_GETLK or F_GETLK64 to
       return the process ID of the process holding a  blocking  lock  and  to
       indicate which system is running that process.

       If  l_len  is positive, the area affected starts at l_start and ends at
       l_start + l_len - 1. If l_len is negative, the area affected starts  at
       l_start  +  l_len  and  ends at l_start - 1. Locks may start and extend
       beyond the current end of a file, but must not be negative relative  to
       the  beginning of the file. A lock will 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 will be locked.

       If a process has an existing  lock  in  which  l_len  is  0  and  which
       includes  the  last  byte  of  the  requested  segment,  and  an unlock
       (F_UNLCK) request is made 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, then the F_UNLCK request will  be  treated  as  a
       request to unlock from the start of the requested segment with an l_len
       equal to 0. Otherwise, the request will  attempt  to  unlock  only  the
       requested segment.

       There  will  be at most one type of lock set for each byte in the file.
       Before a successful return from an  F_SETLK,  F_SETLK64,  F_SETLKW,  or
       F_SETLKW64  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 will be replaced by the
       new lock type. As specified above  under  the  descriptions  of  shared
       locks   and  exclusive  locks,  an  F_SETLK,  F_SETLK64,  F_SETLKW,  or
       F_SETLKW64 request will  (respectively)  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 are 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 created using fork(2).

       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() will fail with an EDEADLK
       error.

       The following values for cmd are used for file  share  reservations.  A
       share reservation is placed on an entire file to allow cooperating pro-
       cesses to control access to the file.

       F_SHARE         Sets a share reservation on a file with  the  specified
                       access  mode  and  designates  which types of access to
                       deny.



       F_UNSHARE       Remove an existing share reservation.



       File share reservations are an advisory form of  access  control  among
       cooperating processes, on both local and remote machines. They are most
       often used by DOS or Windows emulators and DOS based NFS clients.  How-
       ever,  native  UNIX  versions  of  DOS or Windows applications may also
       choose to use this form of access control.

       A share reservation is described by  an  fshare  structure  defined  in
       <&lt;sys/fcntl.h>&gt;, which is included in <&lt;fcntl.h>&gt; as follows:

       typedef struct fshare {
               short   f_access;
               short   f_deny;
               int     f_id;
       } fshare_t;


       A  share  reservation  specifies  the  type  of access, f_access, to be
       requested on the open file descriptor. If access is granted, it further
       specifies what type of access to deny other processes, f_deny. A single
       process on the same file may hold multiple non-conflicting
        reservations by specifying an identifier, f_id, unique to the process,
       with each request.

       An  F_UNSHARE request releases the reservation with the specified f_id.
       The f_access and f_deny fields are ignored.

       Valid f_access values are:

       F_RDACC         Set a file share reservation for read-only access.



       F_WRACC         Set a file share reservation for write-only access.



       F_RWACC         Set a file share reservation for read and write access.



       Valid f_deny values are:

       F_COMPAT        Set a file share reservation to compatibility mode.



       F_RDDNY         Set a file share reservation to  deny  read  access  to
                       other processes.



       F_WRDNY         Set  a  file  share reservation to deny write access to
                       other processes.



       F_RWDNY         Set a file share reservation to  deny  read  and  write
                       access to other processes.



       F_NODNY         Do not deny read or write access to any other process.



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

       F_DUPFD         A new file descriptor.



       F_FREESP        Value of 0.



       F_GETFD         Value of flags defined in <&lt;fcntl.h>&gt;. The  return  value
                       will not be negative.



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



       F_GETLK         Value other than -1.



       F_GETLK64       Value other than -1.



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



       F_GETXFL        Value  of file status flags, access modes, and creation
                       and assignment flags. The return value will not be neg-
                       ative.



       F_SETFD         Value other than -1.



       F_SETFL         Value other than -1.



       F_SETLK         Value other than -1.



       F_SETLK64       Value other than -1.



       F_SETLKW        Value other than -1.



       F_SETLKW64      Value other than -1.



       F_SETOWN        Value other than -1.



       F_SHARE         Value other than -1.



       F_UNSHARE       Value other than -1.



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

ERRORS
       The fcntl() function will fail if:

       EAGAIN          The  cmd  argument is F_SETLK or F_SETLK64, 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 seg-
                       ment of a file to be locked is already shared-locked or
                       exclusive-locked by another process.

                       The  cmd  argument is F_FREESP, the file exists, manda-
                       tory file/record locking is set,  and  there  are  out-
                       standing  record locks on the file; or the cmd argument
                       is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64,  manda-
                       tory  file/record  locking is set, and the file is cur-
                       rently being mapped to virtual memory using mmap(2).

                       The cmd argument is F_SHARE and f_access conflicts with
                       an existing f_deny share reservation.



       EBADF           The  fildes  argument is not a valid open file descrip-
                       tor;  or  the  cmd  argument  is  F_SETLK,   F_SETLK64,
                       F_SETLKW, or F_SETLKW64, 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.

                       The  cmd argument is F_FREESP and fildes is not a valid
                       file descriptor open for writing.

                       The cmd argument is F_DUP2FD, and arg is negative or is
                       not   less   than   the   current  resource  limit  for
                       RLIMIT_NOFILE.

                       The cmd argument is F_SHARE, the f_access share  reser-
                       vation  is  for write access, and fildes is not a valid
                       file descriptor open for writing.

                       The cmd argument is F_SHARE, the f_access share  reser-
                       vation  is  for  read access, and fildes is not a valid
                       file descriptor open for reading.



       EFAULT          The  cmd  argument  is  F_GETLK,  F_GETLK64,   F_SETLK,
                       F_SETLK64,  F_SETLKW,  F_SETLKW64,  or F_FREESP and the
                       arg argument points to an illegal address.

                       The cmd argument is F_SHARE or F_UNSHARE and arg points
                       to an illegal address.



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



       EINVAL          The cmd argument is invalid or  not  supported  by  the
                       file  system; 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_GETLK64, F_SETLK, F_SETLK64,
                       F_SETLKW, or F_SETLKW64 and the data pointed to by  arg
                       is  not valid; or fildes refers to a file that does not
                       support locking.

                       The cmd argument is F_UNSHARE and  a  reservation  with
                       this f_id for this process does not exist.



       EIO             An  I/O error occurred while reading from or writing to
                       the file system.



       EMFILE          The cmd argument is F_DUPFD and  either  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  cmd  argument  is F_SETLK, F_SETLK64, F_SETLKW, or
                       F_SETLKW64 and satisfying the lock  or  unlock  request
                       would  result  in  the  number of locked regions in the
                       system exceeding a system-imposed limit.



       ENOLINK         Either the fildes argument is on a remote  machine  and
                       the  link  to  that machine is no longer active; or the
                       cmd argument is F_FREESP,  the  file  is  on  a  remote
                       machine,  and  the  link  to  that machine is no longer
                       active.



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

                       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 cmd argument is F_GETLK64, F_SETLK64, or F_SETLKW64
                       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 off64_t.



       The fcntl() function may fail if:

       EAGAIN          The  cmd  argument  is F_SETLK, F_SETLK64, F_SETLKW, or
                       F_SETLKW64, and the file is currently being  mapped  to
                       virtual memory using mmap(2).



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

                       The cmd argument is F_FREESP, mandatory record  locking
                       is  enabled,  O_NDELAY  and  O_NONBLOCK are clear and a
                       deadlock condition was detected.



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStan-
       dard MT-LevelAsync-Signal Safe


SEE ALSO
       lockd(1M), chmod(2), close(2),  creat(2),  dup(2),  exec(2),   fork(2),
       mmap(2),  open(2),  pipe(2), read(2), sigaction(2), write(2), dup2(3C),
       fcntl.h(3HEAD), attributes(5), standards(5)

       Programming Interfaces Guide

NOTES
       In the past, the variable errno was set to EACCES  rather  than  EAGAIN
       when  a  section of a file is already locked by another process. There-
       fore, portable application programs should expect and test  for  either
       value.

       Advisory locks allow cooperating processes to perform consistent opera-
       tions on files, but do not guarantee exclusive  access.  Files  can  be
       accessed  without  advisory  locks, but inconsistencies may result. The
       network share locking protocol does not support  the  f_deny  value  of
       F_COMPAT.  For  network file systems, if f_access is F_RDACC, f_deny is
       mapped to F_RDDNY. Otherwise, it is mapped to F_RWDNY.

       To prevent possible file  corruption,  the  system  may  reject  mmap()
       requests  for  advisory locked files, or it may reject advisory locking
       requests for mapped files. Applications that require  a  file  be  both
       locked  and  mapped should lock the entire file (l_start and l_len both
       set to 0). If a file  is  mapped,  the  system  may  reject  an  unlock
       request, resulting in a lock that does not cover the entire file.

       If  the  file  server  crashes and has to be rebooted, the lock manager
       (see lockd(1M)) attempts to recover all locks that were associated with
       that  server.  If a lock cannot be reclaimed, the process that held the
       lock is issued a SIGLOST signal.



SunOS 5.10                        24 Sep 2003                         fcntl(2)