lib/libc/sys/dup.2

   1 .\"     $NetBSD: dup.2,v 1.30 2013/12/25 02:49:52 wiz 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. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)dup.2       8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd December 24, 2013
  33 .Dt DUP 2
  34 .Os
  35 .Sh NAME
  36 .Nm dup ,
  37 .Nm dup2 ,
  38 .Nm dup3
  39 .Nd duplicate an existing file descriptor
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In unistd.h
  44 .Ft int
  45 .Fn dup "int oldfd"
  46 .Ft int
  47 .Fn dup2 "int oldfd" "int newfd"
  48 .Ft int
  49 .Fn dup3 "int oldfd" "int newfd" "int flags"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn dup
  53 family of calls duplicates an existing file descriptor
  54 .Fa oldfd .
  55 A new file descriptor is produced; it is a new reference to the same
  56 underlying system object.
  57 The object in question does not distinguish between the descriptors
  58 referencing it in any way.
  59 Thus for files,
  60 .Xr read 2 ,
  61 .Xr write 2
  62 and
  63 .Xr lseek 2
  64 calls all move a single shared seek position.
  65 Similarly, all object modes, settings, properties, and behavior other
  66 than the close-on-exec flag are shared between references.
  67 This includes the setting of append mode, non-blocking I/O actions,
  68 asynchronous I/O operations in progress, socket options, and so forth.
  69 The close-on-exec flag, however, is a property of the descriptor
  70 rather than the object and can be set independently for each
  71 reference.
  72 .Pp
  73 To get an independent handle with its own seek position and settings,
  74 an additional
  75 .Xr open 2
  76 call must be issued.
  77 (This is not generally possible for pipes and sockets.)
  78 .Pp
  79 The
  80 .Nm dup
  81 call chooses the new descriptor: it is the lowest-numbered descriptor
  82 not currently in use.
  83 The
  84 .Nm dup2
  85 and
  86 .Nm dup3
  87 calls allow the caller to choose the new descriptor by passing
  88 .Fa newfd ,
  89 which must be within the range of valid descriptors.
  90 If
  91 .Fa newfd
  92 is the same as
  93 .Fa oldfd ,
  94 the call has no effect.
  95 Otherwise, if
  96 .Fa newfd
  97 is already in use, it is closed as if
  98 .Xr close 2
  99 had been called.
 100 .Pp
 101 File descriptors are small non-negative integers that index into the
 102 per-process file table.
 103 Values 0, 1, and 2 have the special property that they are treated as
 104 standard input, standard output, and standard error respectively.
 105 (The constants
 106 .Dv STDIN_FILENO ,
 107 .Dv STDOUT_FILENO ,
 108 and
 109 .Dv STDERR_FILENO
 110 are provided as symbolic forms for these values.)
 111 The maximum value for a file descriptor is one less than the file
 112 table size.
 113 The file table size can be interrogated with
 114 .Xr getdtablesize 3
 115 and can to some extent be adjusted with
 116 .Xr setrlimit 2 .
 117 .Pp
 118 The
 119 .Fn dup3
 120 call includs an additional
 121 .Fa flags
 122 argument supporting a subset of the
 123 .Xr open 2
 124 flags:
 125 .Bl -tag -width O_NOSIGPIPE -offset indent
 126 .It Dv O_CLOEXEC
 127 Set the close-on-exec flag on
 128 .Fa newfd .
 129 .It Dv O_NONBLOCK
 130 Sets non-blocking I/O.
 131 .It Dv O_NOSIGPIPE
 132 For pipes and sockets, do not raise
 133 .Dv SIGPIPE
 134 when a write is made to a broken pipe.
 135 Instead, the write will fail with
 136 .Er EPIPE .
 137 .El
 138 As described above, only the close-on-exec flag is
 139 per-file-descriptor, so passing any of the other
 140 .Fa flags
 141 will affect
 142 both
 143 .Fa oldfd
 144 and
 145 .Fa newfd .
 146 These settings are, however, applied atomically along with the rest of
 147 the
 148 .Fn dup3
 149 operation.
 150 .Pp
 151 In the case of
 152 .Fn dup
 153 and
 154 .Fn dup2
 155 the close-on-exec flag on the new file descriptor is always left
 156 unset and all the modes and settings of the underlying object are left
 157 unchanged.
 158 .Pp
 159 Functionality similar to
 160 .Fn dup
 161 with slightly different semantics is also available via
 162 .Xr fcntl 2 .
 163 .Sh RETURN VALUES
 164 These calls return the new file descriptor value.
 165 In the case of
 166 .Fn dup2
 167 and
 168 .Fn dup3
 169 this is always the same as
 170 .Fa newfd .
 171 If an error occurs, the value \-1 is returned and
 172 .Va errno
 173 is set to indicate what happened.
 174 .Sh EXAMPLES
 175 A common use for these functions is to set up a pipe as the standard
 176 input or standard output of a subprocess.
 177 That is done approximately as follows (error handling omitted for
 178 clarity):
 179 .Bd -literal -offset indent
 180 #include \*[Lt]unistd.h\*[Gt]
 181
 182 int fds[2];
 183 pid_t pid;
 184
 185 pipe(fds);
 186 pid = fork();
 187 if (pid == 0) {
 188         /* child; use read end of pipe to stdin */
 189         dup2(fds[0], STDIN_FILENO);
 190         close(fds[0]);
 191         close(fds[1]);
 192         execv("/some/program", args);
 193 }
 194 /* parent process; return write end of pipe */
 195 close(fds[0]);
 196 return fds[1];
 197 .Ed
 198 .Sh ERRORS
 199 These functions fail if:
 200 .Bl -tag -width Er
 201 .It Bq Er EBADF
 202 .Fa oldfd
 203 is not a valid active descriptor, or for
 204 .Fn dup2
 205 and
 206 .Fn dup3 ,
 207 .Fa newfd
 208 is not in the range of valid file descriptors.
 209 .It Bq Er EINVAL
 210 .Fa flags
 211 contained an invalid value.
 212 Only
 213 .Fn dup3
 214 can generate this error.
 215 .It Bq Er EMFILE
 216 Too many descriptors are active.
 217 Only
 218 .Fn dup
 219 can generate this error.
 220 .El
 221 .Sh SEE ALSO
 222 .Xr accept 2 ,
 223 .Xr close 2 ,
 224 .Xr fcntl 2 ,
 225 .Xr getrlimit 2 ,
 226 .Xr open 2 ,
 227 .Xr pipe 2 ,
 228 .Xr setrlimit 2 ,
 229 .Xr socket 2 ,
 230 .Xr socketpair 2 ,
 231 .Xr getdtablesize 3
 232 .Sh STANDARDS
 233 The
 234 .Fn dup
 235 and
 236 .Fn dup2
 237 functions conform to
 238 .St -p1003.1-90 .
 239 .Sh HISTORY
 240 The
 241 .Fn dup3
 242 function originated in Linux and appeared in
 243 .Nx 6.0 .