unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



fcntl(2)							     fcntl(2)



NAME

  fcntl, dup, dup2 - Control open file descriptors

SYNOPSIS

  #include <&lt;fcntl.h>&gt;
  #include <&lt;sys/types.h>&gt;
  #include <&lt;unistd.h>&gt;

  int fcntl (
	  int filedes,
	  int request [,
	  int argument | struct	flock *argument	|
		  advfs_opT argument ] );

  int dup(
	  int filedes );

  int dup2(
	  int old,
	  int new );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  dup(), dup2():  XSH5.0

  fcntl():  XSH5.0, XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  filedes   Specifies an open file descriptor obtained from a successful
	    open(), fcntl(), or	pipe() function.

  request   Specifies the operation to be performed.

  argument  Specifies a	variable that depends on the value of the request
	    parameter.	The standard allows for	a list of variables, but does
	    not	specify	them.  These can vary with each	vendor's implementa-
	    tion of this function.

  old	    Specifies an open file descriptor that is returned by the dup2()
	    function.

  new	    Specifies an open file descriptor that is returned by the dup2()
	    function.

DESCRIPTION

  The fcntl() function performs	controlling operations on the open file
  specified by the filedes parameter.


  When the fcntl(), dup() and dup2() functions need to block, only the cal-
  ling thread is suspended rather than all threads in the calling process.

  The following	are values for the request parameter:

  F_DUPFD   Returns a new file descriptor as follows:

	      +	 Lowest	numbered available file	descriptor greater than	or
		 equal to the argument parameter, taken	as type	int.

	      +	 Same object references	as the original	file.

	      +	 Same file pointer as the original file.  (That	is, both file
		 descriptors share one file pointer if the object is a file).

	      +	 Same access mode (read, write,	or read-write).

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

	      +	 The close-on-exec flag	(FD_CLOEXEC bit) associated with the
		 new file descriptor is	cleared	so that	the file will remain
		 open across exec functions.

  F_GETFD   Gets the value of the close-on-exec	flag associated	with the file
	    descriptor filedes.	 File descriptor flags are associated with a
	    single file	descriptor and do not affect other file	descriptors
	    that refer to the same file.  The argument parameter is ignored.

  F_SETFD   Sets the close-on-exec flag	associated with	the filedes parameter
	    to the value of the	argument parameter, taken as type int.	If
	    the	argument parameter is 0	(zero),	the file remains open across
	    the	exec functions.	 If the	argument parameter is FD_CLOEXEC, the
	    file is closed on successful execution of the next exec function.

  F_GETTIMES
	    [Tru64 UNIX]  Retrieves the	current	times for the file identified
	    by filedes.	 For the F_GETTIMES and	F_SETTIMES requests, the
	    function's third argument is a pointer to the struct attr_timbuf
	    structure (defined in sys/fcntl1.h), which contains	the file's
	    atime (access time), mtime (modification time), and	ctime (file
	    attribute change time) values. These requests are useful for
	    operations,	such as	backup and archiving, when it is necessary to
	    save a file's current time values and then,	after copying or mov-
	    ing	the file, set back atime or mtime without changing ctime.

  F_SETTIMES
	    [Tru64 UNIX]  Sets the current times for the file identified by
	    filedes.  This request requires superuser privilege.

  F_GETFL   Gets the file status flags and file	access modes for the file
	    referred to	by the filedes parameter.  The file access modes can
	    be extracted by using the mask O_ACCMODE on	the return value.
	    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.
	    The	argument parameter is ignored.

  F_SETFL   Sets the file status flags to the argument parameter, taken	as
	    type int, for the file to which the	filedes	parameter refers.
	    The	file access mode is not	changed.

  F_GETOWN  [XNS5.0]   If filedes refers to a socket, gets the process or
	    process group ID currently receiving SIGURG	signals	when out-of-
	    band data is available.  Positive values indicate a	process	ID;
	    negative values, other than	-1, indicate a process group ID.  If
	    filedes does not refer to a	socket,	the results are	unknown.

  F_SETOWN  [XNS5.0]   If filedes refers to a socket, sets the process or
	    process group ID to	receive	SIGURG signals when out-of-band	data
	    is available, using	the value of the argument parameter, taken as
	    type int. Positive values indicate a process ID; negative values,
	    other than -1, indicate a process group ID.	 If filedes does not
	    refer to a socket, the results are unknown.

  F_RSETLK  [Tru64 UNIX]   Reserved for	use by the network lock	daemon
	    (rpc.lockd(8)) on NFS servers to acquire locks requested by
	    F_SETLK on NFS clients.

  F_RSETLKW [Tru64 UNIX]   Reserved for	use by the network lock	daemon
	    (rpc.lockd(8)) on NFS servers to acquire locks requested by
	    F_SETLK on NFS clients.

  F_RGETLK  [Tru64 UNIX]   Reserved for	use by the network lock	daemon
	    (rpc.lockd(8)) on NFS servers to acquire locks requested by
	    F_SETLK on NFS clients.

  F_CNVT    [Tru64 UNIX]   Is used by the network lock daemon (rpc.lockd(8))
	    to communicate with	the NFS	server kernel to handle	locks on the
	    NFS	files.

  F_ADVFS_OP
	    [Tru64 UNIX]   Performs AdvFS-specific operations on AdvFS files.
	    The	value expects that the argument	parameter is a pointer to a
	    advfs_opT structure	as described in	the <&lt;fcntl.h>&gt; header file.

  The following	values for the request parameter are available for record
  locking:

  F_GETLK   Gets the first lock	that blocks the	lock description pointed to
	    by the argument parameter, taken as	a pointer to type struct
	    flock.  The	information retrieved overwrites the information
	    passed to the fcntl() function in the flock	structure.  If no
	    lock is found that would prevent this lock from being created,
	    then the structure is left unchanged except	for the	lock type,
	    which is set to F_UNLCK.

  F_SETLK   Sets or clears a file segment lock according to the	lock descrip-
	    tion pointed to by argument, taken as a pointer to type struct
	    flock.  F_SETLK is used to establish shared	locks (F_RDLCK), or
	    exclusive locks (F_WRLCK), as well as remove either	type of	lock
	    (F_UNLCK).	 If a shared (read) or exclusive (write) lock cannot
	    be set, the	fcntl()	function returns immediately with a value of
	    -1.

	    An unlock (F_UNLCK)	request	in which l_len is nonzero 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 exist-
	    ing	lock in	which l_len is 0 and which includes the	last byte of
	    the	requested segment, is treated as a request to unlock from the
	    start of the requested segment with	an l_len equal to 0.  Other-
	    wise, an unlock (F_UNLCK) request attempts to unlock only the
	    requested file.

  F_SETLKW  Same as F_SETLK except that	if a shared or exclusive lock is
	    blocked by other locks, the	process	will wait until	it is
	    unblocked.	If a signal is received	while fcntl() is waiting for
	    a region, the function is interrupted, -1 is returned, and errno
	    is set to [EINTR].



  AdvFS-only request Parameters

  [Tru64 UNIX]	 The following values for the request parameter	are available
  for AdvFS only, and relate to	performing direct I/O.	The arguments used
  with these request parameters	are in the <&lt;fcntl.h>&gt; file.  FCACHE is defined
  as zero to indicate that the file's cache policy is the file system's
  default cache	policy.	 FDIRECTIO is defined as one to	indicate that the
  file's cache policy is direct	I/O.

  F_GETCACHEPOLICY
	Gets the cache policy for the file, which is either direct I/O or
	caching.

  [Tru64 UNIX]	 The following value for the request parameter is valid	only
  when the filedes parameter describes an AdvFS	or UFS file.

  F_GETMAP
      [Tru64 UNIX]   The F_GETMAP request gets the sparseness map of the file
      referred to by the fildes	parameter.  The	argument parameter, taken as
      a	pointer	to type	struct extentmap, is filled in with data that
      describes	the extent map of the file.

      Each map entry is	declared as:
	   struct extentmapentry {
		   unsigned long offset;
		   unsigned long size;
	   };
	   struct extentmap {
		   unsigned long arraysize;
		   unsigned long numextents;
		   unsigned long offset;
		   struct extentmapentry *extent;
	   };
      The map returned by this function	can be different from the actual
      number of	extents	(or their definition) when the file is being written.
      It is recommended	that you use this function only	on files that are not
      being written.

  [Tru64 UNIX]	 The O_NDELAY and O_NONBLOCK requests affect only operations
  against file descriptors derived from	the same open()	function.  In BSD,
  these	apply to all file descriptors that refer to the	object.

  When a shared	lock is	set on a segment of a file, other processes are	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 fails if the	file descrip-
  tor was not opened with read access.

  An exclusive lock prevents 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 fails if the file descriptor was not opened with write
  access.

  The flock structure 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 set to SEEK_SET, SEEK_CUR or	SEEK_END, to indicate
  that the relative offset l_start bytes is measured from the start of the
  file,	from the current position, or from the end of the file,	respectively.
  The value of l_len is	the number of consecutive bytes	to be locked.  The
  l_len	value 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, the value of	l_whence becomes SEEK_SET.

  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 may not be negative relative to the begin-
  ning of the file.  If	l_len is set to	0 (zero), a lock may be	set to always
  extend to the	largest	possible value of the file offset for that file.  If
  such a lock also has l_start set to 0	(zero) and l_whence is set to
  SEEK_SET, the	whole file is locked.

  Changing or unlocking	a portion from the middle of a larger locked segment
  leaves a smaller segment 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 effect.

  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	in a fork() function.

  [Tru64 UNIX]	 The fcntl() record locks are implemented in the kernel	for
  local	locks and throughout the network by the	network	lock daemon
  (rpc.lockd(8)) for remote locks on NFS files.	If the file server crashes
  and has to be	rebooted, the lock daemon attempts to recover all locks	that
  were associated with that server. If a lock cannot be	reclaimed, the pro-
  cess that held the lock is issued a SIGLOST signal.

  [Tru64 UNIX]	 In order to maintain consistency in the network case, data
  must not be cached on	client machines. For this reason, file buffering for
  an NFS file is turned	off when the first lock	is attempted on	the file.
  Buffering remains off	as long	as the file is open. Programs that do I/O
  buffering in the user	address	space, however,	may have inconsistent
  results. The standard	I/O package, for instance, is a	common source of
  unexpected buffering.

  [Tru64 UNIX]	 If a regular file has enforced	record locking enabled,
  record locks on the file will	affect calls to	other calls, including
  creat(), open(), read(), write(), truncate(),	and ftruncate().

  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, the fcntl() function fails with an [EDEADLK] error.

  [Tru64 UNIX]	 The F_ADVFS_OP	request	is used	to perform operations on
  AdvFS	files which do not have	an analog on other file	systems.  The argu-
  ment parameter is expected to	be a pointer to	an advfs_opT structure.	 The
  operation field of the advfs_opT structure specifies the general kind	of
  operation.  The action field of the advfs_opT	structure refines the opera-
  tion field in	order to specify more exactly the operation to be performed.
  If the action	specified is ADVFS_GET_INFO, the info_buf and info_buf_size
  fields also must be used.  The info_buf field	is a pointer to	the buffer
  that will contain the	requested information.	The info_buf_size field
  specifies the	size of	the buffer.  See the <&lt;fcntl.h>&gt; header file for a
  description of the operations, actions, and values returned by
  ADVFS_GET_INFO.

  To use the F_ADVFS_OP	request	on AdvFS files that are	mounted	across NFS,
  the NFS property list	daemon,	proplistd, must	be running on the NFS client
  and the fileset must have been mounted on the	client using the proplist
  option.

  The following	code fragment shows how	to activate atomic write data logging
  on an	AdvFS file:

	       .
	       .
	       .
       advfs_opT  myop;
       int fd;
	       .
	       .
	       .
       myop.operation =	ADVFS_AW_DATA_LOGGING;
       myop.action    =	ADVFS_ACTIVATE;
       ret = fcntl(fd, F_ADVFS_OP, &myop);
	       .
	       .
	       .

  The following	code fragment shows how	to query the current I/O mode for an
  AdvFS	file:

	       .
	       .
	       .
       advfs_opT  myop;
       int fd;
       int io_mode;
	       .
	       .
	       .
       myop.operation =	advfs_aw_data_logging;
       myop.action    =	ADVFS_GET_INFO;
       myop.info_buf  =	&io_mode;
       myop.info_buf_size = sizeof(int):
       ret = fcntl(fd, F_ADVFS_OP, &myop):
       if (ret)	 {
	   perror("fcntl failed");
       }
       if (io_mode == ADVFS_ASYNC_IO)
	   printf("I/O mode is asynchronous.\n");
       else if (io_mode	== ADVFS_DATA_LOGGING_IO)
	   printf("I/O mode is atomic write data logging.\n");
       else if (io_mode	== ADVFS_SYNC_IO)
	   printf("I/O mode is forced synchronous writes.\n");
	       .
	       .
	       .

  See chfile(8)	for information	on the file's I/O mode.	 Note that the previ-
  ous example is attempting to determine the I/O mode setting.	The setting
  could	also have been specified as ADVFS_SYNC_WRITE.

NOTES

  The dup(filedes) function is equivalent to fcntl(filedes, F_DUPFD, 0).

  The dup2(oldfiledes, newfiledes)  function has similar functionality to:
	   close(newfiledes)
	   fcntl(oldfiledes, F_DUPFD, newfiledes)

RETURN VALUES

  Upon successful completion, the value	returned depends on the	value of the
  request parameter as follows:

  F_DUPFD   Returns a new file descriptor.

  F_GETFD   Returns FD_CLOEXEC or 0 (zero).

  F_SETFD   Returns a value other than -1.

  F_GETFL   Returns the	value of file status flags and access modes.  (The
	    return value will not be negative.)

  F_SETFL   Returns a value other than -1.

  F_GETLK   Returns a value other than -1.

  F_SETLK   Returns a value other than -1.

  F_GETOWN  [XNS5.0]   Returns the value of the	socket owner process or	pro-
	    cess group;	this will not be -1.

  F_SETOWN  [XNS5.0]   Returns a value other than -1.

  F_SETLKW  Returns a value other than -1.

  F_GETCACHEPOLICY
	    [Tru64 UNIX]   Returns a value other than -1.

  F_GETTIMES
	    [Tru64 UNIX]   Returns a value other than -1.

  F_SETTIMES
	    [Tru64 UNIX]   Returns a value other than -1.

  F_GETMAP  [Tru64 UNIX]    Returns a value other than -1.

  If the fcntl() function fails, a value of -1 is returned and errno is	set
  to indicate the error.

ERRORS

  The fcntl() function sets errno to the specified values for the following
  conditions:

  [EACCES] or [EAGAIN]
	    The	request	parameter 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 pro-
	    cess.

	    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	filedes	or old parameter is not	a valid	open file descriptor
	    and	the argument parameter file descriptor is negative or greater
	    than or equal to the per-process limit.

	    [Tru64 UNIX]    The	request	parameter is F_GETMAP and the filedes
	    parameter does not point to	an open	file descriptor	of an AdvFS
	    or UFS file.

	    The	request	parameter is F_SETLK or	F_SETLKW, the type of lock
	    (l_type) is	a shared lock (F_RDLCK), and filedes is	not a valid
	    file descriptor open for reading.

	    The	type of	lock (l_type) is an exclusive lock (F_WRLCK), and
	    filedes is not a valid file	descriptor open	for writing.

  [EDEADLK] The	request	parameter is F_SETLKW, the lock	is blocked by some
	    lock from another process and putting the calling process to
	    sleep, and waiting for that	lock to	become free would cause	a
	    deadlock.

  [EFAULT]  The	argument parameter is an invalid address.

  [EINVAL]  The	request	parameter is F_DUPFD and the argument parameter	is
	    negative or	greater	than or	equal to OPEN_MAX.

	    [Tru64 UNIX]   Either the OPEN_MAX value or	the per-process	soft
	    descriptor limit is	checked.

	    An illegal value was provided for the request parameter.

	    The	request	parameter is F_GETLK, F_SETLK, or F_SETLKW and the
	    data pointed to by argument	is invalid, or filedes refers to a
	    file that does not support locking.

	    [Tru64 UNIX]   The F_ADVFS_OP request was performed	and the	fd
	    referred to	a socket; or the action	was ADVFS_GET_INFO and the
	    info_buf_size was zero; or the operation to	be performed was
	    undefined; or the action to	be taken was undefined.

  [EMFILE]  The	request	parameter is F_DUPFD and too many or OPEN_MAX file
	    descriptors	are currently open in the calling process, or no file
	    descriptors	greater	than or	equal to argument are available.

	    [Tru64 UNIX]   Either the OPEN_MAX value or	the per-process	soft
	    descriptor limit is	checked.



  [EOVERFLOW]
	    One	of the values to be returned cannot be represented correctly.

	    The	request	argument is F_BETLK, F_SETLK, or F_SETLKW and the
	    smallest or, if l_len is nonzero, the largest offset of any	byte
	    in the requested segment cannot be represented correctly in	an
	    object of type off_t.

  [ESRCH]   [Tru64 UNIX]   The value of	the request parameter is F_SETOWN and
	    the	process	ID given as argument is	not in use.

  [EINTR]   The	request	parameter is F_SETLKW and the fcntl() function was
	    interrupted	by a signal which was caught.

  [EIO]	    [Tru64 UNIX]   The request parameter is F_GETMAP and an I/O	error
	    occurred on	the disk where the file	is located.

  [ENOLCK]  The	request	parameter is F_SETLK or	F_SETLKW and satisfying	the
	    lock or unlock request would exceed	the configurable system	limit
	    of NLOCK_RECORD.

	    [Tru64 UNIX]   The file is an NFS file, and	either the client or
	    server system is not running rpc.lockd, which is the NFS lock
	    manager.

  [ENOMEM]  [Tru64 UNIX]   The system was unable to allocate kernel memory
	    for	the requested file descriptor.

  [ENOTTY]  [Tru64 UNIX]   The request parameter is F_SETOWN and the calling
	    process does not have a controlling	terminal, the file is not the
	    controlling	terminal, or the controlling terminal is no longer
	    associated with the	calling	process' session.

  [EPERM]   [Tru64 UNIX]   The request parameter is F_SETOWN and the argument
	    specified by the pgrp_id is	valid, but matches a process ID	or
	    process group ID of	a process in another session.

  The dup() and	dup2() functions set errno to the specified values for the
  following conditions:

  [EACCES]  The	request	parameter is F_SETLK; the type of lock (l_type)	is a
	    read (F_RDLCK) lock, and the segment of a file to be locked	is
	    already write-locked by another process; or	the type is a write
	    (F_WRLCK) lock and the segment of a	file to	be locked is already
	    read- or write-locked by another process.

  [EBADF]   The	filedes	or old parameter is not	a valid	open file descriptor
	    or the new parameter file descriptor is negative or	greater	than
	    OPEN_MAX.

	    [Tru64 UNIX]   Either the OPEN_MAX value or	the per-process	soft
	    descriptor limit is	checked.

  [EINTR]   The	dup2() function	was interrupted	by a signal which was caught.

  [EMFILE]  The	number of file descriptors exceeds OPEN_MAX or the per-
	    process limit, or there is no file descriptor above	the value of
	    the	new parameter.

  [ENETUNREACH]
	    [Tru64 UNIX]    The	file descriptor	specified by filedes is	on a
	    remote machine and the link	to that	machine	is no longer active.

  [ENOMEM]  [Tru64 UNIX]   The system was unable to allocate kernel memory
	    for	the requested file descriptor.

  Because in the future	the variable errno is set to EAGAIN rather than
  EACCES when a	section	of a file is already locked by another process,	port-
  able application programs should expect and test for either value.

RELATED	INFORMATION

  Functions: close(2), creat(2), dup(2), exec(2), flock(2), fork(2), getdta-
  blesize(2), lockf(3),	open(2), pipe(2), read(2), truncate(2),	write(2).

  Commands: rpc.lockd(8), rpc.statd(8).

  Standards: standards(5).