bsd/man/man2/dup.2

   1 .\"     $NetBSD: dup.2,v 1.4 1995/02/27 12:32:21 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)dup.2       8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd December 1, 2010
  37 .Dt DUP 2
  38 .Os BSD 4
  39 .Sh NAME
  40 .Nm dup ,
  41 .Nm dup2
  42 .Nd duplicate an existing file descriptor
  43 .Sh SYNOPSIS
  44 .Fd #include <unistd.h>
  45 .Ft int
  46 .Fo dup
  47 .Fa "int fildes"
  48 .Fc
  49 .Ft int
  50 .Fo dup2
  51 .Fa "int fildes"
  52 .Fa "int fildes2"
  53 .Fc
  54 .Sh DESCRIPTION
  55 .Fn Dup
  56 duplicates an existing object descriptor
  57 and returns its value to the calling process
  58 .Fa ( fildes2
  59 =
  60 .Fn dup fildes ) .
  61 The argument
  62 .Fa fildes
  63 is a small non-negative integer index
  64 in the per-process descriptor table.
  65 The value must be less than the size of the table,
  66 which is returned by
  67 .Xr getdtablesize 2 .
  68 The new descriptor returned by the call
  69 is the lowest numbered descriptor
  70 currently not in use by the process.
  71 .Pp
  72 The object referenced by the descriptor does not distinguish
  73 between
  74 .Fa fildes
  75 and
  76 .Fa fildes2
  77 in any way.
  78 Thus if
  79 .Fa fildes2
  80 and
  81 .Fa fildes
  82 are duplicate references to an open
  83 file,
  84 .Xr read 2 ,
  85 .Xr write 2
  86 and
  87 .Xr lseek 2
  88 calls all move a single pointer into the file,
  89 and append mode, non-blocking I/O and asynchronous I/O options
  90 are shared between the references.
  91 If a separate pointer into the file is desired,
  92 a different object reference to the file must be obtained
  93 by issuing an additional
  94 .Xr open 2
  95 call.
  96 The close-on-exec flag on the new file descriptor is unset.
  97 .Pp
  98 In
  99 .Fn dup2 ,
 100 the value of the new descriptor
 101 .Fa fildes2
 102 is specified.
 103 If
 104 .Fa fildes
 105 and
 106 .Fa fildes2
 107 are equal, then
 108 .Fn dup2
 109 just returns
 110 .Fa fildes2 ;
 111 no other changes are made to the existing descriptor.
 112 Otherwise, if descriptor
 113 .Fa fildes2
 114 is already in use, it is first deallocated as if a
 115 .Xr close 2
 116 call had been done first.
 117 .Sh RETURN VALUES
 118 Upon successful completion, the new file descriptor is returned.
 119 Otherwise, a value of -1 is returned and the global integer variable
 120 .Va errno
 121 is set to indicate the error.
 122 .Sh ERRORS
 123 The
 124 .Fn dup
 125 and
 126 .Fn dup2
 127 system calls will fail if:
 128 .Bl -tag -width Er
 129 .\" ==========
 130 .It Bq Er EBADF
 131 .Fa fildes
 132 is not an active, valid file descriptor.
 133 .\" ==========
 134 .It Bq Er EINTR
 135 Execution is interrupted by a signal.
 136 .\" ==========
 137 .It Bq Er EMFILE
 138 Too many file descriptors are active.
 139 .El
 140 .Pp
 141 The
 142 .Fn dup2
 143 system call will fail if:
 144 .Bl -tag -width Er
 145 .\" ==========
 146 .It Bq Er EBADF
 147 .Fa fildes2
 148 is negative or greater than the maximum allowable number (see getdtablesize(2)).
 149 .El
 150 .Sh SEE ALSO
 151 .Xr accept 2 ,
 152 .Xr close 2 ,
 153 .Xr fcntl 2 ,
 154 .Xr getdtablesize 2 ,
 155 .Xr open 2 ,
 156 .Xr pipe 2 ,
 157 .Xr socket 2 ,
 158 .Xr socketpair 2
 159 .Sh STANDARDS
 160 .Fn Dup
 161 and
 162 .Fn dup2
 163 are expected to conform to
 164 .St -p1003.1-88 .