freebsd-dev/lib/libc/sys/dup.2

.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)dup.2	8.1 (Berkeley) 6/4/93
.\" $FreeBSD$
.\"
.Dd December 1, 2017
.Dt DUP 2
.Os
.Sh NAME
.Nm dup ,
.Nm dup2
.Nd duplicate an existing file descriptor
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn dup "int oldd"
.Ft int
.Fn dup2 "int oldd" "int newd"
.Sh DESCRIPTION
The
.Fn dup
system call
duplicates an existing object descriptor and returns its value to
the calling process
.Fa ( newd
=
.Fn dup oldd ) .
The argument
.Fa oldd
is a small non-negative integer index in
the per-process descriptor table.
The new descriptor returned by the call
is the lowest numbered descriptor
currently not in use by the process.
.Pp
The object referenced by the descriptor does not distinguish
between
.Fa oldd
and
.Fa newd
in any way.
Thus if
.Fa newd
and
.Fa oldd
are duplicate references to an open
file,
.Xr read 2 ,
.Xr write 2
and
.Xr lseek 2
calls all move a single pointer into the file,
and append mode, non-blocking I/O and asynchronous I/O options
are shared between the references.
If a separate pointer into the file is desired, a different
object reference to the file must be obtained by issuing an
additional
.Xr open 2
system call.
The close-on-exec flag on the new file descriptor is unset.
.Pp
In
.Fn dup2 ,
the value of the new descriptor
.Fa newd
is specified.
If this descriptor is already in use and
.Fa oldd
\*(Ne
.Fa newd ,
the descriptor is first deallocated as if the
.Xr close 2
system call had been used.
If
.Fa oldd
is not a valid descriptor, then
.Fa newd
is not closed.
If
.Fa oldd
==
.Fa newd
and
.Fa oldd
is a valid descriptor, then
.Fn dup2
is successful, and does nothing.
.Sh RETURN VALUES
These calls return the new file descriptor if successful;
otherwise the value -1 is returned and
the external variable
.Va errno
is set to indicate the cause of the error.
.Sh ERRORS
The
.Fn dup
system call fails if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa oldd
argument
is not a valid active descriptor
.It Bq Er EMFILE
Too many descriptors are active.
.El
.Pp
The
.Fn dup2
system call fails if:
.Bl -tag -width Er
.It Bq Er EBADF
The
.Fa oldd
argument is not a valid active descriptor or the
.Fa newd
argument is negative or exceeds the maximum allowable descriptor number
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr close 2 ,
.Xr fcntl 2 ,
.Xr getdtablesize 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr socket 2 ,
.Xr socketpair 2 ,
.Xr dup3 3
.Sh STANDARDS
The
.Fn dup
and
.Fn dup2
system calls are expected to conform to
.St -p1003.1-90 .
.Sh HISTORY
The
.Fn dup
function appeared in
.At v3 .
The
.Fn dup2
function appeared in
.At v7 .
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\" Copyright (c) 1980, 1991, 1993`
			`.\" The Regents of the University of California. All rights reserved.`
			`.\"`
			`.\" Redistribution and use in source and binary forms, with or without`
			`.\" modification, are permitted provided that the following conditions`
			`.\" are met:`
			`.\" 1. Redistributions of source code must retain the above copyright`
			`.\" notice, this list of conditions and the following disclaimer.`
			`.\" 2. Redistributions in binary form must reproduce the above copyright`
			`.\" notice, this list of conditions and the following disclaimer in the`
			`.\" documentation and/or other materials provided with the distribution.`
Renumber copyright clause 4 Renumber cluase 4 to 3, per what everybody else did when BSD granted them permission to remove clause 3. My insistance on keeping the same numbering for legal reasons is too pedantic, so give up on that point. Submitted by: Jan Schaumann <jschauma@stevens.edu> Pull Request: https://github.com/freebsd/freebsd/pull/96 2017-02-28 23:42:47 +00:00			`.\" 3. Neither the name of the University nor the names of its contributors`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\" may be used to endorse or promote products derived from this software`
			`.\" without specific prior written permission.`
			`.\"`
			.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
			`.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE`
			`.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE`
			`.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE`
			`.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL`
			`.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS`
			`.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)`
			`.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT`
			`.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY`
			`.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF`
			`.\" SUCH DAMAGE.`
			`.\"`
			`.\" @(#)dup.2 8.1 (Berkeley) 6/4/93`
$Id$ -> $FreeBSD$ 1999-08-28 00:22:10 +00:00			`.\" $FreeBSD$`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.\"`
Correct history for Unix 2nd Edition through 6th Edition for the system calls. Man pages are missing for v2 and v5, so any entries for those versions were inferred by new implementations of these functions in libc. Obtained from: http://www.tuhs.org/cgi-bin/utree.pl 2017-12-01 22:48:20 +00:00			`.Dd December 1, 2017`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Dt DUP 2`
mdoc(7) police: removed HISTORY info from the .Os call. 2001-07-10 13:41:46 +00:00			`.Os`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh NAME`
			`.Nm dup ,`
			`.Nm dup2`
			`.Nd duplicate an existing file descriptor`
Introduce ".Lb" macro to libc manpages. More libraries manpages updates following. 2000-04-21 09:42:15 +00:00			`.Sh LIBRARY`
			`.Lb libc`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh SYNOPSIS`
mdoc(7) police: Use the new .In macro for #include statements. 2001-10-01 16:09:29 +00:00			`.In unistd.h`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Ft int`
			`.Fn dup "int oldd"`
			`.Ft int`
			`.Fn dup2 "int oldd" "int newd"`
			`.Sh DESCRIPTION`
The .Fn function. 2002-07-15 20:59:12 +00:00			`The`
			`.Fn dup`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`duplicates an existing object descriptor and returns its value to`
			`the calling process`
			`.Fa ( newd`
			`=`
			`.Fn dup oldd ) .`
			`The argument`
			`.Fa oldd`
			`is a small non-negative integer index in`
Mechanically kill hard sentence breaks. 2004-07-02 23:52:20 +00:00			`the per-process descriptor table.`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`The new descriptor returned by the call`
			`is the lowest numbered descriptor`
			`currently not in use by the process.`
			`.Pp`
			`The object referenced by the descriptor does not distinguish`
			`between`
			`.Fa oldd`
			`and`
			`.Fa newd`
			`in any way.`
			`Thus if`
			`.Fa newd`
			`and`
			`.Fa oldd`
			`are duplicate references to an open`
			`file,`
			`.Xr read 2 ,`
			`.Xr write 2`
			`and`
			`.Xr lseek 2`
			`calls all move a single pointer into the file,`
			`and append mode, non-blocking I/O and asynchronous I/O options`
			`are shared between the references.`
			`If a separate pointer into the file is desired, a different`
			`object reference to the file must be obtained by issuing an`
			`additional`
			`.Xr open 2`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call.`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`The close-on-exec flag on the new file descriptor is unset.`
			`.Pp`
Remove whitespace at EOL. 2001-07-15 07:53:42 +00:00			`In`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Fn dup2 ,`
			`the value of the new descriptor`
			`.Fa newd`
Mechanically kill hard sentence breaks. 2004-07-02 23:52:20 +00:00			`is specified.`
			`If this descriptor is already in use and`
Clarified the behaviour of dup2(fd1,fd2) when fd1==fd2 and when fd1 is invalid. Safe for 2.2! 1997-03-09 13:16:48 +00:00			`.Fa oldd`
mdoc(7) police: join split punctuation to macro calls. 2001-08-10 17:35:21 +00:00			`\*(Ne`
Clarified the behaviour of dup2(fd1,fd2) when fd1==fd2 and when fd1 is invalid. Safe for 2.2! 1997-03-09 13:16:48 +00:00			`.Fa newd ,`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`the descriptor is first deallocated as if the`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Xr close 2`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system call had been used.`
Clarified the behaviour of dup2(fd1,fd2) when fd1==fd2 and when fd1 is invalid. Safe for 2.2! 1997-03-09 13:16:48 +00:00			`If`
			`.Fa oldd`
			`is not a valid descriptor, then`
			`.Fa newd`
			`is not closed.`
			`If`
			`.Fa oldd`
			`==`
			`.Fa newd`
			`and`
			`.Fa oldd`
			`is a valid descriptor, then`
			`.Fn dup2`
			`is successful, and does nothing.`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh RETURN VALUES`
dup(2): Clarify return value, in particular of dup2(). 2013-05-31 22:09:31 +00:00			`These calls return the new file descriptor if successful;`
			`otherwise the value -1 is returned and`
			`the external variable`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Va errno`
dup(2): Clarify return value, in particular of dup2(). 2013-05-31 22:09:31 +00:00			`is set to indicate the cause of the error.`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh ERRORS`
The .Fn function. 2002-07-15 20:59:12 +00:00			`The`
			`.Fn dup`
Return EBADF instead of EMFILE from dup2 when the second argument is outside the range of valid file descriptors PR: kern/164970 Submitted by: Peter Jeremy <peterjeremy@acm.org> Reviewed by: jilles Approved by: cperciva MFC after: 1 week 2012-04-11 14:08:09 +00:00			`system call fails if:`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Bl -tag -width Er`
			`.It Bq Er EBADF`
mdoc(7) police: "The .Fa argument.". 2002-12-19 09:40:28 +00:00			`The`
			`.Fa oldd`
			`argument`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`is not a valid active descriptor`
			`.It Bq Er EMFILE`
			`Too many descriptors are active.`
			`.El`
Add missing .Pp macro. PR: docs/170380 Submitted by: Garrett Cooper <yanegomi@gmail.com> Approved by: joel (mentor) 2012-08-21 16:35:14 +00:00			`.Pp`
Return EBADF instead of EMFILE from dup2 when the second argument is outside the range of valid file descriptors PR: kern/164970 Submitted by: Peter Jeremy <peterjeremy@acm.org> Reviewed by: jilles Approved by: cperciva MFC after: 1 week 2012-04-11 14:08:09 +00:00			`The`
			`.Fn dup2`
			`system call fails if:`
			`.Bl -tag -width Er`
			`.It Bq Er EBADF`
			`The`
			`.Fa oldd`
			`argument is not a valid active descriptor or the`
			`.Fa newd`
			`argument is negative or exceeds the maximum allowable descriptor number`
			`.El`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh SEE ALSO`
			`.Xr accept 2 ,`
			`.Xr close 2 ,`
			`.Xr fcntl 2 ,`
Sort cross references. 1997-01-20 23:23:22 +00:00			`.Xr getdtablesize 2 ,`
			`.Xr open 2 ,`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Xr pipe 2 ,`
			`.Xr socket 2 ,`
Add man page dup3(3). 2013-08-16 13:16:27 +00:00			`.Xr socketpair 2 ,`
			`.Xr dup3 3`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`.Sh STANDARDS`
upgrade STANDARDS from POSIX 1003.1-88 to 1003.1-90 using .St macro use ``is expected to conform to'' phrase, not ``conforms to'' Pointed out by: Bruce->NIST-PCTS 1996-12-02 20:03:58 +00:00			`The`
			`.Fn dup`
BSD 4.4 Lite Lib Sources 1994-05-27 05:00:24 +00:00			`and`
			`.Fn dup2`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`system calls are expected to conform to`
upgrade STANDARDS from POSIX 1003.1-88 to 1003.1-90 using .St macro use ``is expected to conform to'' phrase, not ``conforms to'' Pointed out by: Bruce->NIST-PCTS 1996-12-02 20:03:58 +00:00			`.St -p1003.1-90 .`
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2 1996-08-29 21:24:19 +00:00			`.Sh HISTORY`
mdoc(7) police: Tidy up the syscall language. Stop calling system calls "function calls". Use "The .Fn system call" a-la "The .Nm utility". When referring to a non-BSD implementation in the HISTORY section, call syscall a function, to be safe. 2002-12-18 09:22:32 +00:00			`The`
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2 1996-08-29 21:24:19 +00:00			`.Fn dup`
Correct history for Unix 2nd Edition through 6th Edition for the system calls. Man pages are missing for v2 and v5, so any entries for those versions were inferred by new implementations of these functions in libc. Obtained from: http://www.tuhs.org/cgi-bin/utree.pl 2017-12-01 22:48:20 +00:00			`function appeared in`
			`.At v3 .`
			`The`
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2 1996-08-29 21:24:19 +00:00			`.Fn dup2`
Correct history for Unix 2nd Edition through 6th Edition for the system calls. Man pages are missing for v2 and v5, so any entries for those versions were inferred by new implementations of these functions in libc. Obtained from: http://www.tuhs.org/cgi-bin/utree.pl 2017-12-01 22:48:20 +00:00			`function appeared in`
function appeared in Version 7 AT&T UNIX Obtained from: ftp://netlib.att.com/netlib/att/cs/v7man/man2 1996-08-29 21:24:19 +00:00			`.At v7 .`