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

NAME

12       dup, dup2 - duplicate an open file descriptor
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

59       Upon  successful  completion  a  non-negative  integer, namely the file
60       descriptor, shall be returned; otherwise,  -1  shall  be  returned  and
61       errno set to indicate the error.
62

ERRORS

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

EXAMPLES

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

APPLICATION USAGE

109       None.
110

RATIONALE

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

FUTURE DIRECTIONS

139       None.
140

SEE ALSO

142       close(),   fcntl(),   open(),   the   Base   Definitions   volume    of
143       IEEE Std 1003.1-2001, <unistd.h>
144

COPYRIGHT

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