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 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  num-
		       bered  available	 (that	is, not	already	open) file de-
		       scriptor	greater	than or	equal to the  third  argument,
		       arg,  taken as an integer of type int. The new file de-
		       scriptor	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 or-
		       dinary file fildes. The section is specified by a vari-
		       able 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	possi-
		       ble variations 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  ar-
		       gument rather than a struct flock argument.

       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 de-
		       scriptor	and do not affect other	file descriptors  that
		       refer to	the same file.

       F_GETFL	       Get  the	 file  status flags and	file access modes, de-
		       fined 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 de-
		       fined  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 in-
		       dicate 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 us-
		       ing 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 descriptions.

       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 will remain open	across
		       the exec() functions; otherwise the file	will be	closed
		       upon  successful	 execution  of one of the exec() func-
		       tions.

       F_SETFL	       Set the file status flags, defined  in  <fcntl.h>,  for
		       the file	descriptor specified by	fildes from the	corre-
		       sponding	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  un-
		       specified.

       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 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 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 argu-
		       ment 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 argu-
		       ment 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  fc-
		       ntl()  is  waiting for a	region,	fcntl()	will be	inter-
		       rupted. 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  ar-
		       gument 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 in-
       dicate 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	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 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. 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  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	single
       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 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 ac-
		       cess 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 assignment flags. The return	value will not be neg-
		       ative.

       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  seg-
		       ment 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,	manda-
		       tory  file/record  locking  is  set, and	there are out-
		       standing	record locks on	the file; or the cmd  argument
		       is  F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64,	manda-
		       tory file/record	locking	is set,	and the	file  is  cur-
		       rently 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  descrip-
		       tor;   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	reser-
		       vation 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	reser-
		       vation 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 ma-
		       chine, and the link to that machine is  no  longer  ac-
		       tive.

       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  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 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 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)

       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.10			  24 Sep 2003			      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.10>

home | help