man2/dup.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\" and Copyright (C) 2005, 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" Modified 1993-07-21, Rik Faith <faith@cs.unc.edu>
   9 .\" Modified 1994-08-21, Michael Chastain <mec@shell.portal.com>:
  10 .\"   Fixed typos.
  11 .\" Modified 1997-01-31, Eric S. Raymond <esr@thyrsus.com>
  12 .\" Modified 2002-09-28, aeb
  13 .\" 2009-01-12, mtk, reordered text in DESCRIPTION and added some
  14 .\"     details for dup2().
  15 .\" 2008-10-09, mtk: add description of dup3()
  16 .\"
  17 .TH dup 2 (date) "Linux man-pages (unreleased)"
  18 .SH NAME
  19 dup, dup2, dup3 \- duplicate a file descriptor
  20 .SH LIBRARY
  21 Standard C library
  22 .RI ( libc ", " \-lc )
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <unistd.h>
  26 .PP
  27 .BI "int dup(int " oldfd );
  28 .BI "int dup2(int " oldfd ", int " newfd );
  29 .PP
  30 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  31 .BR "#include <fcntl.h>" "              /* Definition of " O_* " constants */"
  32 .B #include <unistd.h>
  33 .PP
  34 .BI "int dup3(int " oldfd ", int " newfd ", int " flags );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR dup ()
  39 system call allocates a new file descriptor that refers to the same
  40 open file description as the descriptor
  41 .IR oldfd .
  42 (For an explanation of open file descriptions, see
  43 .BR open (2).)
  44 The new file descriptor number is guaranteed to be the lowest-numbered
  45 file descriptor that was unused in the calling process.
  46 .PP
  47 After a successful return,
  48 the old and new file descriptors may be used interchangeably.
  49 Since the two file descriptors refer to the same open file description,
  50 they share file offset and file status flags;
  51 for example, if the file offset is modified by using
  52 .BR lseek (2)
  53 on one of the file descriptors,
  54 the offset is also changed for the other file descriptor.
  55 .PP
  56 The two file descriptors do not share file descriptor flags
  57 (the close-on-exec flag).
  58 The close-on-exec flag
  59 .RB ( FD_CLOEXEC ;
  60 see
  61 .BR fcntl (2))
  62 for the duplicate descriptor is off.
  63 .\"
  64 .SS dup2()
  65 The
  66 .BR dup2 ()
  67 system call performs the same task as
  68 .BR dup (),
  69 but instead of using the lowest-numbered unused file descriptor,
  70 it uses the file descriptor number specified in
  71 .IR newfd .
  72 In other words,
  73 the file descriptor
  74 .I newfd
  75 is adjusted so that it now refers to the same open file description as
  76 .IR oldfd .
  77 .PP
  78 If the file descriptor
  79 .I newfd
  80 was previously open, it is closed before being reused;
  81 the close is performed silently
  82 (i.e., any errors during the close are not reported by
  83 .BR dup2 ()).
  84 .PP
  85 The steps of closing and reusing the file descriptor
  86 .I newfd
  87 are performed
  88 .IR atomically .
  89 This is important, because trying to implement equivalent functionality using
  90 .BR close (2)
  91 and
  92 .BR dup ()
  93 would be
  94 subject to race conditions, whereby
  95 .I newfd
  96 might be reused between the two steps.
  97 Such reuse could happen because the main program is interrupted
  98 by a signal handler that allocates a file descriptor,
  99 or because a parallel thread allocates a file descriptor.
 100 .PP
 101 Note the following points:
 102 .IP \[bu] 3
 103 If
 104 .I oldfd
 105 is not a valid file descriptor, then the call fails, and
 106 .I newfd
 107 is not closed.
 108 .IP \[bu]
 109 If
 110 .I oldfd
 111 is a valid file descriptor, and
 112 .I newfd
 113 has the same value as
 114 .IR oldfd ,
 115 then
 116 .BR dup2 ()
 117 does nothing, and returns
 118 .IR newfd .
 119 .\"
 120 .SS dup3()
 121 .BR dup3 ()
 122 is the same as
 123 .BR dup2 (),
 124 except that:
 125 .IP \[bu] 3
 126 The caller can force the close-on-exec flag to be set
 127 for the new file descriptor by specifying
 128 .B O_CLOEXEC
 129 in
 130 .IR flags .
 131 See the description of the same flag in
 132 .BR open (2)
 133 for reasons why this may be useful.
 134 .IP \[bu]
 135 .\" Ulrich Drepper, LKML, 2008-10-09:
 136 .\"     We deliberately decided on this change.  Otherwise, what is the
 137 .\"     result of dup3(fd, fd, O_CLOEXEC)?
 138 If
 139 .I oldfd
 140 equals
 141 .IR newfd ,
 142 then
 143 .BR dup3 ()
 144 fails with the error
 145 .BR EINVAL .
 146 .SH RETURN VALUE
 147 On success, these system calls
 148 return the new file descriptor.
 149 On error, \-1 is returned, and
 150 .I errno
 151 is set to indicate the error.
 152 .SH ERRORS
 153 .TP
 154 .B EBADF
 155 .I oldfd
 156 isn't an open file descriptor.
 157 .TP
 158 .B EBADF
 159 .I newfd
 160 is out of the allowed range for file descriptors (see the discussion of
 161 .B RLIMIT_NOFILE
 162 in
 163 .BR getrlimit (2)).
 164 .TP
 165 .B EBUSY
 166 (Linux only) This may be returned by
 167 .BR dup2 ()
 168 or
 169 .BR dup3 ()
 170 during a race condition with
 171 .BR open (2)
 172 and
 173 .BR dup ().
 174 .TP
 175 .B EINTR
 176 The
 177 .BR dup2 ()
 178 or
 179 .BR dup3 ()
 180 call was interrupted by a signal; see
 181 .BR signal (7).
 182 .TP
 183 .B EINVAL
 184 .RB ( dup3 ())
 185 .I flags
 186 contain an invalid value.
 187 .TP
 188 .B EINVAL
 189 .RB ( dup3 ())
 190 .I oldfd
 191 was equal to
 192 .IR newfd .
 193 .TP
 194 .B EMFILE
 195 The per-process limit on the number of open file descriptors has been reached
 196 (see the discussion of
 197 .B RLIMIT_NOFILE
 198 in
 199 .BR getrlimit (2)).
 200 .SH STANDARDS
 201 .TP
 202 .BR dup ()
 203 .TQ
 204 .BR dup2 ()
 205 POSIX.1-2008.
 206 .TP
 207 .BR dup3 ()
 208 Linux.
 209 .SH HISTORY
 210 .TP
 211 .BR dup ()
 212 .TQ
 213 .BR dup2 ()
 214 POSIX.1-2001, SVr4, 4.3BSD.
 215 .\" SVr4 documents additional
 216 .\" EINTR and ENOLINK error conditions.  POSIX.1 adds EINTR.
 217 .\" The EBUSY return is Linux-specific.
 218 .TP
 219 .BR dup3 ()
 220 Linux 2.6.27,
 221 glibc 2.9.
 222 .SH NOTES
 223 The error returned by
 224 .BR dup2 ()
 225 is different from that returned by
 226 .BR fcntl( "..., " F_DUPFD ", ..." )
 227 when
 228 .I newfd
 229 is out of range.
 230 On some systems,
 231 .BR dup2 ()
 232 also sometimes returns
 233 .B EINVAL
 234 like
 235 .BR F_DUPFD .
 236 .PP
 237 If
 238 .I newfd
 239 was open, any errors that would have been reported at
 240 .BR close (2)
 241 time are lost.
 242 If this is of concern,
 243 then\[em]unless the program is single-threaded and does not allocate
 244 file descriptors in signal handlers\[em]the correct approach is
 245 .I not
 246 to close
 247 .I newfd
 248 before calling
 249 .BR dup2 (),
 250 because of the race condition described above.
 251 Instead, code something like the following could be used:
 252 .PP
 253 .in +4n
 254 .EX
 255 /* Obtain a duplicate of \[aq]newfd\[aq] that can subsequently
 256    be used to check for close() errors; an EBADF error
 257    means that \[aq]newfd\[aq] was not open. */
 258
 259 tmpfd = dup(newfd);
 260 if (tmpfd == \-1 && errno != EBADF) {
 261     /* Handle unexpected dup() error. */
 262 }
 263
 264 /* Atomically duplicate \[aq]oldfd\[aq] on \[aq]newfd\[aq]. */
 265
 266 if (dup2(oldfd, newfd) == \-1) {
 267     /* Handle dup2() error. */
 268 }
 269
 270 /* Now check for close() errors on the file originally
 271    referred to by \[aq]newfd\[aq]. */
 272
 273 if (tmpfd != \-1) {
 274     if (close(tmpfd) == \-1) {
 275         /* Handle errors from close. */
 276     }
 277 }
 278 .EE
 279 .in
 280 .SH SEE ALSO
 281 .BR close (2),
 282 .BR fcntl (2),
 283 .BR open (2),
 284 .BR pidfd_getfd (2)