fcntl man page on Solaris

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

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

       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 descrip‐
			   tion 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 operation
			   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	speci‐
			   fied	 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_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	 exclusive-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, 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 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 not supported by the
			   file system; 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.

       EOVERFLOW	   One	of  the values to be returned cannot be repre‐
			   sented 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  seg‐
			   ment	 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 dead‐
			   lock.

			   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:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Standard			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │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),
       fcntl.h(3HEAD), attributes(5), standards(5)

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.10			  24 Sep 2003			      fcntl(2)
[top]

List of man pages available for Solaris

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