dup.3p (6278B)
- '\" et
- .TH DUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- dup,
- dup2
- \(em duplicate an open file descriptor
- .SH SYNOPSIS
- .LP
- .nf
- #include <unistd.h>
- .P
- int dup(int \fIfildes\fP);
- int dup2(int \fIfildes\fP, int \fIfildes2\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIdup\fR()
- function provides an alternative interface to the service provided by
- \fIfcntl\fR()
- using the F_DUPFD command. The call
- .IR dup ( fildes )
- shall be equivalent to:
- .sp
- .RS 4
- .nf
- fcntl(fildes, F_DUPFD, 0);
- .fi
- .P
- .RE
- .P
- The
- \fIdup2\fR()
- function shall cause the file descriptor
- .IR fildes2
- to refer to the same open file description as the file descriptor
- .IR fildes
- and to share any locks, and shall return
- .IR fildes2 .
- If
- .IR fildes2
- is already a valid open file descriptor, it shall be closed first, unless
- .IR fildes
- is equal to
- .IR fildes2
- in which case
- \fIdup2\fR()
- shall return
- .IR fildes2
- without closing it. If the close operation fails to close
- .IR fildes2 ,
- \fIdup2\fR()
- shall return \-1 without changing the open file description to which
- .IR fildes2
- refers. If
- .IR fildes
- is not a valid file descriptor,
- \fIdup2\fR()
- shall return \-1 and shall not close
- .IR fildes2 .
- If
- .IR fildes2
- is less than 0 or greater than or equal to
- {OPEN_MAX},
- \fIdup2\fR()
- shall return \-1 with
- .IR errno
- set to
- .BR [EBADF] .
- .P
- Upon successful completion, if
- .IR fildes
- is not equal to
- .IR fildes2 ,
- the FD_CLOEXEC flag associated with
- .IR fildes2
- shall be cleared. If
- .IR fildes
- is equal to
- .IR fildes2 ,
- the FD_CLOEXEC flag associated with
- .IR fildes2
- shall not be changed.
- .P
- If
- .IR fildes
- refers to a typed memory object, the result of the
- \fIdup2\fR()
- function is unspecified.
- .SH "RETURN VALUE"
- Upon successful completion a non-negative integer, namely the file
- descriptor, shall be returned; otherwise, \-1 shall be returned
- and
- .IR errno
- set to indicate the error.
- .SH ERRORS
- The
- \fIdup\fR()
- function shall fail if:
- .TP
- .BR EBADF
- The
- .IR fildes
- argument is not a valid open file descriptor.
- .TP
- .BR EMFILE
- All file descriptors available to the process are currently open.
- .P
- The
- \fIdup2\fR()
- function shall fail if:
- .TP
- .BR EBADF
- The
- .IR fildes
- argument is not a valid open file descriptor or the argument
- .IR fildes2
- is negative or greater than or equal to
- {OPEN_MAX}.
- .TP
- .BR EINTR
- The
- \fIdup2\fR()
- function was interrupted by a signal.
- .P
- The
- \fIdup2\fR()
- function may fail if:
- .TP
- .BR EIO
- An I/O error occurred while attempting to close
- .IR fildes2 .
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Redirecting Standard Output to a File" S
- .P
- The following example closes standard output for the current processes,
- re-assigns standard output to go to the file referenced by
- .IR pfd ,
- and closes the original file descriptor to clean up.
- .sp
- .RS 4
- .nf
- #include <unistd.h>
- \&...
- int pfd;
- \&...
- close(1);
- dup(pfd);
- close(pfd);
- \&...
- .fi
- .P
- .RE
- .SS "Redirecting Error Messages"
- .P
- The following example redirects messages from
- .IR stderr
- to
- .IR stdout .
- .sp
- .RS 4
- .nf
- #include <unistd.h>
- \&...
- dup2(1, 2);
- \&...
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- Implementations may use file descriptors that must be inherited into
- child processes for the child process to remain conforming, such as for
- message catalog or tracing purposes. Therefore, an application that calls
- \fIdup2\fR()
- with an arbitrary integer for
- .IR fildes2
- risks non-conforming behavior, and
- \fIdup2\fR()
- can only portably be used to overwrite file descriptor values that the
- application has obtained through explicit actions, or for the three file
- descriptors corresponding to the standard file streams. In order to avoid
- a race condition of leaking an unintended file descriptor into a child
- process, an application should consider opening all file descriptors
- with the FD_CLOEXEC bit set unless the file descriptor is intended to
- be inherited across
- .IR exec .
- .SH RATIONALE
- The
- \fIdup\fR()
- function is redundant. Its services are also provided by the
- \fIfcntl\fR()
- function. It has been included in this volume of POSIX.1\(hy2017 primarily for historical reasons,
- since many existing applications use it. On the other hand, the
- \fIdup2\fR()
- function provides unique services, as no other interface is able to
- atomically replace an existing file descriptor.
- .P
- The
- \fIdup2\fR()
- function is not marked obsolescent because it presents a type-safe
- version of functionality provided in a type-unsafe version by
- \fIfcntl\fR().
- It is used in the POSIX Ada binding.
- .P
- The
- \fIdup2\fR()
- function is not intended for use in critical regions as a
- synchronization mechanism.
- .P
- In the description of
- .BR [EBADF] ,
- the case of
- .IR fildes
- being out of range is covered by the given case of
- .IR fildes
- not being valid. The descriptions for
- .IR fildes
- and
- .IR fildes2
- are different because the only kind of invalidity that is relevant for
- .IR fildes2
- is whether it is out of range; that is, it does not matter whether
- .IR fildes2
- refers to an open file when the
- \fIdup2\fR()
- call is made.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIclose\fR\^(\|)",
- .IR "\fIfcntl\fR\^(\|)",
- .IR "\fIopen\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<unistd.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .