xref: /csrg-svn/lib/libc/sys/dup.2 (revision 61181)
1*61181Sbostic.\" Copyright (c) 1980, 1991, 1993
2*61181Sbostic.\"	The Regents of the University of California.  All rights reserved.
320068Smckusick.\"
447208Scael.\" %sccs.include.redist.man%
520068Smckusick.\"
6*61181Sbostic.\"     @(#)dup.2	8.1 (Berkeley) 06/04/93
747208Scael.\"
847208Scael.Dd
947208Scael.Dt DUP 2
1047208Scael.Os BSD 4
1147208Scael.Sh NAME
1247208Scael.Nm dup ,
1347208Scael.Nm dup2
1447208Scael.Nd duplicate an existing file descriptor
1547208Scael.Sh SYNOPSIS
1647208Scael.Fd #include <unistd.h>
1747208Scael.Ft int
1847208Scael.Fn dup "int oldd"
1947208Scael.Ft int
2047208Scael.Fn dup2 "int oldd" "int newd"
2147208Scael.Sh DESCRIPTION
2247208Scael.Fn Dup
2347208Scaelduplicates an existing object descriptor and returns its value to
2447208Scaelthe calling process
2547208Scael.Fa ( newd
2647208Scael=
2747208Scael.Fn dup oldd ) .
2847208ScaelThe argument
2947208Scael.Fa oldd
3047208Scaelis 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
3347208Scael.Xr getdtablesize 2 .
3447208ScaelThe new descriptor returned by the call
3547208Scaelis the lowest numbered descriptor
3647208Scaelcurrently not in use by the process.
3747208Scael.Pp
3820069SmckusickThe object referenced by the descriptor does not distinguish
3947208Scaelbetween
4047208Scael.Fa oldd
4147208Scaeland
4247208Scael.Fa newd
4347208Scaelin any way.
4447208ScaelThus if
4547208Scael.Fa newd
4647208Scaeland
4747208Scael.Fa oldd
4847208Scaelare duplicate references to an open
4920069Smckusickfile,
5047208Scael.Xr read 2 ,
5147208Scael.Xr write 2
5220069Smckusickand
5347208Scael.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
6047208Scael.Xr open 2
6120069Smckusickcall.
6228067SkarelsThe close-on-exec flag on the new file descriptor is unset.
6347208Scael.Pp
6447208ScaelIn
6547208Scael.Fn dup2 ,
6647208Scaelthe value of the new descriptor
6747208Scael.Fa newd
6847208Scaelis specified.  If this descriptor is already
6920069Smckusickin use, the descriptor is first deallocated as if a
7047208Scael.Xr close 2
7120069Smckusickcall had been done first.
7247208Scael.Sh RETURN VALUES
7347208ScaelThe value -1 is returned if an error occurs in either call.
7420069SmckusickThe external variable
7547208Scael.Va errno
7620069Smckusickindicates the cause of the error.
7747208Scael.Sh ERRORS
7847208Scael.Fn Dup
7920069Smckusickand
8047208Scael.Fn dup2
8120069Smckusickfail if:
8247208Scael.Bl -tag -width Er
8347208Scael.It Bq Er EBADF
8447208Scael.Fa Oldd
8547208Scaelor
8647208Scael.Fa newd
8747208Scaelis not a valid active descriptor
8847208Scael.It Bq Er EMFILE
8920069SmckusickToo many descriptors are active.
9047208Scael.El
9147208Scael.Sh SEE ALSO
9247208Scael.Xr accept 2 ,
9347208Scael.Xr open 2 ,
9447208Scael.Xr close 2 ,
9547208Scael.Xr fcntl 2 ,
9647208Scael.Xr pipe 2 ,
9747208Scael.Xr socket 2 ,
9847208Scael.Xr socketpair 2 ,
9947208Scael.Xr getdtablesize 2
10047208Scael.Sh STANDARDS
10147208Scael.Fn Dup
10247208Scaeland
10347208Scael.Fn dup2
10447208Scaelare expected to conform
10547208Scaelto IEEE Std 1003.1-1988
10647208Scael.Pq Dq Tn POSIX .
107