unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



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 may 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 available values for  cmd  are  defined  in  the  header
     <fcntl.h>, which 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  argu-
           ment,  arg,  taken  as an integer of type int. The new
           file descriptor refers to the same open file  descrip-
           tion  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 <fcntl.h>
           header (see fcntl(3HEAD)) and is described below. Note
           that  all  file systems might not support all possible
           variations of F_FREESP arguments.  In particular, many
           file  systems  allow space to be freed only at the end
           of a file.

     F_GETFD
           Get the file descriptor  flags  defined  in  <fcntl.h>
           that  are  associated with the file descriptor fildes.



SunOS 5.9            Last change: 8 Jan 2002                    1






System Calls                                             fcntl(2)



           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_GETFL
           Get the file  status  flags  and  file  access  modes,
           defined  in  <fcntl.h>, for the file descriptor speci-
           fied  by  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 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  pro-
           cess group ID specified to receive SIGURG signals when
           out-of-band data is available.  Positive values  indi-
           cate  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 <fcntl.h>,
           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
           <fcntl.h>.   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  <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 will remain open
           across the exec() functions; otherwise the  file  will
           be  closed  upon  successful  execution  of one of the
           exec() functions.

     F_SETFL
           Set the file status flags, defined in  <fcntl.h>,  for
           the  file  descriptor  specified  by  fildes  from the
           corresponding 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 men-
           tioned here are changed by the application, the result
           is unspecified.




SunOS 5.9            Last change: 8 Jan 2002                    2






System Calls                                             fcntl(2)



     F_SETOWN
           If fildes refers to a socket, set the process or  pro-
           cess 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  <fcntl.h>.
           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
           argument 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
           <fcntl.h>.  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
           <fcntl.h>.  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
           argument 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  satis-
           fied.  If  a  signal  that is to be caught is received
           while fcntl() is waiting for a region, fcntl() will be
           interrupted.   Upon  return  from  the process' signal
           handler, fcntl() will return  -1  with  errno  set  to
           EINTR, and the lock operation will not be done.



SunOS 5.9            Last change: 8 Jan 2002                    3






System Calls                                             fcntl(2)



     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 pro-
     tected 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  set-
     ting  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  ele-
     ments:

     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 possi-
     ble 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.



SunOS 5.9            Last change: 8 Jan 2002                    4






System Calls                                             fcntl(2)



     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 seg-
     ment 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 con-
     flicts 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  reser-
     vations.  A share reservation is placed on an entire file to
     allow cooperating processes 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  con-
     trol  among  cooperating processes, on both local and remote
     machines. They are  most often used by  DOS or Windows  emu-
     lators  and   DOS  based  NFS clients.  However, native UNIX
     versions of  DOS or Windows applications may also choose  to



SunOS 5.9            Last change: 8 Jan 2002                    5






System Calls                                             fcntl(2)



     use this form of access control.

     A share reservation is described  by  an   fshare  structure
     defined in <sys/fcntl.h>, which is included in  <fcntl.h> 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



SunOS 5.9            Last change: 8 Jan 2002                    6






System Calls                                             fcntl(2)



           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 follows:

     F_DUPFD
           A new file descriptor.

     F_FREESP
           Value of 0.

     F_GETFD
           Value of flags defined in <fcntl.h>. 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
           negative.

     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.



SunOS 5.9            Last change: 8 Jan 2002                    7






System Calls                                             fcntl(2)



     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
           currently   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.



SunOS 5.9            Last change: 8 Jan 2002                    8






System Calls                                             fcntl(2)



           The cmd  argument  is  F_SHARE,  the   f_access  share
           reservation  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 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.




SunOS 5.9            Last change: 8 Jan 2002                    9






System Calls                                             fcntl(2)



     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  seg-
           ment  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 put-
           ting 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  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-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), attributes(5), fcntl(3HEAD)

     Programming Interfaces Guide

NOTES




SunOS 5.9            Last change: 8 Jan 2002                   10






System Calls                                             fcntl(2)



     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. Therefore,  portable  application  programs
     should expect and test for either value.

     Advisory locks allow cooperating processes to  perform  con-
     sistent  operations on files, but do not guarantee exclusive
     access. Files can be accessed without  advisory  locks,  but
     inconsistencies may result. The network share locking proto-
     col does not support the f_deny value of F_COMPAT. For  net-
     work  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.9            Last change: 8 Jan 2002                   11