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

3 .\"

4 .\" This code is derived from software contributed to Berkeley by

5 .\" the American National Standards Committee X3, on Information

6 .\" Processing Systems.

7 .\"

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

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

10 .\" are met:

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

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

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

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

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

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

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

18 .\" without specific prior written permission.

19 .\"

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

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

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

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

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

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

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

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

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

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

30 .\" SUCH DAMAGE.

31 .\"

32 .\" @(#)tmpnam.3 8.2 (Berkeley) 11/17/93

33 .\" $FreeBSD: src/lib/libc/stdio/tmpnam.3,v 1.20 2007/03/16 21:46:24 maxim Exp $

34 .\"

35 .Dd November 12, 2008

36 .Dt TMPFILE 3

37 .Os

38 .Sh NAME

39 .Nm tempnam ,

40 .Nm tmpfile ,

41 .Nm tmpnam

42 .Nd temporary file routines

43 .Sh LIBRARY

44 .Lb libc

45 .Sh SYNOPSIS

46 .In stdio.h

47 .Ft FILE *

48 .Fo tmpfile

49 .Fa "void"

50 .Fc

51 .Ft char *

52 .Fo tmpnam

53 .Fa "char *s"

54 .Fc

55 .Ft char *

56 .Fo tempnam

57 .Fa "const char *dir"

58 .Fa "const char *pfx"

59 .Fc

60 .Sh DESCRIPTION

61 The

62 .Fn tmpfile

63 function

64 returns a pointer to a stream associated with a file descriptor returned

65 by the routine

66 .Xr mkstemp 3 .

67 The created file is unlinked before

68 .Fn tmpfile

69 returns, causing the file to be automatically deleted when the last

70 reference to it is closed.

71 The file is opened with the access value

72 .Ql w+ .

73 If the environment variable

74 .Ev TMPDIR

75 is defined,

76 the file is created in the specified directory.

77 The default location, if

78 .Ev TMPDIR

79 is not set, is

80 .Pa /tmp .

81 .Pp

82 The

83 .Fn tmpnam

84 function

85 returns a pointer to a file name, in the

86 .Dv P_tmpdir

87 directory, which

88 did not reference an existing file at some indeterminate point in the

89 past.

90 .Dv P_tmpdir

91 is defined in the include file

92 .In stdio.h .

93 If the argument

94 .Fa s

95 is

96 .Pf non- Dv NULL ,

97 the file name is copied to the buffer it references.

98 Otherwise, the file name is copied to a static buffer.

99 In either case,

100 .Fn tmpnam

101 returns a pointer to the file name.

102 .Pp

103 The buffer referenced by

104 .Fa s

105 is expected to be at least

106 .Dv L_tmpnam

107 bytes in length.

108 .Dv L_tmpnam

109 is defined in the include file

110 .In stdio.h .

111 .Pp

112 The

113 .Fn tempnam

114 function

115 is similar to

116 .Fn tmpnam ,

117 but provides the ability to specify the directory which will

118 contain the temporary file and the file name prefix.

119 .Pp

120 The argument

121 .Fa dir

122 (if

123 .Pf non- Dv NULL ) ,

124 the directory

125 .Dv P_tmpdir ,

126 the environment variable

127 .Ev TMPDIR

128 (if set),

129 the directory

130 .Pa /tmp

131 and finally, the current directory,

132 are tried, in the listed order, as directories in which to store the

133 temporary file.

134 .Pp

135 The argument

136 .Fa pfx ,

137 if

138 .Pf non- Dv NULL ,

139 is used to specify a file name prefix, which will be the

140 first part of the created file name.

141 The

142 .Fn tempnam

143 function

144 allocates memory in which to store the file name; the returned pointer

145 may be used as a subsequent argument to

146 .Xr free 3 .

147 .Sh RETURN VALUES

148 The

149 .Fn tmpfile

150 function

151 returns a pointer to an open file stream on success, and a

152 .Dv NULL

153 pointer

154 on error.

155 .Pp

156 The

157 .Fn tmpnam

158 and

159 .Fn tempfile

160 functions

161 return a pointer to a file name on success, and a

162 .Dv NULL

163 pointer

164 on error.

165 .Sh ENVIRONMENT

166 .Bl -tag -width Ds

167 .It Ev TMPDIR

168 .Pf [ Fn tempnam

169 only]

170 If set,

171 the directory in which the temporary file is stored.

172 .Ev TMPDIR

173 is ignored for processes

174 for which

175 .Xr issetugid 2

176 is true.

177 .El

178 .Sh COMPATIBILITY

179 These interfaces are provided from System V and

180 .Tn ANSI

181 compatibility only.

182 .Pp

183 Most historic implementations of these functions provide

184 only a limited number of possible temporary file names

185 (usually 26)

186 before file names will start being recycled.

187 System V implementations of these functions

188 (and of

189 .Xr mktemp 3 )

190 use the

191 .Xr access 2

192 system call to determine whether or not the temporary file

193 may be created.

194 This has obvious ramifications for setuid or setgid programs,

195 complicating the portable use of these interfaces in such programs.

196 .Pp

197 The

198 .Fn tmpfile

199 interface should not be used in software expected to be used on other systems

200 if there is any possibility that the user does not wish the temporary file to

201 be publicly readable and writable.

202 .Sh ERRORS

203 The

204 .Fn tmpfile

205 function

206 may fail and set the global variable

207 .Va errno

208 for any of the errors specified for the library functions

209 .Xr fdopen 3

210 or

211 .Xr mkstemp 3 .

212 .Pp

213 The

214 .Fn tmpnam

215 function

216 may fail and set

217 .Va errno

218 for any of the errors specified for the library function

219 .Xr mktemp 3 .

220 .Pp

221 The

222 .Fn tempnam

223 function

224 may fail and set

225 .Va errno

226 for any of the errors specified for the library functions

227 .Xr malloc 3

228 or

229 .Xr mktemp 3 .

230 .Sh SECURITY CONSIDERATIONS

231 The

232 .Fn tmpnam

233 and

234 .Fn tempnam

235 functions are susceptible to a race condition

236 occurring between the selection of the file name

237 and the creation of the file,

238 which allows malicious users

239 to potentially overwrite arbitrary files in the system,

240 depending on the level of privilege of the running program.

241 Additionally, there is no means by which

242 file permissions may be specified.

243 It is strongly suggested that

244 .Xr mkstemp 3

245 be used in place of these functions.

246 (See

247 the FSA.)

248 .Sh LEGACY DESCRIPTION

249 In legacy mode, the order directories are tried by the

250 .Fn tempnam

251 function is different; the environment variable

252 .Ev TMPDIR

253 (if defined) is used first.

254 .Sh SEE ALSO

255 .Xr mkstemp 3 ,

256 .Xr mktemp 3

257 .Sh STANDARDS

258 The

259 .Fn tmpfile

260 and

261 .Fn tmpnam

262 functions

263 conform to

264 .St -isoC .