xref: /freebsd/lib/libsys/dup.2 (revision 1edb7116)
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.Dd December 1, 2017
29.Dt DUP 2
30.Os
31.Sh NAME
32.Nm dup ,
33.Nm dup2
34.Nd duplicate an existing file descriptor
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In unistd.h
39.Ft int
40.Fn dup "int oldd"
41.Ft int
42.Fn dup2 "int oldd" "int newd"
43.Sh DESCRIPTION
44The
45.Fn dup
46system call
47duplicates an existing object descriptor and returns its value to
48the calling process
49.Fa ( newd
50=
51.Fn dup oldd ) .
52The argument
53.Fa oldd
54is a small non-negative integer index in
55the per-process descriptor table.
56The new descriptor returned by the call
57is the lowest numbered descriptor
58currently not in use by the process.
59.Pp
60The object referenced by the descriptor does not distinguish
61between
62.Fa oldd
63and
64.Fa newd
65in any way.
66Thus if
67.Fa newd
68and
69.Fa oldd
70are duplicate references to an open
71file,
72.Xr read 2 ,
73.Xr write 2
74and
75.Xr lseek 2
76calls all move a single pointer into the file,
77and append mode, non-blocking I/O and asynchronous I/O options
78are shared between the references.
79If a separate pointer into the file is desired, a different
80object reference to the file must be obtained by issuing an
81additional
82.Xr open 2
83system call.
84The close-on-exec flag on the new file descriptor is unset.
85.Pp
86In
87.Fn dup2 ,
88the value of the new descriptor
89.Fa newd
90is specified.
91If this descriptor is already in use and
92.Fa oldd
93\*(Ne
94.Fa newd ,
95the descriptor is first deallocated as if the
96.Xr close 2
97system call had been used.
98If
99.Fa oldd
100is not a valid descriptor, then
101.Fa newd
102is not closed.
103If
104.Fa oldd
105==
106.Fa newd
107and
108.Fa oldd
109is a valid descriptor, then
110.Fn dup2
111is successful, and does nothing.
112.Sh RETURN VALUES
113These calls return the new file descriptor if successful;
114otherwise the value -1 is returned and
115the external variable
116.Va errno
117is set to indicate the cause of the error.
118.Sh ERRORS
119The
120.Fn dup
121system call fails if:
122.Bl -tag -width Er
123.It Bq Er EBADF
124The
125.Fa oldd
126argument
127is not a valid active descriptor
128.It Bq Er EMFILE
129Too many descriptors are active.
130.El
131.Pp
132The
133.Fn dup2
134system call fails if:
135.Bl -tag -width Er
136.It Bq Er EBADF
137The
138.Fa oldd
139argument is not a valid active descriptor or the
140.Fa newd
141argument is negative or exceeds the maximum allowable descriptor number
142.El
143.Sh SEE ALSO
144.Xr accept 2 ,
145.Xr close 2 ,
146.Xr fcntl 2 ,
147.Xr getdtablesize 2 ,
148.Xr open 2 ,
149.Xr pipe 2 ,
150.Xr socket 2 ,
151.Xr socketpair 2 ,
152.Xr dup3 3
153.Sh STANDARDS
154The
155.Fn dup
156and
157.Fn dup2
158system calls are expected to conform to
159.St -p1003.1-90 .
160.Sh HISTORY
161The
162.Fn dup
163function appeared in
164.At v3 .
165The
166.Fn dup2
167function appeared in
168.At v7 .
169