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