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

NAME

6       dup, dup2 - duplicate an open file descriptor
7

SYNOPSIS

9       #include <unistd.h>
10
11       int dup(int fildes);
12       int dup2(int fildes, int fildes2);
13
14

DESCRIPTION

16       The  dup() and dup2() functions provide an alternative interface to the
17       service provided by fcntl() using the F_DUPFD command. The call:
18
19
20              fid = dup(fildes);
21
22       shall be equivalent to:
23
24
25              fid = fcntl(fildes, F_DUPFD, 0);
26
27       The call:
28
29
30              fid = dup2(fildes, fildes2);
31
32       shall be equivalent to:
33
34
35              close(fildes2);
36              fid = fcntl(fildes, F_DUPFD, fildes2);
37
38       except for the following:
39
40        * If fildes2 is less than 0 or greater than or  equal  to  {OPEN_MAX},
41          dup2() shall return -1 with errno set to [EBADF].
42
43        * If fildes is a valid file descriptor and is equal to fildes2, dup2()
44          shall return fildes2 without closing it.
45
46        * If fildes is not a valid file descriptor, dup2() shall return -1 and
47          shall not close fildes2.
48
49        * The  value returned shall be equal to the value of fildes2 upon suc‐
50          cessful completion, or -1 upon failure.
51

RETURN VALUE

53       Upon successful completion a  non-negative  integer,  namely  the  file
54       descriptor,  shall  be  returned;  otherwise,  -1 shall be returned and
55       errno set to indicate the error.
56

ERRORS

58       The dup() function shall fail if:
59
60       EBADF  The fildes argument is not a valid open file descriptor.
61
62       EMFILE The number of file descriptors in  use  by  this  process  would
63              exceed {OPEN_MAX}.
64
65
66       The dup2() function shall fail if:
67
68       EBADF  The  fildes  argument is not a valid open file descriptor or the
69              argument fildes2  is  negative  or  greater  than  or  equal  to
70              {OPEN_MAX}.
71
72       EINTR  The dup2() function was interrupted by a signal.
73
74
75       The following sections are informative.
76

EXAMPLES

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

APPLICATION USAGE

103       None.
104

RATIONALE

106       The  dup()  and dup2() functions are redundant. Their services are also
107       provided by the fcntl() function. They have been included in this  vol‐
108       ume  of  IEEE Std 1003.1-2001  primarily  for historical reasons, since
109       many existing applications use them.
110
111       While the brief code segment shown  is  very  similar  in  behavior  to
112       dup2(), a conforming implementation based on other functions defined in
113       this volume of  IEEE Std 1003.1-2001  is  significantly  more  complex.
114       Least obvious is the possible effect of a signal-catching function that
115       could be invoked between steps and allocate or deallocate file descrip‐
116       tors. This could be avoided by blocking signals.
117
118       The  dup2()  function  is  not marked obsolescent because it presents a
119       type-safe version of functionality provided in a type-unsafe version by
120       fcntl(). It is used in the POSIX Ada binding.
121
122       The  dup2()  function  is not intended for use in critical regions as a
123       synchronization mechanism.
124
125       In the description of [EBADF], the case of fildes being out of range is
126       covered  by  the given case of fildes not being valid. The descriptions
127       for fildes and fildes2 are different because the only kind of  invalid‐
128       ity  that  is  relevant for fildes2 is whether it is out of range; that
129       is, it does not matter whether fildes2 refers to an open file when  the
130       dup2() call is made.
131

FUTURE DIRECTIONS

133       None.
134

SEE ALSO

136       close()   ,   fcntl()  ,  open()  ,  the  Base  Definitions  volume  of
137       IEEE Std 1003.1-2001, <unistd.h>
138

COPYRIGHT

140       Portions of this text are reprinted and reproduced in  electronic  form
141       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
142       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
143       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
144       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
145       event of any discrepancy between this version and the original IEEE and
146       The Open Group Standard, the original IEEE and The Open Group  Standard
147       is  the  referee document. The original Standard can be obtained online
148       at http://www.opengroup.org/unix/online.html .
149
150
151
152IEEE/The Open Group                  2003                               DUP(P)