1.\" $NetBSD: dup.2,v 1.36 2024/11/01 18:48:17 nia Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)dup.2 8.1 (Berkeley) 6/4/93 31.\" 32.Dd November 1, 2024 33.Dt DUP 2 34.Os 35.Sh NAME 36.Nm dup , 37.Nm dup2 , 38.Nm dup3 39.Nd duplicate an existing file descriptor 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In unistd.h 44.Ft int 45.Fn dup "int oldfd" 46.Ft int 47.Fn dup2 "int oldfd" "int newfd" 48.Ft int 49.Fn dup3 "int oldfd" "int newfd" "int flags" 50.Sh DESCRIPTION 51The 52.Fn dup 53family of calls duplicates an existing file descriptor 54.Fa oldfd . 55A new file descriptor is produced; it is a new reference to the same 56underlying system object. 57The object in question does not distinguish between the descriptors 58referencing it in any way. 59Thus for files, 60.Xr read 2 , 61.Xr write 2 62and 63.Xr lseek 2 64calls all move a single shared seek position. 65Similarly, all object modes, settings, properties, and behavior other 66than the close-on-exec flag are shared between references. 67This includes the setting of append mode, non-blocking I/O actions, 68asynchronous I/O operations in progress, socket options, and so forth. 69The close-on-exec flag, however, is a property of the descriptor 70rather than the object and can be set independently for each 71reference. 72.Pp 73To get an independent handle with its own seek position and settings, 74an additional 75.Xr open 2 76call must be issued. 77(This is not generally possible for pipes and sockets.) 78.Pp 79The 80.Fn dup 81call chooses the new descriptor: it is the lowest-numbered descriptor 82not currently in use. 83The 84.Fn dup2 85and 86.Fn dup3 87calls allow the caller to choose the new descriptor by passing 88.Fa newfd , 89which must be within the range of valid descriptors. 90If 91.Fa newfd 92is the same as 93.Fa oldfd , 94the call has no effect. 95Otherwise, if 96.Fa newfd 97is already in use, it is closed as if 98.Xr close 2 99had been called. 100.Pp 101File descriptors are small non-negative integers that index into the 102per-process file table. 103Values 0, 1, and 2 have the special property that they are treated as 104standard input, standard output, and standard error respectively. 105(The constants 106.Dv STDIN_FILENO , 107.Dv STDOUT_FILENO , 108and 109.Dv STDERR_FILENO 110are provided as symbolic forms for these values.) 111The maximum value for a file descriptor is one less than the file 112table size. 113The file table size can be interrogated with 114.Xr getdtablesize 3 115and can to some extent be adjusted with 116.Xr setrlimit 2 . 117.Pp 118The 119.Fn dup3 120call fails and returns 121.Er EINVAL 122if the numeric value in the 123.Ar oldfd 124argument is equal to the one in the 125.Ar newfd 126argument. 127It also includes an additional 128.Fa flags 129argument supporting a subset of the 130.Xr open 2 131flags: 132.Bl -tag -width O_NOSIGPIPE -offset indent 133.It Dv O_CLOEXEC 134Set the close-on-exec flag on 135.Fa newfd . 136.It Dv O_NONBLOCK 137Sets non-blocking I/O. 138.It Dv O_NOSIGPIPE 139For pipes and sockets, do not raise 140.Dv SIGPIPE 141when a write is made to a broken pipe. 142Instead, the write will fail with 143.Er EPIPE . 144.El 145As described above, only the close-on-exec flag is 146per-file-descriptor, so passing any of the other 147.Fa flags 148will affect 149both 150.Fa oldfd 151and 152.Fa newfd . 153These settings are, however, applied atomically along with the rest of 154the 155.Fn dup3 156operation. 157.Pp 158In the case of 159.Fn dup 160and 161.Fn dup2 162the close-on-exec flag on the new file descriptor is always left 163unset and all the modes and settings of the underlying object are left 164unchanged. 165.Pp 166Functionality similar to 167.Fn dup 168with slightly different semantics is also available via 169.Xr fcntl 2 . 170.Sh RETURN VALUES 171These calls return the new file descriptor value. 172In the case of 173.Fn dup2 174and 175.Fn dup3 176this is always the same as 177.Fa newfd . 178If an error occurs, the value \-1 is returned and 179.Va errno 180is set to indicate what happened. 181.Sh EXAMPLES 182A common use for these functions is to set up a pipe as the standard 183input or standard output of a subprocess. 184That is done approximately as follows (error handling omitted for 185clarity): 186.Bd -literal -offset indent 187#include <unistd.h> 188 189int fds[2]; 190pid_t pid; 191 192pipe(fds); 193pid = fork(); 194if (pid == 0) { 195 /* child; use read end of pipe to stdin */ 196 dup2(fds[0], STDIN_FILENO); 197 close(fds[0]); 198 close(fds[1]); 199 execv("/some/program", args); 200} 201/* parent process; return write end of pipe */ 202close(fds[0]); 203return fds[1]; 204.Ed 205.Sh ERRORS 206These functions fail if: 207.Bl -tag -width Er 208.It Bq Er EBADF 209.Fa oldfd 210is not a valid active descriptor, or for 211.Fn dup2 212and 213.Fn dup3 , 214.Fa newfd 215is not in the range of valid file descriptors. 216.It Bq Er EINVAL 217In the 218.Fn dup3 219call either the 220.Fa flags 221argument contained an invalid value or the 222.Ar oldfd 223argument is equal to the 224.Ar newfd 225argument. 226.It Bq Er EMFILE 227Too many descriptors are active. 228Only 229.Fn dup 230can generate this error. 231.El 232.Sh SEE ALSO 233.Xr accept 2 , 234.Xr close 2 , 235.Xr fcntl 2 , 236.Xr getrlimit 2 , 237.Xr open 2 , 238.Xr pipe 2 , 239.Xr setrlimit 2 , 240.Xr socket 2 , 241.Xr socketpair 2 , 242.Xr getdtablesize 3 243.Sh STANDARDS 244The 245.Fn dup 246and 247.Fn dup2 248functions conform to 249.St -p1003.1-90 . 250The 251.Fn dup3 252function conforms to 253.St -p1003.1-2024 . 254.Sh HISTORY 255The 256.Fn dup3 257function originated in Linux and appeared in 258.Nx 6.0 . 259