1DUP(3P)                    POSIX Programmer's Manual                   DUP(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       dup, dup2 — duplicate an open file descriptor
14

SYNOPSIS

16       #include <unistd.h>
17
18       int dup(int fildes);
19       int dup2(int fildes, int fildes2);
20

DESCRIPTION

22       The dup() function provides an alternative  interface  to  the  service
23       provided  by  fcntl()  using  the F_DUPFD command. The call dup(fildes)
24       shall be equivalent to:
25
26           fcntl(fildes, F_DUPFD, 0);
27
28       The dup2() function shall cause the file descriptor fildes2 to refer to
29       the  same  open  file  description as the file descriptor fildes and to
30       share any locks, and shall return fildes2.  If  fildes2  is  already  a
31       valid  open file descriptor, it shall be closed first, unless fildes is
32       equal to fildes2 in which case  dup2()  shall  return  fildes2  without
33       closing it. If the close operation fails to close fildes2, dup2() shall
34       return −1 without changing the open file description to  which  fildes2
35       refers.  If  fildes is not a valid file descriptor, dup2() shall return
36       −1 and shall not close fildes2.  If fildes2 is less than 0  or  greater
37       than  or  equal to {OPEN_MAX}, dup2() shall return −1 with errno set to
38       [EBADF].
39
40       Upon successful completion, if fildes is  not  equal  to  fildes2,  the
41       FD_CLOEXEC  flag associated with fildes2 shall be cleared. If fildes is
42       equal to fildes2, the FD_CLOEXEC flag associated with fildes2 shall not
43       be changed.
44
45       If  fildes  refers  to  a typed memory object, the result of the dup2()
46       function is unspecified.
47

RETURN VALUE

49       Upon successful completion a  non-negative  integer,  namely  the  file
50       descriptor,  shall  be  returned;  otherwise,  −1 shall be returned and
51       errno set to indicate the error.
52

ERRORS

54       The dup() function shall fail if:
55
56       EBADF  The fildes argument is not a valid open file descriptor.
57
58       EMFILE All file descriptors available  to  the  process  are  currently
59              open.
60
61       The dup2() function shall fail if:
62
63       EBADF  The  fildes  argument is not a valid open file descriptor or the
64              argument fildes2  is  negative  or  greater  than  or  equal  to
65              {OPEN_MAX}.
66
67       EINTR  The dup2() function was interrupted by a signal.
68
69       The dup2() function may fail if:
70
71       EIO    An I/O error occurred while attempting to close fildes2.
72
73       The following sections are informative.
74

EXAMPLES

76   Redirecting Standard Output to a File S
77       The following example closes standard output for the current processes,
78       re-assigns standard output to go to the file  referenced  by  pfd,  and
79       closes the original file descriptor to clean up.
80
81           #include <unistd.h>
82           ...
83           int pfd;
84           ...
85           close(1);
86           dup(pfd);
87           close(pfd);
88           ...
89
90   Redirecting Error Messages
91       The following example redirects messages from stderr to stdout.
92
93           #include <unistd.h>
94           ...
95           dup2(1, 2);
96           ...
97

APPLICATION USAGE

99       Implementations  may  use  file descriptors that must be inherited into
100       child processes for the child process to remain conforming, such as for
101       message  catalog  or  tracing  purposes. Therefore, an application that
102       calls dup2() with an arbitrary integer for fildes2 risks non-conforming
103       behavior,  and  dup2()  can  only  portably  be  used to overwrite file
104       descriptor values that the application has  obtained  through  explicit
105       actions,  or  for the three file descriptors corresponding to the stan‐
106       dard file streams. In order to avoid a race  condition  of  leaking  an
107       unintended  file descriptor into a child process, an application should
108       consider opening all file  descriptors  with  the  FD_CLOEXEC  bit  set
109       unless the file descriptor is intended to be inherited across exec.
110

RATIONALE

112       The  dup() function is redundant. Its services are also provided by the
113       fcntl() function. It has been included in this volume  of  POSIX.1‐2008
114       primarily  for historical reasons, since many existing applications use
115       it. On the other hand, the dup2() function provides unique services, as
116       no  other  interface  is  able  to  atomically replace an existing file
117       descriptor.
118
119       The dup2() function is not marked obsolescent  because  it  presents  a
120       type-safe version of functionality provided in a type-unsafe version by
121       fcntl().  It is used in the POSIX Ada binding.
122
123       The dup2() function is not intended for use in critical  regions  as  a
124       synchronization mechanism.
125
126       In the description of [EBADF], the case of fildes being out of range is
127       covered by the given case of fildes not being valid.  The  descriptions
128       for  fildes and fildes2 are different because the only kind of invalid‐
129       ity that is relevant for fildes2 is whether it is out  of  range;  that
130       is,  it does not matter whether fildes2 refers to an open file when the
131       dup2() call is made.
132

FUTURE DIRECTIONS

134       None.
135

SEE ALSO

137       close(), fcntl(), open()
138
139       The Base Definitions volume of POSIX.1‐2008, <unistd.h>
140
142       Portions of this text are reprinted and reproduced in  electronic  form
143       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
144       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
145       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
146       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
147       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
148       event of any discrepancy between this version and the original IEEE and
149       The  Open Group Standard, the original IEEE and The Open Group Standard
150       is the referee document. The original Standard can be  obtained  online
151       at http://www.unix.org/online.html .
152
153       Any  typographical  or  formatting  errors that appear in this page are
154       most likely to have been introduced during the conversion of the source
155       files  to  man page format. To report such errors, see https://www.ker
156       nel.org/doc/man-pages/reporting_bugs.html .
157
158
159
160IEEE/The Open Group                  2013                              DUP(3P)
Impressum