fcntl(2) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

fcntl(2)

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 <fcntl.h> and include:

       F_DUPFD

           Return a new file descriptor which is 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 refers to the same open file description as the
           original file descriptor, and shares any locks. The FD_CLOEXEC  and
           FD_CLOFORK  flags  associated  with the new file descriptor are not
           set.


       F_DUPFD_CLOEXEC

           Similar to F_DUPFD, except that the FD_CLOEXEC flag associated with
           the new file descriptor is set.


       F_DUPFD_CLOFORK

           Similar to F_DUPFD, except that the FD_CLOFORK flag associated with
           the new file descriptor is set.


       F_DUP2FD

           Similar to F_DUPFD, except that it  always  returns  arg.  F_DUP2FD
           closes  arg if it is open and not equal to fildes. If fildes is not
           equal to arg, the FD_CLOEXEC and FD_CLOFORK flags  associated  with
           the new file descriptor are cleared. If fildes is equal to arg, the
           FD_CLOEXEC and  FD_CLOFORK  flags  associated  with  the  new  file
           descriptor  are not changed. F_DUP2FD is equivalent to dup2(fildes,
           arg).


       F_DUP2FD_CLOEXEC

           Similar to F_DUP2FD, except that the  FD_CLOEXEC  flag  aassociated
           with the new file descriptor is set, unless fildes is equal to arg,
           in which case the flags are unchanged.


       F_DUP2FD_CLOFORK

           Similar to F_DUP2FD, except that  the  FD_CLOFORK  flag  associated
           with the new file descriptor is set, unless fildes is equal to arg,
           in which case the flags are unchanged.


       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.h(3HEAD)) and is described below.
           Note that all file systems might not support  all  possible  varia‐
           tions 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_ALLOCSP

           Allocate  space for a section of the ordinary file fildes. The sec‐
           tion 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.h(3HEAD) and is described below.


       F_ALLOCSP64

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


       F_GETFD

           Get the file descriptor flags defined in <fcntl.h> that are associ‐
           ated 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
           <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 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 avail‐
           able. 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 <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 different open file descriptions.


       F_SETFD

           Set  the file descriptor flags defined in <fcntl.h>, that are asso‐
           ciated 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() functions.

           If  the  FD_CLOFORK  flag in the third argument is 0, the file will
           remain open across the fork() functions; otherwise the file will be
           unavailable  after  successful execution of one of the fork() func‐
           tions.


       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 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 avail‐
           able,  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  satisfied.  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 opera‐
           tion 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
       <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   reserva‐
       tions  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_DUPFD_CLOEXEC     A new file descriptor.


       F_DUPFD_CLOFORK     A new file descriptor.


       F_DUP2FD            A new file descriptor.


       F_DUP2FD_CLOEXEC    A new file descriptor.


       F_DUP2FD_CLOFORK    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  cre‐
                           ation  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.


       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
           segment of a file to be locked is already shared-locked  or  exclu‐
           sive-locked by another process.

           The   cmd   argument   is  F_FREESP,  the  file  exists,  mandatory
           file/record locking is set, and there are outstanding record  locks
           on  the  file; or the cmd argument is F_SETLK, F_SETLK64, F_SETLKW,
           or F_SETLKW64, mandatory 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 descriptor; 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_CLOEXEC and F_DUP2FD_CLOFORK  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 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 reservation 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 ille‐
           gal 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_CLOEXEC and F_DUP2FD_CLOFORK 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_CLOEXEC and F_DUP2FD_CLOFORK 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()   box;   cw(2.75i)  |cw(2.75i)  lw(2.75i)  |lw(2.75i)  ATTRIBUTE
       TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _  MT-LevelAsync-
       Signal Safe _ StandardSee standards(5).


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)


       Oracle Solaris 11.2 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.


       The process ID returned for locked files on network file systems  might
       not be meaningful.


       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.11                        9 Apr 2015                          fcntl(2)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3