1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)dup.2 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD: src/lib/libc/sys/dup.2,v 1.9.2.6 2001/12/14 18:34:00 ru Exp $ 34.\" 35.Dd June 4, 1993 36.Dt DUP 2 37.Os 38.Sh NAME 39.Nm dup , 40.Nm dup2 41.Nd duplicate an existing file descriptor 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.In unistd.h 46.Ft int 47.Fn dup "int oldd" 48.Ft int 49.Fn dup2 "int oldd" "int newd" 50.Sh DESCRIPTION 51.Fn Dup 52duplicates an existing object descriptor and returns its value to 53the calling process 54.Fa ( newd 55= 56.Fn dup oldd ) . 57The argument 58.Fa oldd 59is a small non-negative integer index in 60the per-process descriptor table. The value must be less 61than the size of the table, which is returned by 62.Xr getdtablesize 2 . 63The new descriptor returned by the call 64is the lowest numbered descriptor 65currently not in use by the process. 66.Pp 67The object referenced by the descriptor does not distinguish 68between 69.Fa oldd 70and 71.Fa newd 72in any way. 73Thus if 74.Fa newd 75and 76.Fa oldd 77are duplicate references to an open 78file, 79.Xr read 2 , 80.Xr write 2 81and 82.Xr lseek 2 83calls all move a single pointer into the file, 84and append mode, non-blocking I/O and asynchronous I/O options 85are shared between the references. 86If a separate pointer into the file is desired, a different 87object reference to the file must be obtained by issuing an 88additional 89.Xr open 2 90call. 91The close-on-exec flag on the new file descriptor is unset. 92.Pp 93In 94.Fn dup2 , 95the value of the new descriptor 96.Fa newd 97is specified. If this descriptor is already in use and 98.Fa oldd 99\*(Ne 100.Fa newd , 101the descriptor is first deallocated as if a 102.Xr close 2 103call had been used. 104If 105.Fa oldd 106is not a valid descriptor, then 107.Fa newd 108is not closed. 109If 110.Fa oldd 111== 112.Fa newd 113and 114.Fa oldd 115is a valid descriptor, then 116.Fn dup2 117is successful, and does nothing. 118.Sh RETURN VALUES 119The value -1 is returned if an error occurs in either call. 120The external variable 121.Va errno 122indicates the cause of the error. 123.Sh ERRORS 124.Fn Dup 125and 126.Fn dup2 127fail if: 128.Bl -tag -width Er 129.It Bq Er EBADF 130.Fa Oldd 131or 132.Fa newd 133is not a valid active descriptor 134.It Bq Er EMFILE 135Too many descriptors are active. 136.El 137.Sh SEE ALSO 138.Xr accept 2 , 139.Xr close 2 , 140.Xr fcntl 2 , 141.Xr getdtablesize 2 , 142.Xr open 2 , 143.Xr pipe 2 , 144.Xr socket 2 , 145.Xr socketpair 2 146.Sh STANDARDS 147The 148.Fn dup 149and 150.Fn dup2 151function calls are expected to conform to 152.St -p1003.1-90 . 153.Sh HISTORY 154A 155.Fn dup 156and a 157.Fn dup2 158function call appeared in 159.At v7 . 160