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