fcntl man page on OPENSTEP

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


FCNTL(2)							      FCNTL(2)

NAME
       fcntl - file control

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

       int fcntl(int fd, int cmd, ...);
       int fcntl(int fd, int cmd, int arg);
       int fcntl(int fd, int cmd, struct flock *arg);

DESCRIPTION
       The fcntl function performs a variety of functions on open descriptors.
       The argument fd is an open descriptor to	 be  operated  on  by  cmd  as
       follows:

       F_DUPFD	      Return a new descriptor as follows:

		      Lowest  numbered	available  descriptor  greater than or
		      equal to arg.

		      References the same object as the original descriptor.

		      New descriptor shares  the  same	file  pointer  if  the
		      object was a file.

		      Same access mode (read, write or read/write).

		      Same  file status flags (that is, both descriptors share
		      the same file status flags).

		      The  close-on-exec  flag	 associated   with   the   new
		      descriptor  is  cleared  to  keep	 the  file open across
		      execve(2) system calls.

       F_GETFD	      Get  the	close-on-exec	flag   associated   with   the
		      descriptor  fd.	If  the	 low-order bit of this flag is
		      clear (that is, if it's zero), then the file will remain
		      open  across an exec(2) system call.  Otherwise the file
		      will  be	closed	upon  execution	 of  exec(2).	 POSIX
		      applications  refer  to  this  flag  with	 the  constant
		      FD_CLOEXEC.

       F_SETFD	      Set the close-on-exec flag associated  with  fd  to  the
		      low-order	  bit  of  the	third  argument,  arg.	 POSIX
		      applications use the constant  FD_CLOEXEC	 to  set  this
		      flag and 0 to clear it.

       F_GETFL	      Get  the file status flags and file access modes for the
		      open file descriptor associated with fd.

		      POSIX applications can extract  the  file	 access	 modes
		      from  the	 return	 value	using  the mask O_ACCMODE (see
		      <fcntl.h>).  The file status  flags  are	O_APPEND  (set
		      append mode) and O_NONBLOCK (no delay).  The file access
		      modes are O_RDONLY (open for reading only), O_RDWR (open
		      for  reading and writing) and O_WRONLY (open for writing
		      only).

       F_SETFL	      Set the file status flags for the open  file  descriptor
		      associated  with	fd  from the corresponding bits in the
		      third argument, arg.  Bits  corresponding	 to  the  file
		      access  modes  and  the oflag values that are set in arg
		      are ignored.

       F_GETOWN	      Get the process ID or process group currently  receiving
		      SIGIO and SIGURG signals; process groups are returned as
		      negative values.

       F_SETOWN	      Set the process or process group to  receive  SIGIO  and
		      SIGURG   signals;	  process   groups  are	 specified  by
		      supplying arg as negative, otherwise arg is  interpreted
		      as a process ID.

       The  SIGIO  facilities  are  enabled  by	 setting  the FASYNC flag with
       F_SETFL.

       The following commands are POSIX-specific:

       F_GETLK	      Get a description of the first lock  which  would	 block
		      the  lock specified in the flock structure pointed to by
		      arg.    The   information	  retrieved   overwrites   the
		      information in the flock structure.  If no lock is found
		      that would prevent this lock from	 being	created,  then
		      the  structure  is  passed back unchanged except for the
		      lock type which will be set to F_UNLCK.

       F_SETLK	      Set or clear an advisory record lock  according  to  the
		      flock  structure	pointed to by arg.  F_SETLK is used to
		      establish	 shared	 (F_RDLCK)  and	 exclusive   (F_WRLCK)
		      locks,  or  to remove either type of lock (F_UNLCK).  If
		      the specified  lock  cannot  be  applied,	 fcntl()  will
		      return with an error value of -1.

       F_SETLKW	      This  cmd is the same as F_SETLK except that if a shared
		      or  exclusive  lock  is  blocked	by  other  locks,  the
		      requesting  process  will	 sleep	until  the lock may be
		      applied.

NOTES ON FILE-LOCKING FOR POSIX APPLICATIONS
       Advisory	 locks	allow  cooperating  processes  to  perform  consistent
       operations  on  files,  but  do	not  guarantee exclusive access (i.e.,
       processes may still access files without using advisory locks, possibly
       resulting in inconsistencies).

       The  record  locking  mechanism allows two types of locks: shared locks
       (F_RDLCK) and exclusive locks (F_WRLCK).	 More  than  one  process  may
       hold  a	shared	lock  for  a particular segment of a file at any given
       time, but multiple exclusive, or both shared and exclusive,  locks  may
       not exist simultaneously on any segment.

       In  order  to claim a shared lock, the descriptor must have been opened
       with read access.  The descriptor on which an exclusive lock  is	 being
       placed must have been opened with write access.

       A  shared  lock	may  be upgraded to an exclusive lock, and vice versa,
       simply by specifying the appropriate lock type with a cmd of F_SETLK or
       F_SETLKW;  the  previous lock will be released and the new lock applied
       (possibly after other processes have gained and released the lock).

       If the cmd is  F_SETLKW	and  the  requested  lock  cannot  be  claimed
       immediately  (e.g.,  another  process  holds  an	 exclusive  lock  that
       partially or completely overlaps the current request) then the  calling
       process	will  block until the lock may be acquired.  Processes blocked
       awaiting a lock may be awakened by signals.

       Care should be taken to avoid deadlock situations  in  applications  in
       which  multiple	processes  perform  blocking  locks on a set of common
       records.

       The record that is to be locked or unlocked is described by  the	 flock
       structure, which is defined in <fcntl.h> as follows:

	      struct flock {
		   short     l_type;   /* F_RDLCK, F_WRLCK, or F_UNLCK */
		   short     l_whence; /* flag to choose starting offset */
		   off_t     l_start;  /* relative offset, in bytes */
		   off_t     l_len;    /* length, in bytes;  0 means lock to EOF */
		   pid_t     l_pid;    /* returned with F_GETLK */
	      };

       The  flock  structure  describes	 the  type  (l_type),  starting offset
       (l_whence), relative offset (l_start), and size (l_len) of the  segment
       of  the	file  to  be  affected.	 L_whence must be set to 0, 1, or 2 to
       indicate that the relative offset will be measured from	the  start  of
       the  file, current position, or end-of-file, respectively.  The process
       id field (l_pid) is only used  with  the	 F_GETLK  cmd  to  return  the
       description of a lock held by another process.

       Locks  may start and extend beyond the current end-of-file, but may not
       be negative relative to the beginning of the file.  A lock may  be  set
       to  always  extend to the end-of-file by setting l_len to zero (0).  If
       such a lock also has l_whence and l_start set to zero (0),  the	entire
       file  will  be locked.  Changing or unlocking a segment from the middle
       of a larger locked segment leaves two smaller segments at  either  end.
       Locking	a segment that is already locked by the calling process causes
       the old lock type to be removed and the new lock type to	 take  affect.
       All  locks  associated with a file for a given process are removed when
       the file is closed or the process terminates.  Locks are not  inherited
       by the child process in a fork(2) system call.

RETURN VALUE
       Upon  successful	 completion,  the  value  returned  depends  on cmd as
       follows:
	 F_DUPFD   A new descriptor.
	 F_GETFD   Value of flag (only the low-order bit is defined).
	 F_GETFL   Value of flags.
	 F_GETOWN  Value of descriptor owner.
	 other	   Value other than -1.
       Otherwise, a value of -1 is returned and errno is set to	 indicate  the
       error.

ERRORS
       The fcntl function will fail if one or more of the following are true:

       [EAGAIN]	      cmd  is  F_SETLK,	 the  lock  type  (l_type)  is F_RDLCK
		      (shared lock), and the segment of the file to be	locked
		      already  has  an exclusive lock held by another process.
		      This error will also be returned if  the	lock  type  is
		      F_WRLCK (exclusive lock) and another process already has
		      the segment locked with either  a	 shared	 or  exclusive
		      lock.

       [EBADF]	      cmd is F_SETLK or F_SETLKW and the process does not have
		      the appropriate read or write permissions on the file.

       [EBADF]	      fd is not a valid open descriptor.

       [EFAULT]	      cmd is F_GETLK, F_SETLK, or F_SETLKW and arg  points  to
		      an invalid address.

       [EINTR]	      cmd  is  F_SETLKW	 and  a signal interrupted the process
		      while it was waiting for the lock to be granted.

       [EINVAL]	      cmd is F_GETLK, F_SETLK, or F_SETLKW and	the  data  arg
		      points  to  is  not valid; or, either cmd is invalid, or
		      cmd is F_DUPFD and arg is negative or greater  than  the
		      maximum	 allowable    number   (OPEN_MAX   for	 POSIX
		      applications, or the return  value  of  getdtablesize(2)
		      for non-POSIX applications).

       [EMFILE]	      cmd  is  F_DUPFD	and  the  maximum  allowed  number  of
		      descriptors are currently open.

       [ENOLCK]	      cmd is F_SETLK or F_SETLKW and there are	no  more  file
		      lock entries available.

SEE ALSO
       close(2), execve(2), getdtablesize(2), open(2), sigvec(2)

BUGS (POSIX-SPECIFIC)
       File  locks obtained through the fcntl mechanism do not interact in any
       way with those acquired by using flock(2).

       F_GETLK returns F_UNLCK if the requesting process holds	the  specified
       lock.   Thus, there is no way for a process to determine if it is still
       holding a specific lock after catching a SIGLOST signal.

				August 1, 1992			      FCNTL(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OPENSTEP

List of man pages available for OPENSTEP

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