'\"macro stdmacro
.if n .pH g2.dup @(#)dup	40.11 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} dup 2 "" "\&"
.if \nX=1 .ds x} dup 2 ""
.if \nX=2 .ds x} dup 2 "" "\&"
.if \nX=3 .ds x} dup "" "" "\&"
.TH \*(x}
.SH NAME
\f4dup\f1 \- duplicate an open file descriptor
.SH SYNOPSIS
\f4#include <unistd.h>\f1
.PP
\f4int dup(int fildes);\f1
.SH DESCRIPTION
.I fildes\^
is a
file descriptor
obtained from a
\f4creat\fP,
\f4open\fP,
\f4dup\fP,
\f4fcntl\fP,
or
\f4pipe\fP
system call.
\f4dup\fP
returns a new
file descriptor
having the following in common with the original:
.IP
Same open file (or pipe).
.IP
Same file pointer
(i.e., both file descriptors share one file pointer).
.IP
Same access mode (read, write or read/write).
.PP
The new
file descriptor
is set to remain open across
\f4exec\fP
system calls
[see
\f4fcntl\fP(2)].
.PP
The
file descriptor
returned is the lowest one available.
.PP
\f4dup\fP 
will fail if one or more of the following are true:
.TP 15
\f4EBADF\fP
.I fildes\^
is not a valid open
file descriptor.
.TP 15
\f4EINTR\fP
A signal was caught during the \f4dup\fP system call.
.TP 15
\f4EMFILE\fP
The process has too many open files [see
\f4getrlimit\fP(2)].
.TP 15
\f4ENOLINK\fP
\f2fildes\f1 is on a remote machine and the link
to that machine is no longer active.
.SH "SEE ALSO"
\f4close\fP(2),
\f4creat\fP(2),
\f4exec\fP(2),
\f4fcntl\fP(2),
\f4getrlimit\fP(2),
\f4open\fP(2),
\f4pipe\fP(2),
\f4dup2\fP(3C),
\f4lockf\fP(3C).
.SH "DIAGNOSTICS"
Upon successful completion a non-negative integer,
namely the
file descriptor,
is returned.
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.\"	@(#)dup.2	6.2 of 9/6/83
.Ee
