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 2022-09-09 "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 * 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 *
 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 * 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 *
 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 VERSIONS
 201 .BR dup3 ()
 202 was added to Linux in version 2.6.27;
 203 glibc support is available starting with
 204 version 2.9.
 205 .SH STANDARDS
 206 .BR dup (),
 207 .BR dup2 ():
 208 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 209 .PP
 210 .BR dup3 ()
 211 is Linux-specific.
 212 .\" SVr4 documents additional
 213 .\" EINTR and ENOLINK error conditions.  POSIX.1 adds EINTR.
 214 .\" The EBUSY return is Linux-specific.
 215 .SH NOTES
 216 The error returned by
 217 .BR dup2 ()
 218 is different from that returned by
 219 .BR fcntl( "..., " F_DUPFD ", ..." )
 220 when
 221 .I newfd
 222 is out of range.
 223 On some systems,
 224 .BR dup2 ()
 225 also sometimes returns
 226 .B EINVAL
 227 like
 228 .BR F_DUPFD .
 229 .PP
 230 If
 231 .I newfd
 232 was open, any errors that would have been reported at
 233 .BR close (2)
 234 time are lost.
 235 If this is of concern,
 236 then\(emunless the program is single-threaded and does not allocate
 237 file descriptors in signal handlers\(emthe correct approach is
 238 .I not
 239 to close
 240 .I newfd
 241 before calling
 242 .BR dup2 (),
 243 because of the race condition described above.
 244 Instead, code something like the following could be used:
 245 .PP
 246 .in +4n
 247 .EX
 248 /* Obtain a duplicate of \(aqnewfd\(aq that can subsequently
 249    be used to check for close() errors; an EBADF error
 250    means that \(aqnewfd\(aq was not open. */
 251
 252 tmpfd = dup(newfd);
 253 if (tmpfd == \-1 && errno != EBADF) {
 254     /* Handle unexpected dup() error. */
 255 }
 256
 257 /* Atomically duplicate \(aqoldfd\(aq on \(aqnewfd\(aq. */
 258
 259 if (dup2(oldfd, newfd) == \-1) {
 260     /* Handle dup2() error. */
 261 }
 262
 263 /* Now check for close() errors on the file originally
 264    referred to by \(aqnewfd\(aq. */
 265
 266 if (tmpfd != \-1) {
 267     if (close(tmpfd) == \-1) {
 268         /* Handle errors from close. */
 269     }
 270 }
 271 .EE
 272 .in
 273 .SH SEE ALSO
 274 .BR close (2),
 275 .BR fcntl (2),
 276 .BR open (2),
 277 .BR pidfd_getfd (2)