Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 may	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 available values for	cmd are	defined	in the header <fcntl.h>, which
       include:

       F_DUPFD
	     Return  a new file	descriptor which is the	lowest numbered	avail-
	     able (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  de-
	     scription	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 de-
	     fined in the <fcntl.h> header (see	fcntl(3HEAD)) and is described
	     below. Note that all file systems might not support all  possible
	     variations	 of F_FREESP arguments.	 In particular,	many file sys-
	     tems allow	space to be freed only at the end of a file.

       F_GETFD
	     Get the file descriptor flags defined in <fcntl.h>	that are asso-
	     ciated 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 <fc-
	     ntl.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
	     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_GETXFL
	     Get the file status flags,	file access modes, and	file  creation
	     and assignment flags, defined in <fcntl.h>, for the file descrip-
	     tor 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 descrip-
	     tors that refer to	the same file with  different  open  file  de-
	     scriptions.

       F_SETFD
	     Set  the file descriptor flags defined in <fcntl.h>, that are as-
	     sociated 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 de-
	     scriptor  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
	     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 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 descrip-
	     tion pointed to by	the third argument, arg, taken as a pointer to
	     type  struct  flock, defined in <fcntl.h>.	F_SETLK	is used	to es-
	     tablish 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 han-
	     dler, 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 re-
       quest 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  re-
       quest,  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 be-
       yond  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 in-
       cludes 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 re-
       quest.

       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 re-
       gion is put to sleep by attempting to lock another process' locked  re-
       gion.  If the system detects that sleeping until	a locked region	is un-
       locked would cause a deadlock, fcntl() will fail	with an	  EDEADLK  er-
       ror.

       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.	 However, 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 re-
       quested on the open file	descriptor.   If access	is granted, it further
       specifies  what type of access to deny other processes,	f_deny.	A sin-
       gle process on the same file may	hold multiple non-conflicting
	reservations  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  pro-
	     cesses.

       F_WRDNY
	     Set  a  file share	reservation to deny write access to other pro-
	     cesses.

       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 creation and as-
	     signment 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 por-
	     tion 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  ex-
	     isting  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  de-
	     scriptor 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 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  descrip-
	     tors  are	currently  open	in the calling process,	or no file de-
	     scriptors 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	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  ob-
	     ject 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 en-
	     abled, 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	   |
       +-----------------------------+-----------------------------+
       |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),
       attributes(5), fcntl(3HEAD)

       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 ac-
       cessed without advisory locks, but inconsistencies may result. The net-
       work share locking protocol does	not support the	f_deny value of	F_COM-
       PAT. 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() re-
       quests for advisory locked files, or it may reject advisory locking re-
       quests  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 re-
       quest, resulting	in a lock that does not	cover the entire file.

       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.9			  8 Jan	2002			      fcntl(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fcntl&sektion=2&manpath=SunOS+5.9>

home | help