*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> dup2 (2)              
Title
Content
Arch
Section
 

fcntl(2)

Contents


NAME    [Toc]    [Back]

       fcntl, dup, dup2 - Control open file descriptors

SYNOPSIS    [Toc]    [Back]

       #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    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards 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    [Toc]    [Back]

       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 parameter.  The standard
 allows for a list of variables, but does not  specify
       them.  These can vary with each vendor's implementation of
       this function.  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    [Toc]    [Back]

       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 descriptors 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
       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.  [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 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 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.  [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 daemon (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  operations
  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    [Toc]    [Back]
       [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 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
       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 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
       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  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 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,  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 argument 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 operation 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 <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_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  previous example is attempting to determine the
       I/O mode setting. The setting could also have been  specified
 as ADVFS_SYNC_WRITE.

NOTES    [Toc]    [Back]

       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    [Toc]    [Back]

       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    [Toc]    [Back]

       The fcntl() function sets errno to  the  specified  values
       for the following 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 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.   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 kernel
              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 descriptor  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 interrupted 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    [Toc]    [Back]

      
      
       Functions: close(2), creat(2), dup(2), exec(2),  flock(2),
       fork(2),   getdtablesize(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)
[ Back ]
 Similar pages
Name OS Title
lockf Tru64 Lock and unlocks regions of open file descriptors
sendfile Linux transfer data between file descriptors
poll HP-UX monitor I/O conditions on multiple file descriptors
poll Tru64 Monitor conditions on multiple file descriptors
poll HP-UX monitor I/O conditions on multiple file descriptors
maxfiles_lim HP-UX hard maximum number of file descriptors per process
devpoll.h Tru64 Device driver for a fast poll on many file descriptors
VkInput IRIX Encapsulation class for input callbacks on file descriptors
poll Tru64 Device driver for a fast poll on many file descriptors
maxfiles HP-UX initial (soft) maximum number of file descriptors per process
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service