dup man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=dup&af=0&tf=2&of=DigitalUNIX

fcntl(2)							      fcntl(2)

NAME
       fcntl, dup, dup2 - Control open file descriptors

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

       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 stan‐
       dards as follows:

       dup(), dup2():	XSH4.0, XSH4.2, XSH5.0

       fcntl():	  XSH4.0, XSH4.2,XSH5.0, XNS4.0, XNS5.0

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

PARAMETERS
       Specifies  an  open  file descriptor obtained from a successful open(),
       fcntl(), or pipe() function.  Specifies the operation to be  performed.
       Specifies  a  variable that depends on the value of the request parame‐
       ter.  The standard allows for a list of variables, but does not specify
       them.   These  can vary with each vendor's implementation of this func‐
       tion.  Specifies an open file descriptor that is returned by the dup2()
       function.   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
       calling thread is suspended rather than	all  threads  in  the  calling
       process.

       The following are values for the request parameter:

       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 options. (That is, both file descrip‐
       tors  share  the	 same  file status options).  The close-on-exec option
       (FD_CLOEXEC bit) associated with the new file descriptor is cleared  so
       that  the  file will remain open across exec functions.	Gets the value
       of  the	close-on-exec  option  associated  with	 the  file  descriptor
       filedes.	 File  descriptor  options  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.	Sets the close-on-exec
       option associated with the filedes parameter to the value of the	 argu‐
       ment  parameter,	 taken	as  type  int.	If the argument parameter is 0
       (zero), the file remains open across the exec functions. If  the	 argu‐
       ment  parameter	is FD_CLOEXEC, the file is closed on successful execu‐
       tion of the next exec function.	[Tru64	UNIX]  Retrieves  the  current
       times for the file identified by filedes. For the F_GETTIMES and F_SET‐
       TIMES 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 moving the
       file,  set  back	 atime	or  mtime  without  changing  ctime.	[Tru64
       UNIX]  Sets  the current times for the file identified by filedes. This
       request requires superuser privilege and returns the [EPERM]  error  on
       an attempt to set the file's times without this privilege.

	      The  following example illustrates how to use the F_GETTIMES and
	      F_SETTIMES requests:

	      #	 include  <stdio.h>  #	 include   <sys/fcntl.h>   #   include
	      <sys/fcntl1.h> main() {
		   char buffer[1024];
		   int fd,bytesread;
		   struct attr_timbuf  tstamp;

		   /* Create a file*/
		   fd=open("/usr/tmp/foo",O_CREAT|O_RDONLY);
		   if(fd > 0) {
			/* Display the atime and ctime of the file */
			printf("atime before reading the file:\n");
			system("ls -lu /usr/tmp/foo");
			printf("ctime before reading the file:\n");
			system("ls -lc /usr/tmp/foo");
			if(fcntl(fd,F_GETTIMES,&tstamp) < 0) {
			     perror("fcntl:F_GETTIMES");
			     exit(1);
			}
		   }
		   else {
			perror("open");
			exit(1);
		   }

		   printf("Sleeping  for  one minute because ls commands can \
	      show time change only in terms of hours and minutes...\n");
		   sleep(60);

		   /* Access the file */
		   bytesread=read(fd,buffer,1024);
		   if(bytesread >= 0) {
			/* Again display the atime and ctime of the file */
			printf("\n\natime after reading the file:\n");
			system( "ls -lu /usr/tmp/foo");
			printf("ctime after reading the file:\n");
			system( "ls -lc /usr/tmp/foo");

		   /* Now use F_SETTIMES to reinstate the original atime */
			if(fcntl(fd,F_SETTIMES,&tstamp) < 0) {
			     perror("fcntl:F_SETTIMES");
			     exit(1);
			}
			else {
			     printf("\n\nAfter	using  F_SETTIMES,  atime   is
	      reset \ without affecting ctime\n");

			     printf("\tatime:\n");
			     system( "ls -lu /usr/tmp/foo");
			     printf("\tctime:\n");
			     system( "ls -lc /usr/tmp/foo");
			}
		   }
		   else
			perror("read");

		   system("rm  -rf  /usr/tmp/foo");  }	Gets  the  file status
	      options 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
	      options  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.  Sets the file status options  to
	      the argument parameter, taken as type int, for the file to which
	      the filedes parameter  refers.  The  file	 access	 mode  is  not
	      changed.

       [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.  [XNS5.0]	  If filedes refers to
       a socket, sets the process or process group ID to receive  SIGURG  sig‐
       nals  when  out-of-band data is available, using the value of the argu‐
       ment 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.	[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.
       [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.  [Tru64 UNIX]   Reserved for use by the network lock dae‐
       mon (rpc.lockd(8)) on NFS servers to acquire locks requested by F_SETLK
       on  NFS	clients.   [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.	 [Tru64 UNIX]	Performs AdvFS-specific opera‐
       tions on AdvFS files. The value expects that the argument parameter  is
       a pointer to a advfs_opT structure as described in the <fcntl.h> header
       file.

       The following values for the request parameter are available for record
       locking:	 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.   Sets  or
       clears a file segment lock according to the lock description 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
	      existing	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. Otherwise, an unlock (F_UNLCK)	 request  attempts  to	unlock
	      only  the	 requested  file.   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 <fcntl.h> 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.   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.

       [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	opera‐
       tions  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 descriptor 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 defini‐
       tion 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  beginning 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 seg‐
       ment  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 process 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, how‐
       ever, 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
       argument	 parameter  is expected to be a pointer to an advfs_opT struc‐
       ture. The operation field of the advfs_opT structure specifies the gen‐
       eral  kind  of  operation.  The action field of the advfs_opT structure
       refines the operation field in order to specify more exactly the opera‐
       tion  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
       <fcntl.h> 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_ACTI‐
       VATE; 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
       previous 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) and fcntl(oldfiledes, F_DUPFD, newfiledes).

RETURN VALUES
       Upon successful completion, the value returned depends on the value  of
       the  request  parameter	as  follows:  Returns  a  new file descriptor.
       Returns FD_CLOEXEC or  0	 (zero).   Returns  a  value  other  than  -1.
       Returns	the value of file status options and access modes. (The return
       value will not be negative.)  Returns a value other than -1.  Returns a
       value  other  than  -1.	 Returns  a  value  other than -1.  [XNS5.0]
       Returns the value of the socket owner process or	 process  group;  this
       will  not  be -1.  [XNS5.0]   Returns a value other than -1.  Returns a
       value other than -1.  [Tru64 UNIX]   Returns a  value  other  than  -1.
       [Tru64 UNIX]   Returns a value other than -1.  [Tru64 UNIX]   Returns a
       value other than -1.  [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 follow‐
       ing conditions:

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

	      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 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.  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.
	      The  argument  parameter	is  an	invalid	 address.  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.  The request
	      parameter is F_DUPFD and too many or OPEN_MAX  file  descriptors
	      are  currently  open in the calling process, or no file descrip‐
	      tors greater than or equal to argument are available.

	      [Tru64 UNIX]   Either the OPEN_MAX value or the per-process soft
	      descriptor  limit	 is checked.  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.  [Tru64 UNIX]   The value of the request
	      parameter is F_SETOWN and the process ID given  as  argument  is
	      not  in  use.  The request parameter is F_SETLKW and the fcntl()
	      function was interrupted by a signal which was  caught.	[Tru64
	      UNIX]    The  request  parameter	is  F_GETMAP  and an I/O error
	      occurred on the disk where the file  is  located.	  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.	 [Tru64 UNIX]	The system was unable to allocate ker‐
	      nel memory for the requested file	 descriptor.   [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.  [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.

	      [Tru64  UNIX]  The  request parameter is F_SETTIMES and the user
	      does not have superuser privilege.

       The dup() and dup2() functions set errno to the	specified  values  for
       the following conditions: 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.  The filedes or old parameter
       is not a valid open file descriptor or the new parameter file  descrip‐
       tor is negative or greater than OPEN_MAX.

	      [Tru64 UNIX]   Either the OPEN_MAX value or the per-process soft
	      descriptor limit is checked.  The	 dup2()	 function  was	inter‐
	      rupted  by  a  signal  which  was	 caught.   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.
	      [Tru64 UNIX]   The file descriptor specified by filedes is on  a
	      remote machine and the link to that machine is no longer active.
	      [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,
       portable application programs should expect and test for either value.

SEE ALSO
       Functions: close(2), creat(2), dup(2), exec(2), flock(2), fork(2), get‐
       dtablesize(2),  open(2),	 pipe(2),  read(2),   truncate(2),   write(2),
       lockf(3)

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

       Standards: standards(5)

       Network Programmer's Guide

								      fcntl(2)
[top]

List of man pages available for DigitalUNIX

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