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