git.saurik.com Git - apple/xnu.git/blob

1 .\" $NetBSD: dup.2,v 1.4 1995/02/27 12:32:21 cgd Exp $

2 .\"

5 .\"

6 .\" Redistribution and use in source and binary forms, with or without

7 .\" modification, are permitted provided that the following conditions

8 .\" are met:

9 .\" 1. Redistributions of source code must retain the above copyright

10 .\" notice, this list of conditions and the following disclaimer.

11 .\" 2. Redistributions in binary form must reproduce the above copyright

12 .\" notice, this list of conditions and the following disclaimer in the

13 .\" documentation and/or other materials provided with the distribution.

14 .\" 3. All advertising materials mentioning features or use of this software

15 .\" must display the following acknowledgement:

16 .\" This product includes software developed by the University of

17 .\" California, Berkeley and its contributors.

18 .\" 4. Neither the name of the University nor the names of its contributors

19 .\" may be used to endorse or promote products derived from this software

20 .\" without specific prior written permission.

21 .\"

22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

32 .\" SUCH DAMAGE.

33 .\"

34 .\" @(#)dup.2 8.1 (Berkeley) 6/4/93

35 .\"

36 .Dd December 1, 2010

37 .Dt DUP 2

38 .Os BSD 4

39 .Sh NAME

40 .Nm dup ,

41 .Nm dup2

42 .Nd duplicate an existing file descriptor

43 .Sh SYNOPSIS

44 .Fd #include <unistd.h>

45 .Ft int

46 .Fo dup

47 .Fa "int fildes"

48 .Fc

49 .Ft int

50 .Fo dup2

51 .Fa "int fildes"

52 .Fa "int fildes2"

53 .Fc

54 .Sh DESCRIPTION

55 .Fn dup

56 duplicates an existing object descriptor

57 and returns its value to the calling process

58 .Fa ( fildes2

59 =

60 .Fn dup fildes ) .

61 The argument

62 .Fa fildes

63 is a small non-negative integer index

64 in the per-process descriptor table.

65 The value must be less than the size of the table,

66 which is returned by

67 .Xr getdtablesize 2 .

68 The new descriptor returned by the call

69 is the lowest numbered descriptor

70 currently not in use by the process.

71 .Pp

72 The object referenced by the descriptor does not distinguish

73 between

74 .Fa fildes

75 and

76 .Fa fildes2

77 in any way.

78 Thus if

79 .Fa fildes2

80 and

81 .Fa fildes

82 are duplicate references to an open

83 file,

84 .Xr read 2 ,

85 .Xr write 2

86 and

87 .Xr lseek 2

88 calls all move a single pointer into the file,

89 and append mode, non-blocking I/O and asynchronous I/O options

90 are shared between the references.

91 If a separate pointer into the file is desired,

92 a different object reference to the file must be obtained

93 by issuing an additional

94 .Xr open 2

95 call.

96 The close-on-exec flag on the new file descriptor is unset.

97 .Pp

98 In

99 .Fn dup2 ,

100 the value of the new descriptor

101 .Fa fildes2

102 is specified.

103 If

104 .Fa fildes

105 and

106 .Fa fildes2

107 are equal, then

108 .Fn dup2

109 just returns

110 .Fa fildes2 ;

111 no other changes are made to the existing descriptor.

112 Otherwise, if descriptor

113 .Fa fildes2

114 is already in use, it is first deallocated as if a

115 .Xr close 2

116 call had been done first.

117 .Sh RETURN VALUES

118 Upon successful completion, the new file descriptor is returned.

119 Otherwise, a value of -1 is returned and the global integer variable

120 .Va errno

121 is set to indicate the error.

122 .Sh ERRORS

123 The

124 .Fn dup

125 and

126 .Fn dup2

127 system calls will fail if:

128 .Bl -tag -width Er

129 .\" ==========

130 .It Bq Er EBADF

131 .Fa fildes

132 is not an active, valid file descriptor.

133 .\" ==========

134 .It Bq Er EINTR

135 Execution is interrupted by a signal.

136 .\" ==========

137 .It Bq Er EMFILE

138 Too many file descriptors are active.

139 .El

140 .Pp

141 The

142 .Fn dup2

143 system call will fail if:

144 .Bl -tag -width Er

145 .\" ==========

146 .It Bq Er EBADF

147 .Fa fildes2

148 is negative or greater than the maximum allowable number (see getdtablesize(2)).

149 .El

150 .Sh SEE ALSO

151 .Xr accept 2 ,

152 .Xr close 2 ,

153 .Xr fcntl 2 ,

154 .Xr getdtablesize 2 ,

155 .Xr open 2 ,

156 .Xr pipe 2 ,

157 .Xr socket 2 ,

158 .Xr socketpair 2

159 .Sh STANDARDS

160 .Fn dup

161 and

162 .Fn dup2

163 are expected to conform to

164 .St -p1003.1-88 .