fcntl man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

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  fol‐
       lows:

       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; otherwise, the
	      file  shall  be  closed  upon successful execution of one of the
	      exec functions.

       F_GETFL
	      Get the file status flags and  file  access  modes,  defined  in
	      <fcntl.h>,  for the file description 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  associated  with fildes from the corresponding bits
	      in the third argument, arg, taken as type int. Bits  correspond‐
	      ing  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  val‐
	      ues,  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; negative val‐
	      ues, 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  sup‐
       ported for other files.

       F_GETLK
	      Get  the first lock which blocks the lock description pointed to
	      by the third argument, arg, taken as a pointer  to  type	struct
	      flock,  defined  in  <fcntl.h>.  The information retrieved shall
	      overwrite the information passed to  fcntl()  in	the  structure
	      flock.  If  no  lock  is found that would prevent this lock from
	      being created, then the structure shall be left unchanged except
	      for the lock type which shall be set to F_UNLCK.

       F_SETLK
	      Set  or clear a file segment lock according to the lock descrip‐
	      tion pointed to by the third argument, arg, taken as  a  pointer
	      to  type	struct flock, defined in <fcntl.h>. F_SETLK can estab‐
	      lish shared (or read) locks (F_RDLCK) or	exclusive  (or	write)
	      locks  (F_WRLCK),	 as  well  as  to  remove  either type of lock
	      (F_UNLCK).  F_RDLCK,  F_WRLCK,  and  F_UNLCK  are	  defined   in
	      <fcntl.h>.  If a shared or exclusive lock cannot be set, fcntl()
	      shall return immediately with a return value of -1.

       F_SETLKW
	      This command shall be equivalent to F_SETLK  except  that	 if  a
	      shared  or  exclusive lock is blocked by other locks, the thread
	      shall wait until the request can be satisfied. If a signal  that
	      is  to  be  caught  is  received	while fcntl() is waiting for a
	      region, fcntl() shall be interrupted. Upon return from the  sig‐
	      nal  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 exclusive 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
       possible	 value of the file offset for that file by setting l_len to 0.
       If such a lock also has l_start	set  to	 0  and	 l_whence  is  set  to
       SEEK_SET, the whole file shall be locked.

       There  shall be at most one type of lock set for each byte in the file.
       Before a successful return from an F_SETLK or an F_SETLKW request  when
       the  calling  process  has  previously  existing	 locks on bytes in the
       region specified by the request, the previous lock type for  each  byte
       in  the	specified  region  shall  be replaced by the new lock type. As
       specified above under the descriptions of shared	 locks	and  exclusive
       locks,  an  F_SETLK or an F_SETLKW request (respectively) shall fail or
       block when another process has existing locks on bytes in the specified
       region and the type of any of those locks conflicts with the type spec‐
       ified in the request.

       All locks associated with a file for a given process shall  be  removed
       when  a	file descriptor for that file is closed by that process or the
       process holding that file descriptor terminates. Locks are  not	inher‐
       ited 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 unspeci‐
       fied: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.

       If fildes refers to a typed memory object, the result  of  the  fcntl()
       function is unspecified.

RETURN VALUE
       Upon  successful	 completion, the value returned shall depend on cmd as
       follows:

       F_DUPFD
	      A new file descriptor.

       F_GETFD
	      Value of flags defined in <fcntl.h>. The return value shall  not
	      be negative.

       F_SETFD
	      Value other than -1.

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

       F_SETFL
	      Value other than -1.

       F_GETLK
	      Value other than -1.

       F_SETLK
	      Value other than -1.

       F_SETLKW
	      Value other than -1.

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

       F_SETOWN
	      Value other than -1.

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

ERRORS
       The fcntl() function shall fail if:

       EACCES or EAGAIN

	      The  cmd	argument  is  F_SETLK; the type of lock ( l_type) is a
	      shared (F_RDLCK) or exclusive (F_WRLCK) lock and the segment  of
	      a	 file  to  be  locked  is  already exclusive-locked by another
	      process, or the type is an exclusive lock and  some  portion  of
	      the  segment  of a file to be locked is already shared-locked or
	      exclusive-locked by another process.

       EBADF  The fildes argument is not a valid open file descriptor, or  the
	      argument	cmd  is F_SETLK or F_SETLKW, the type of lock, l_type,
	      is a shared lock (F_RDLCK), and  fildes  is  not	a  valid  file
	      descriptor  open for reading, or the type of lock, l_type, is an
	      exclusive lock  (F_WRLCK),  and  fildes  is  not	a  valid  file
	      descriptor open for writing.

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

       EINVAL The cmd argument is invalid, or the cmd argument is F_DUPFD  and
	      arg  is  negative or greater than or equal to {OPEN_MAX}, or the
	      cmd argument is F_GETLK,	F_SETLK,  or  F_SETLKW	and  the  data
	      pointed  to by arg is not valid, or fildes refers to a file that
	      does not support locking.

       EMFILE The argument cmd is F_DUPFD and {OPEN_MAX} file descriptors  are
	      currently	 open  in  the calling process, or no file descriptors
	      greater than or equal to arg are available.

       ENOLCK The argument cmd is F_SETLK or F_SETLKW and satisfying the  lock
	      or  unlock  request would result in the number of locked regions
	      in the system exceeding a system-imposed limit.

       EOVERFLOW
	      One of the values to be  returned	 cannot	 be  represented  cor‐
	      rectly.

       EOVERFLOW
	      The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the small‐
	      est or, if l_len is non-zero, the largest offset of any byte  in
	      the  requested  segment  cannot  be  represented correctly in an
	      object of type off_t.

       The fcntl() function may fail if:

       EDEADLK
	      The cmd argument is F_SETLKW, the lock is blocked by a lock from
	      another  process,	 and  putting  the 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 stan‐
       dard  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 func‐
       tions 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 pro‐
       cesses try to update the same record, without sequencing controls; sev‐
       eral  updates may occur in parallel and the last writer "wins". Another
       case is a bit-tree or other internal list-based database that is under‐
       going  reorganization. Without exclusive use to the tree segment by the
       updating process, other reading processes chance getting	 lost  in  the
       database	 when  the  index  blocks  are	split, condensed, inserted, or
       deleted. While fcntl() is useful	 for  many  applications,  it  is  not
       intended	 to be overly general and does not handle the bit-tree example
       well.

       This facility is only required for regular  files  because  it  is  not
       appropriate for many devices such as 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 inher‐
       ited 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 dif‐
       ferent specifications.

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

       The identification of a machine in a network environment is outside the
       scope of this volume of IEEE Std 1003.1-2001.  Thus, an l_sysid member,
       such as found in System V, is not included in the locking structure.

       Changing	 of  lock types can result in a previously locked region being
       split into smaller regions.

       Mandatory locking was a major feature of the 1984 /usr/group standard.

       For advisory file record locking to be effective,  all  processes  that
       have  access  to	 a  file must cooperate and use the advisory mechanism
       before doing I/O on the file. Enforcement-mode record locking is impor‐
       tant  when it cannot be assumed that all processes are cooperating. For
       example, if one user uses an editor to update a file at the  same  time
       that  a second user executes another process that updates the same file
       and if only one of the two processes is	using  advisory	 locking,  the
       processes  are  not  cooperating. Enforcement-mode record locking would
       protect against accidental collisions.

       Secondly, advisory record locking requires a process using  locking  to
       bracket	each  I/O operation with lock (or test) and unlock operations.
       With enforcement-mode file and record locking, a process can  lock  the
       file  once  and	unlock	when  all  I/O operations have been completed.
       Enforcement-mode record locking provides a base that can	 be  enhanced;
       for  example,  with  sharable  locks.  That  is, the mechanism could be
       enhanced to allow a process to lock a file  so  other  processes	 could
       read it, but none of them could write it.

       Mandatory locks were omitted for several reasons:

	1. Mandatory  lock  setting  was done by multiplexing the set-group-ID
	   bit in most implementations; this was 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 histori‐
	   cal implementations keep the password database in a publicly	 read‐
	   able	 file.	A  malicious  user could thus prohibit logins. Another
	   possibility would be to hold open a long-distance telephone line.

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

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

FUTURE DIRECTIONS
       None.

SEE ALSO
       alarm()	,  close()  , exec() , open() , sigaction() , the Base Defini‐
       tions 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 original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			      FCNTL(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net