1.\" $OpenBSD: dup.2,v 1.18 2014/12/10 19:46:48 schwarze Exp $ 2.\" $NetBSD: dup.2,v 1.4 1995/02/27 12:32:21 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)dup.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: December 10 2014 $ 34.Dt DUP 2 35.Os 36.Sh NAME 37.Nm dup , 38.Nm dup2 , 39.Nm dup3 40.Nd duplicate an existing file descriptor 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn dup "int oldd" 45.Ft int 46.Fn dup2 "int oldd" "int newd" 47.In fcntl.h 48.In unistd.h 49.Ft int 50.Fn dup3 "int oldd" "int newd" "int flags" 51.Sh DESCRIPTION 52.Fn dup 53duplicates an existing object descriptor and returns its value to 54the calling process 55.Fa ( newd 56= 57.Fn dup oldd ) . 58The argument 59.Fa oldd 60is a small non-negative integer index in the per-process descriptor table. 61The value must be less than the size of the table, which is returned by 62.Xr getdtablesize 3 . 63The new descriptor returned by the call is the lowest numbered descriptor 64currently not in use by the process. 65.Pp 66The object referenced by the descriptor does not distinguish between 67.Fa oldd 68and 69.Fa newd 70in any way. 71Thus if 72.Fa newd 73and 74.Fa oldd 75are duplicate references to an open 76file, 77.Xr read 2 , 78.Xr write 2 79and 80.Xr lseek 2 81calls all move a single pointer into the file, 82and append mode, non-blocking I/O and asynchronous I/O options 83are shared between the references. 84If a separate pointer into the file is desired, a different 85object reference to the file must be obtained by issuing an 86additional 87.Xr open 2 88call. 89The close-on-exec flag on the new file descriptor is unset. 90.Pp 91In 92.Fn dup2 , 93the value of the new descriptor 94.Fa newd 95is specified. 96If this descriptor is already in use, it is first deallocated as if a 97.Xr close 2 98call had been done first. 99When 100.Fa newd 101equals 102.Fa oldd , 103.Fn dup2 104just returns without affecting the close-on-exec flag. 105.Pp 106In 107.Fn dup3 , 108both the value of the new descriptor and the close-on-exec flag on 109the new file descriptor are specified: 110.Fa newd 111specifies the value and the 112.Dv O_CLOEXEC 113bit in 114.Fa flags 115specifies the close-on-exec flag. 116Unlike 117.Fn dup2 , 118if 119.Fa oldd 120and 121.Fa newd 122are equal then 123.Fn dup3 124fails. 125Otherwise, if 126.Fa flags 127is zero then 128.Fn dup3 129is identical to a call to 130.Fn dup2 . 131.Sh RETURN VALUES 132Upon successful completion, the value of the new descriptor is returned. 133The value \-1 is returned if an error occurs in either call. 134The external variable 135.Va errno 136indicates the cause of the error. 137.Sh ERRORS 138.Fn dup 139will fail if: 140.Bl -tag -width Er 141.It Bq Er EBADF 142.Fa oldd 143is not a valid active descriptor. 144.It Bq Er EMFILE 145Too many descriptors are active. 146.El 147.Pp 148.Fn dup2 149and 150.Fn dup3 151will fail if: 152.Bl -tag -width Er 153.It Bq Er EBADF 154.Fa oldd 155is not a valid active descriptor or 156.Fa newd 157is negative or greater than or equal to the process's 158.Dv RLIMIT_NOFILE 159limit. 160.It Bq Er EINTR 161An interrupt was received. 162.It Bq Er EIO 163An I/O error occurred while writing to the file system. 164.El 165.Pp 166In addition, 167.Fn dup3 168will return the following error: 169.Bl -tag -width Er 170.It Bq Er EINVAL 171.Fa oldd 172is equal to 173.Fa newd 174or 175.Fa flags 176is invalid. 177.El 178.Sh SEE ALSO 179.Xr accept 2 , 180.Xr close 2 , 181.Xr fcntl 2 , 182.Xr getrlimit 2 , 183.Xr open 2 , 184.Xr pipe 2 , 185.Xr socket 2 , 186.Xr socketpair 2 , 187.Xr getdtablesize 3 188.Sh STANDARDS 189.Fn dup 190and 191.Fn dup2 192conform to 193.St -p1003.1-2008 . 194The 195.Fn dup3 196function is expected to conform to a future revision of that standard. 197.Sh HISTORY 198The 199.Fn dup 200system call first appeared in 201.At v3 , 202.Fn dup2 203in 204.At v7 , 205and 206.Fn dup3 207in 208.Ox 5.7 . 209