Debian Codegraph @

upstream/debian-unstable/man2/dup.2

raw
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)