libc/sys/dup.2

.\"	$NetBSD: dup.2,v 1.30 2013/12/25 02:49:52 wiz Exp $
.\"
.\" 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
.\"
.Dd December 24, 2013
.Dt DUP 2
.Os
.Sh NAME
.Nm dup ,
.Nm dup2 ,
.Nm dup3
.Nd duplicate an existing file descriptor
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fn dup "int oldfd"
.Ft int
.Fn dup2 "int oldfd" "int newfd"
.Ft int
.Fn dup3 "int oldfd" "int newfd" "int flags"
.Sh DESCRIPTION
The
.Fn dup
family of calls duplicates an existing file descriptor
.Fa oldfd .
A new file descriptor is produced; it is a new reference to the same
underlying system object.
The object in question does not distinguish between the descriptors
referencing it in any way.
Thus for files,
.Xr read 2 ,
.Xr write 2
and
.Xr lseek 2
calls all move a single shared seek position.
Similarly, all object modes, settings, properties, and behavior other
than the close-on-exec flag are shared between references.
This includes the setting of append mode, non-blocking I/O actions,
asynchronous I/O operations in progress, socket options, and so forth.
The close-on-exec flag, however, is a property of the descriptor
rather than the object and can be set independently for each
reference.
.Pp
To get an independent handle with its own seek position and settings,
an additional
.Xr open 2
call must be issued.
(This is not generally possible for pipes and sockets.)
.Pp
The
.Nm dup
call chooses the new descriptor: it is the lowest-numbered descriptor
not currently in use.
The
.Nm dup2
and
.Nm dup3
calls allow the caller to choose the new descriptor by passing
.Fa newfd ,
which must be within the range of valid descriptors.
If
.Fa newfd
is the same as
.Fa oldfd ,
the call has no effect.
Otherwise, if
.Fa newfd
is already in use, it is closed as if
.Xr close 2
had been called.
.Pp
File descriptors are small non-negative integers that index into the
per-process file table.
Values 0, 1, and 2 have the special property that they are treated as
standard input, standard output, and standard error respectively.
(The constants
.Dv STDIN_FILENO ,
.Dv STDOUT_FILENO ,
and
.Dv STDERR_FILENO
are provided as symbolic forms for these values.)
The maximum value for a file descriptor is one less than the file
table size.
The file table size can be interrogated with
.Xr getdtablesize 3
and can to some extent be adjusted with
.Xr setrlimit 2 .
.Pp
The
.Fn dup3
call includs an additional
.Fa flags
argument supporting a subset of the
.Xr open 2
flags:
.Bl -tag -width O_NOSIGPIPE -offset indent
.It Dv O_CLOEXEC
Set the close-on-exec flag on
.Fa newfd .
.It Dv O_NONBLOCK
Sets non-blocking I/O.
.It Dv O_NOSIGPIPE
For pipes and sockets, do not raise
.Dv SIGPIPE
when a write is made to a broken pipe.
Instead, the write will fail with
.Er EPIPE .
.El
As described above, only the close-on-exec flag is
per-file-descriptor, so passing any of the other
.Fa flags
will affect
both
.Fa oldfd
and
.Fa newfd .
These settings are, however, applied atomically along with the rest of
the
.Fn dup3
operation.
.Pp
In the case of
.Fn dup
and
.Fn dup2
the close-on-exec flag on the new file descriptor is always left
unset and all the modes and settings of the underlying object are left
unchanged.
.Pp
Functionality similar to
.Fn dup
with slightly different semantics is also available via
.Xr fcntl 2 .
.Sh RETURN VALUES
These calls return the new file descriptor value.
In the case of
.Fn dup2
and
.Fn dup3
this is always the same as
.Fa newfd .
If an error occurs, the value \-1 is returned and
.Va errno
is set to indicate what happened.
.Sh EXAMPLES
A common use for these functions is to set up a pipe as the standard
input or standard output of a subprocess.
That is done approximately as follows (error handling omitted for
clarity):
.Bd -literal -offset indent
#include \*[Lt]unistd.h\*[Gt]

int fds[2];
pid_t pid;

pipe(fds);
pid = fork();
if (pid == 0) {
	/* child; use read end of pipe to stdin */
	dup2(fds[0], STDIN_FILENO);
	close(fds[0]);
	close(fds[1]);
	execv("/some/program", args);
}
/* parent process; return write end of pipe */
close(fds[0]);
return fds[1];
.Ed
.Sh ERRORS
These functions fail if:
.Bl -tag -width Er
.It Bq Er EBADF
.Fa oldfd
is not a valid active descriptor, or for
.Fn dup2
and
.Fn dup3 ,
.Fa newfd
is not in the range of valid file descriptors.
.It Bq Er EINVAL
.Fa flags
contained an invalid value.
Only
.Fn dup3
can generate this error.
.It Bq Er EMFILE
Too many descriptors are active.
Only
.Fn dup
can generate this error.
.El
.Sh SEE ALSO
.Xr accept 2 ,
.Xr close 2 ,
.Xr fcntl 2 ,
.Xr getrlimit 2 ,
.Xr open 2 ,
.Xr pipe 2 ,
.Xr setrlimit 2 ,
.Xr socket 2 ,
.Xr socketpair 2 ,
.Xr getdtablesize 3
.Sh STANDARDS
The
.Fn dup
and
.Fn dup2
functions conform to
.St -p1003.1-90 .
.Sh HISTORY
The
.Fn dup3
function originated in Linux and appeared in
.Nx 6.0 .