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