1*47208Scael.\" Copyright (c) 1980, 1991 Regents of the University of California. 2*47208Scael.\" All rights reserved. 320068Smckusick.\" 4*47208Scael.\" %sccs.include.redist.man% 520068Smckusick.\" 6*47208Scael.\" @(#)dup.2 6.4 (Berkeley) 03/10/91 7*47208Scael.\" 8*47208Scael.Dd 9*47208Scael.Dt DUP 2 10*47208Scael.Os BSD 4 11*47208Scael.Sh NAME 12*47208Scael.Nm dup , 13*47208Scael.Nm dup2 14*47208Scael.Nd duplicate an existing file descriptor 15*47208Scael.Sh SYNOPSIS 16*47208Scael.Fd #include <unistd.h> 17*47208Scael.Ft int 18*47208Scael.Fn dup "int oldd" 19*47208Scael.Ft int 20*47208Scael.Fn dup2 "int oldd" "int newd" 21*47208Scael.Sh DESCRIPTION 22*47208Scael.Fn Dup 23*47208Scaelduplicates an existing object descriptor and returns its value to 24*47208Scaelthe calling process 25*47208Scael.Fa ( newd 26*47208Scael= 27*47208Scael.Fn dup oldd ) . 28*47208ScaelThe argument 29*47208Scael.Fa oldd 30*47208Scaelis a small non-negative integer index in 3120069Smckusickthe per-process descriptor table. The value must be less 3220069Smckusickthan the size of the table, which is returned by 33*47208Scael.Xr getdtablesize 2 . 34*47208ScaelThe new descriptor returned by the call 35*47208Scaelis the lowest numbered descriptor 36*47208Scaelcurrently not in use by the process. 37*47208Scael.Pp 3820069SmckusickThe object referenced by the descriptor does not distinguish 39*47208Scaelbetween 40*47208Scael.Fa oldd 41*47208Scaeland 42*47208Scael.Fa newd 43*47208Scaelin any way. 44*47208ScaelThus if 45*47208Scael.Fa newd 46*47208Scaeland 47*47208Scael.Fa oldd 48*47208Scaelare duplicate references to an open 4920069Smckusickfile, 50*47208Scael.Xr read 2 , 51*47208Scael.Xr write 2 5220069Smckusickand 53*47208Scael.Xr lseek 2 5428067Skarelscalls all move a single pointer into the file, 5528067Skarelsand append mode, non-blocking I/O and asynchronous I/O options 5628067Skarelsare shared between the references. 5720069SmckusickIf a separate pointer into the file is desired, a different 5820069Smckusickobject reference to the file must be obtained by issuing an 5920069Smckusickadditional 60*47208Scael.Xr open 2 6120069Smckusickcall. 6228067SkarelsThe close-on-exec flag on the new file descriptor is unset. 63*47208Scael.Pp 64*47208ScaelIn 65*47208Scael.Fn dup2 , 66*47208Scaelthe value of the new descriptor 67*47208Scael.Fa newd 68*47208Scaelis specified. If this descriptor is already 6920069Smckusickin use, the descriptor is first deallocated as if a 70*47208Scael.Xr close 2 7120069Smckusickcall had been done first. 72*47208Scael.Sh RETURN VALUES 73*47208ScaelThe value -1 is returned if an error occurs in either call. 7420069SmckusickThe external variable 75*47208Scael.Va errno 7620069Smckusickindicates the cause of the error. 77*47208Scael.Sh ERRORS 78*47208Scael.Fn Dup 7920069Smckusickand 80*47208Scael.Fn dup2 8120069Smckusickfail if: 82*47208Scael.Bl -tag -width Er 83*47208Scael.It Bq Er EBADF 84*47208Scael.Fa Oldd 85*47208Scaelor 86*47208Scael.Fa newd 87*47208Scaelis not a valid active descriptor 88*47208Scael.It Bq Er EMFILE 8920069SmckusickToo many descriptors are active. 90*47208Scael.El 91*47208Scael.Sh SEE ALSO 92*47208Scael.Xr accept 2 , 93*47208Scael.Xr open 2 , 94*47208Scael.Xr close 2 , 95*47208Scael.Xr fcntl 2 , 96*47208Scael.Xr pipe 2 , 97*47208Scael.Xr socket 2 , 98*47208Scael.Xr socketpair 2 , 99*47208Scael.Xr getdtablesize 2 100*47208Scael.Sh STANDARDS 101*47208Scael.Fn Dup 102*47208Scaeland 103*47208Scael.Fn dup2 104*47208Scaelare expected to conform 105*47208Scaelto IEEE Std 1003.1-1988 106*47208Scael.Pq Dq Tn POSIX . 107