👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for fcntl (linux section 3posix)

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

NAME
       fcntl - file control

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

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

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

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

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

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

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

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

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

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

       F_SETOWN
	      If fildes refers to a socket, set the process or	process  group	ID  specified  to
	      receive  SIGURG  signals when out-of-band data is available, using the value of the
	      third argument, arg, taken as type int. Positive values indicate a process ID; neg-
	      ative  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 argu-
	      ment, arg, taken as a pointer to type  struct  flock,  defined  in  <fcntl.h>.  The
	      information  retrieved  shall  overwrite	the  information passed to fcntl() in the
	      structure flock. If no lock is found that would prevent this lock from  being  cre-
	      ated,  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 sat-
	      isfied. If a signal that is to be caught is received while fcntl() is waiting for a
	      region, fcntl() shall be interrupted. Upon return from the signal handler,  fcntl()
	      shall  return  -1  with  errno  set to [EINTR], and the lock operation shall not be
	      done.

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

       When  a	shared	lock  is set on a segment of a file, other processes shall be able to set
       shared locks on that segment or a portion of it. A shared lock prevents any other  process
       from  setting  an  exclusive  lock  on  any portion of the protected area. A request for a
       shared lock shall fail if the file descriptor was not opened with read access.

       An exclusive lock shall prevent any other process from setting a shared lock or an  exclu-
       sive lock on any portion of the protected area. A request for an exclusive lock shall fail
       if the file descriptor was not opened with write access.

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

       The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate  that  the  relative
       offset  l_start	bytes  shall be measured from the start of the file, current position, or
       end of the file, respectively. The value of l_len is the number of consecutive bytes to be
       locked. The value of l_len may be negative (where the definition of off_t permits negative
       values of l_len). The l_pid field is only used with F_GETLK to return the  process  ID  of
       the  process  holding a blocking lock. After a successful F_GETLK request, when a blocking
       lock is found, the values returned in the flock structure shall be as follows:

       l_type Type of blocking lock found.

       l_whence
	      SEEK_SET.

       l_start
	      Start of the blocking lock.

       l_len  Length of the blocking lock.

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

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

       If  l_len  is  positive,  the  area  affected  shall  start at l_start and end at l_start+
       l_len-1. If l_len is negative, the area affected shall start at l_start+ l_len and end  at
       l_start-1.  Locks  may  start  and  extend beyond the current end of a file, but shall not
       extend before the beginning of the file. A lock shall be set to extend to the largest pos-
       sible  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  success-
       ful  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 descrip-
       tor 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 unspeci-
       fied.

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 exclu-
	      sive-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 avail-
	      able.

       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  repre-
	      sented correctly in an object of type off_t.

       The fcntl() function may fail if:

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

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

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

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

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

       Data losses occur in several ways. One case occurs when several processes  try  to  update
       the  same  record,  without sequencing controls; several updates may occur in parallel and
       the last writer "wins". Another case is a bit-tree or other internal  list-based  database
       that is undergoing reorganization. Without exclusive use to the tree segment by the updat-
       ing 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 appli-
       cations, it is not intended to be overly general and does not handle the bit-tree  example
       well.

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

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

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

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

       The identification of a machine in a network environment is outside the scope of this vol-
       ume  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 cooper-
       ating. 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 exam-
       ple,  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 implemen-
	   tations; this was confusing, at best.

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

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

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

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

FUTURE DIRECTIONS
       None.

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

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

IEEE/The Open Group			       2003					 FCNTL(P)


All times are GMT -4. The time now is 03:29 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?