Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "File::Temp 3" | |
132 | .TH File::Temp 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | File::Temp \- return name and handle of a temporary file safely | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use File::Temp qw/ tempfile tempdir /; | |
139 | .Ve | |
140 | .PP | |
141 | .Vb 2 | |
142 | \& $dir = tempdir( CLEANUP => 1 ); | |
143 | \& ($fh, $filename) = tempfile( DIR => $dir ); | |
144 | .Ve | |
145 | .PP | |
146 | .Vb 2 | |
147 | \& ($fh, $filename) = tempfile( $template, DIR => $dir); | |
148 | \& ($fh, $filename) = tempfile( $template, SUFFIX => '.dat'); | |
149 | .Ve | |
150 | .PP | |
151 | .Vb 1 | |
152 | \& $fh = tempfile(); | |
153 | .Ve | |
154 | .PP | |
155 | MkTemp family: | |
156 | .PP | |
157 | .Vb 1 | |
158 | \& use File::Temp qw/ :mktemp /; | |
159 | .Ve | |
160 | .PP | |
161 | .Vb 2 | |
162 | \& ($fh, $file) = mkstemp( "tmpfileXXXXX" ); | |
163 | \& ($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix); | |
164 | .Ve | |
165 | .PP | |
166 | .Vb 1 | |
167 | \& $tmpdir = mkdtemp( $template ); | |
168 | .Ve | |
169 | .PP | |
170 | .Vb 1 | |
171 | \& $unopened_file = mktemp( $template ); | |
172 | .Ve | |
173 | .PP | |
174 | \&\s-1POSIX\s0 functions: | |
175 | .PP | |
176 | .Vb 1 | |
177 | \& use File::Temp qw/ :POSIX /; | |
178 | .Ve | |
179 | .PP | |
180 | .Vb 2 | |
181 | \& $file = tmpnam(); | |
182 | \& $fh = tmpfile(); | |
183 | .Ve | |
184 | .PP | |
185 | .Vb 2 | |
186 | \& ($fh, $file) = tmpnam(); | |
187 | \& ($fh, $file) = tmpfile(); | |
188 | .Ve | |
189 | .PP | |
190 | Compatibility functions: | |
191 | .PP | |
192 | .Vb 1 | |
193 | \& $unopened_file = File::Temp::tempnam( $dir, $pfx ); | |
194 | .Ve | |
195 | .SH "DESCRIPTION" | |
196 | .IX Header "DESCRIPTION" | |
197 | \&\f(CW\*(C`File::Temp\*(C'\fR can be used to create and open temporary files in a safe way. | |
198 | The \fItempfile()\fR function can be used to return the name and the open | |
199 | filehandle of a temporary file. The \fItempdir()\fR function can | |
200 | be used to create a temporary directory. | |
201 | .PP | |
202 | The security aspect of temporary file creation is emphasized such that | |
203 | a filehandle and filename are returned together. This helps guarantee | |
204 | that a race condition can not occur where the temporary file is | |
205 | created by another process between checking for the existence of the | |
206 | file and its opening. Additional security levels are provided to | |
207 | check, for example, that the sticky bit is set on world writable | |
208 | directories. See \*(L"safe_level\*(R" for more information. | |
209 | .PP | |
210 | For compatibility with popular C library functions, Perl implementations of | |
211 | the \fImkstemp()\fR family of functions are provided. These are, \fImkstemp()\fR, | |
212 | \&\fImkstemps()\fR, \fImkdtemp()\fR and \fImktemp()\fR. | |
213 | .PP | |
214 | Additionally, implementations of the standard \s-1POSIX\s0 | |
215 | \&\fItmpnam()\fR and \fItmpfile()\fR functions are provided if required. | |
216 | .PP | |
217 | Implementations of \fImktemp()\fR, \fItmpnam()\fR, and \fItempnam()\fR are provided, | |
218 | but should be used with caution since they return only a filename | |
219 | that was valid when function was called, so cannot guarantee | |
220 | that the file will not exist by the time the caller opens the filename. | |
221 | .SH "FUNCTIONS" | |
222 | .IX Header "FUNCTIONS" | |
223 | This section describes the recommended interface for generating | |
224 | temporary files and directories. | |
225 | .IP "\fBtempfile\fR" 4 | |
226 | .IX Item "tempfile" | |
227 | This is the basic function to generate temporary files. | |
228 | The behaviour of the file can be changed using various options: | |
229 | .Sp | |
230 | .Vb 1 | |
231 | \& ($fh, $filename) = tempfile(); | |
232 | .Ve | |
233 | .Sp | |
234 | Create a temporary file in the directory specified for temporary | |
235 | files, as specified by the \fItmpdir()\fR function in File::Spec. | |
236 | .Sp | |
237 | .Vb 1 | |
238 | \& ($fh, $filename) = tempfile($template); | |
239 | .Ve | |
240 | .Sp | |
241 | Create a temporary file in the current directory using the supplied | |
242 | template. Trailing `X' characters are replaced with random letters to | |
243 | generate the filename. At least four `X' characters must be present | |
244 | in the template. | |
245 | .Sp | |
246 | .Vb 1 | |
247 | \& ($fh, $filename) = tempfile($template, SUFFIX => $suffix) | |
248 | .Ve | |
249 | .Sp | |
250 | Same as previously, except that a suffix is added to the template | |
251 | after the `X' translation. Useful for ensuring that a temporary | |
252 | filename has a particular extension when needed by other applications. | |
253 | But see the \s-1WARNING\s0 at the end. | |
254 | .Sp | |
255 | .Vb 1 | |
256 | \& ($fh, $filename) = tempfile($template, DIR => $dir); | |
257 | .Ve | |
258 | .Sp | |
259 | Translates the template as before except that a directory name | |
260 | is specified. | |
261 | .Sp | |
262 | .Vb 1 | |
263 | \& ($fh, $filename) = tempfile($template, UNLINK => 1); | |
264 | .Ve | |
265 | .Sp | |
266 | Return the filename and filehandle as before except that the file is | |
267 | automatically removed when the program exits. Default is for the file | |
268 | to be removed if a file handle is requested and to be kept if the | |
269 | filename is requested. In a scalar context (where no filename is | |
270 | returned) the file is always deleted either on exit or when it is closed. | |
271 | .Sp | |
272 | If the template is not specified, a template is always | |
273 | automatically generated. This temporary file is placed in \fItmpdir()\fR | |
274 | (File::Spec) unless a directory is specified explicitly with the | |
275 | \&\s-1DIR\s0 option. | |
276 | .Sp | |
277 | .Vb 1 | |
278 | \& $fh = tempfile( $template, DIR => $dir ); | |
279 | .Ve | |
280 | .Sp | |
281 | If called in scalar context, only the filehandle is returned | |
282 | and the file will automatically be deleted when closed (see | |
283 | the description of \fItmpfile()\fR elsewhere in this document). | |
284 | This is the preferred mode of operation, as if you only | |
285 | have a filehandle, you can never create a race condition | |
286 | by fumbling with the filename. On systems that can not unlink | |
287 | an open file or can not mark a file as temporary when it is opened | |
288 | (for example, Windows \s-1NT\s0 uses the \f(CW\*(C`O_TEMPORARY\*(C'\fR flag)) | |
289 | the file is marked for deletion when the program ends (equivalent | |
290 | to setting \s-1UNLINK\s0 to 1). The \f(CW\*(C`UNLINK\*(C'\fR flag is ignored if present. | |
291 | .Sp | |
292 | .Vb 1 | |
293 | \& (undef, $filename) = tempfile($template, OPEN => 0); | |
294 | .Ve | |
295 | .Sp | |
296 | This will return the filename based on the template but | |
297 | will not open this file. Cannot be used in conjunction with | |
298 | \&\s-1UNLINK\s0 set to true. Default is to always open the file | |
299 | to protect from possible race conditions. A warning is issued | |
300 | if warnings are turned on. Consider using the \fItmpnam()\fR | |
301 | and \fImktemp()\fR functions described elsewhere in this document | |
302 | if opening the file is not required. | |
303 | .Sp | |
304 | Options can be combined as required. | |
305 | .IP "\fBtempdir\fR" 4 | |
306 | .IX Item "tempdir" | |
307 | This is the recommended interface for creation of temporary directories. | |
308 | The behaviour of the function depends on the arguments: | |
309 | .Sp | |
310 | .Vb 1 | |
311 | \& $tempdir = tempdir(); | |
312 | .Ve | |
313 | .Sp | |
314 | Create a directory in \fItmpdir()\fR (see File::Spec). | |
315 | .Sp | |
316 | .Vb 1 | |
317 | \& $tempdir = tempdir( $template ); | |
318 | .Ve | |
319 | .Sp | |
320 | Create a directory from the supplied template. This template is | |
321 | similar to that described for \fItempfile()\fR. `X' characters at the end | |
322 | of the template are replaced with random letters to construct the | |
323 | directory name. At least four `X' characters must be in the template. | |
324 | .Sp | |
325 | .Vb 1 | |
326 | \& $tempdir = tempdir ( DIR => $dir ); | |
327 | .Ve | |
328 | .Sp | |
329 | Specifies the directory to use for the temporary directory. | |
330 | The temporary directory name is derived from an internal template. | |
331 | .Sp | |
332 | .Vb 1 | |
333 | \& $tempdir = tempdir ( $template, DIR => $dir ); | |
334 | .Ve | |
335 | .Sp | |
336 | Prepend the supplied directory name to the template. The template | |
337 | should not include parent directory specifications itself. Any parent | |
338 | directory specifications are removed from the template before | |
339 | prepending the supplied directory. | |
340 | .Sp | |
341 | .Vb 1 | |
342 | \& $tempdir = tempdir ( $template, TMPDIR => 1 ); | |
343 | .Ve | |
344 | .Sp | |
345 | Using the supplied template, create the temporary directory in | |
346 | a standard location for temporary files. Equivalent to doing | |
347 | .Sp | |
348 | .Vb 1 | |
349 | \& $tempdir = tempdir ( $template, DIR => File::Spec->tmpdir); | |
350 | .Ve | |
351 | .Sp | |
352 | but shorter. Parent directory specifications are stripped from the | |
353 | template itself. The \f(CW\*(C`TMPDIR\*(C'\fR option is ignored if \f(CW\*(C`DIR\*(C'\fR is set | |
354 | explicitly. Additionally, \f(CW\*(C`TMPDIR\*(C'\fR is implied if neither a template | |
355 | nor a directory are supplied. | |
356 | .Sp | |
357 | .Vb 1 | |
358 | \& $tempdir = tempdir( $template, CLEANUP => 1); | |
359 | .Ve | |
360 | .Sp | |
361 | Create a temporary directory using the supplied template, but | |
362 | attempt to remove it (and all files inside it) when the program | |
363 | exits. Note that an attempt will be made to remove all files from | |
364 | the directory even if they were not created by this module (otherwise | |
365 | why ask to clean it up?). The directory removal is made with | |
366 | the \fIrmtree()\fR function from the File::Path module. | |
367 | Of course, if the template is not specified, the temporary directory | |
368 | will be created in \fItmpdir()\fR and will also be removed at program exit. | |
369 | .SH "MKTEMP FUNCTIONS" | |
370 | .IX Header "MKTEMP FUNCTIONS" | |
371 | The following functions are Perl implementations of the | |
372 | \&\fImktemp()\fR family of temp file generation system calls. | |
373 | .IP "\fBmkstemp\fR" 4 | |
374 | .IX Item "mkstemp" | |
375 | Given a template, returns a filehandle to the temporary file and the name | |
376 | of the file. | |
377 | .Sp | |
378 | .Vb 1 | |
379 | \& ($fh, $name) = mkstemp( $template ); | |
380 | .Ve | |
381 | .Sp | |
382 | In scalar context, just the filehandle is returned. | |
383 | .Sp | |
384 | The template may be any filename with some number of X's appended | |
385 | to it, for example \fI/tmp/temp.XXXX\fR. The trailing X's are replaced | |
386 | with unique alphanumeric combinations. | |
387 | .IP "\fBmkstemps\fR" 4 | |
388 | .IX Item "mkstemps" | |
389 | Similar to \fImkstemp()\fR, except that an extra argument can be supplied | |
390 | with a suffix to be appended to the template. | |
391 | .Sp | |
392 | .Vb 1 | |
393 | \& ($fh, $name) = mkstemps( $template, $suffix ); | |
394 | .Ve | |
395 | .Sp | |
396 | For example a template of \f(CW\*(C`testXXXXXX\*(C'\fR and suffix of \f(CW\*(C`.dat\*(C'\fR | |
397 | would generate a file similar to \fItesthGji_w.dat\fR. | |
398 | .Sp | |
399 | Returns just the filehandle alone when called in scalar context. | |
400 | .IP "\fBmkdtemp\fR" 4 | |
401 | .IX Item "mkdtemp" | |
402 | Create a directory from a template. The template must end in | |
403 | X's that are replaced by the routine. | |
404 | .Sp | |
405 | .Vb 1 | |
406 | \& $tmpdir_name = mkdtemp($template); | |
407 | .Ve | |
408 | .Sp | |
409 | Returns the name of the temporary directory created. | |
410 | Returns undef on failure. | |
411 | .Sp | |
412 | Directory must be removed by the caller. | |
413 | .IP "\fBmktemp\fR" 4 | |
414 | .IX Item "mktemp" | |
415 | Returns a valid temporary filename but does not guarantee | |
416 | that the file will not be opened by someone else. | |
417 | .Sp | |
418 | .Vb 1 | |
419 | \& $unopened_file = mktemp($template); | |
420 | .Ve | |
421 | .Sp | |
422 | Template is the same as that required by \fImkstemp()\fR. | |
423 | .SH "POSIX FUNCTIONS" | |
424 | .IX Header "POSIX FUNCTIONS" | |
425 | This section describes the re-implementation of the \fItmpnam()\fR | |
426 | and \fItmpfile()\fR functions described in \s-1POSIX\s0 | |
427 | using the \fImkstemp()\fR from this module. | |
428 | .PP | |
429 | Unlike the \s-1POSIX\s0 implementations, the directory used | |
430 | for the temporary file is not specified in a system include | |
431 | file (\f(CW\*(C`P_tmpdir\*(C'\fR) but simply depends on the choice of \fItmpdir()\fR | |
432 | returned by File::Spec. On some implementations this | |
433 | location can be set using the \f(CW\*(C`TMPDIR\*(C'\fR environment variable, which | |
434 | may not be secure. | |
435 | If this is a problem, simply use \fImkstemp()\fR and specify a template. | |
436 | .IP "\fBtmpnam\fR" 4 | |
437 | .IX Item "tmpnam" | |
438 | When called in scalar context, returns the full name (including path) | |
439 | of a temporary file (uses \fImktemp()\fR). The only check is that the file does | |
440 | not already exist, but there is no guarantee that that condition will | |
441 | continue to apply. | |
442 | .Sp | |
443 | .Vb 1 | |
444 | \& $file = tmpnam(); | |
445 | .Ve | |
446 | .Sp | |
447 | When called in list context, a filehandle to the open file and | |
448 | a filename are returned. This is achieved by calling \fImkstemp()\fR | |
449 | after constructing a suitable template. | |
450 | .Sp | |
451 | .Vb 1 | |
452 | \& ($fh, $file) = tmpnam(); | |
453 | .Ve | |
454 | .Sp | |
455 | If possible, this form should be used to prevent possible | |
456 | race conditions. | |
457 | .Sp | |
458 | See \*(L"tmpdir\*(R" in File::Spec for information on the choice of temporary | |
459 | directory for a particular operating system. | |
460 | .IP "\fBtmpfile\fR" 4 | |
461 | .IX Item "tmpfile" | |
462 | In scalar context, returns the filehandle of a temporary file. | |
463 | .Sp | |
464 | .Vb 1 | |
465 | \& $fh = tmpfile(); | |
466 | .Ve | |
467 | .Sp | |
468 | The file is removed when the filehandle is closed or when the program | |
469 | exits. No access to the filename is provided. | |
470 | .Sp | |
471 | If the temporary file can not be created undef is returned. | |
472 | Currently this command will probably not work when the temporary | |
473 | directory is on an \s-1NFS\s0 file system. | |
474 | .SH "ADDITIONAL FUNCTIONS" | |
475 | .IX Header "ADDITIONAL FUNCTIONS" | |
476 | These functions are provided for backwards compatibility | |
477 | with common tempfile generation C library functions. | |
478 | .PP | |
479 | They are not exported and must be addressed using the full package | |
480 | name. | |
481 | .IP "\fBtempnam\fR" 4 | |
482 | .IX Item "tempnam" | |
483 | Return the name of a temporary file in the specified directory | |
484 | using a prefix. The file is guaranteed not to exist at the time | |
485 | the function was called, but such guarantees are good for one | |
486 | clock tick only. Always use the proper form of \f(CW\*(C`sysopen\*(C'\fR | |
487 | with \f(CW\*(C`O_CREAT | O_EXCL\*(C'\fR if you must open such a filename. | |
488 | .Sp | |
489 | .Vb 1 | |
490 | \& $filename = File::Temp::tempnam( $dir, $prefix ); | |
491 | .Ve | |
492 | .Sp | |
493 | Equivalent to running \fImktemp()\fR with \f(CW$dir\fR/$prefixXXXXXXXX | |
494 | (using unix file convention as an example) | |
495 | .Sp | |
496 | Because this function uses \fImktemp()\fR, it can suffer from race conditions. | |
497 | .SH "UTILITY FUNCTIONS" | |
498 | .IX Header "UTILITY FUNCTIONS" | |
499 | Useful functions for dealing with the filehandle and filename. | |
500 | .IP "\fBunlink0\fR" 4 | |
501 | .IX Item "unlink0" | |
502 | Given an open filehandle and the associated filename, make a safe | |
503 | unlink. This is achieved by first checking that the filename and | |
504 | filehandle initially point to the same file and that the number of | |
505 | links to the file is 1 (all fields returned by \fIstat()\fR are compared). | |
506 | Then the filename is unlinked and the filehandle checked once again to | |
507 | verify that the number of links on that file is now 0. This is the | |
508 | closest you can come to making sure that the filename unlinked was the | |
509 | same as the file whose descriptor you hold. | |
510 | .Sp | |
511 | .Vb 1 | |
512 | \& unlink0($fh, $path) or die "Error unlinking file $path safely"; | |
513 | .Ve | |
514 | .Sp | |
515 | Returns false on error. The filehandle is not closed since on some | |
516 | occasions this is not required. | |
517 | .Sp | |
518 | On some platforms, for example Windows \s-1NT\s0, it is not possible to | |
519 | unlink an open file (the file must be closed first). On those | |
520 | platforms, the actual unlinking is deferred until the program ends and | |
521 | good status is returned. A check is still performed to make sure that | |
522 | the filehandle and filename are pointing to the same thing (but not at | |
523 | the time the end block is executed since the deferred removal may not | |
524 | have access to the filehandle). | |
525 | .Sp | |
526 | Additionally, on Windows \s-1NT\s0 not all the fields returned by \fIstat()\fR can | |
527 | be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be | |
528 | different. Also, it seems that the size of the file returned by \fIstat()\fR | |
529 | does not always agree, with \f(CW\*(C`stat(FH)\*(C'\fR being more accurate than | |
530 | \&\f(CW\*(C`stat(filename)\*(C'\fR, presumably because of caching issues even when | |
531 | using autoflush (this is usually overcome by waiting a while after | |
532 | writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it). | |
533 | .Sp | |
534 | Finally, on \s-1NFS\s0 file systems the link count of the file handle does | |
535 | not always go to zero immediately after unlinking. Currently, this | |
536 | command is expected to fail on \s-1NFS\s0 disks. | |
537 | .SH "PACKAGE VARIABLES" | |
538 | .IX Header "PACKAGE VARIABLES" | |
539 | These functions control the global state of the package. | |
540 | .IP "\fBsafe_level\fR" 4 | |
541 | .IX Item "safe_level" | |
542 | Controls the lengths to which the module will go to check the safety of the | |
543 | temporary file or directory before proceeding. | |
544 | Options are: | |
545 | .RS 4 | |
546 | .IP "\s-1STANDARD\s0" 8 | |
547 | .IX Item "STANDARD" | |
548 | Do the basic security measures to ensure the directory exists and | |
549 | is writable, that the \fIumask()\fR is fixed before opening of the file, | |
550 | that temporary files are opened only if they do not already exist, and | |
551 | that possible race conditions are avoided. Finally the unlink0 | |
552 | function is used to remove files safely. | |
553 | .IP "\s-1MEDIUM\s0" 8 | |
554 | .IX Item "MEDIUM" | |
555 | In addition to the \s-1STANDARD\s0 security, the output directory is checked | |
556 | to make sure that it is owned either by root or the user running the | |
557 | program. If the directory is writable by group or by other, it is then | |
558 | checked to make sure that the sticky bit is set. | |
559 | .Sp | |
560 | Will not work on platforms that do not support the \f(CW\*(C`\-k\*(C'\fR test | |
561 | for sticky bit. | |
562 | .IP "\s-1HIGH\s0" 8 | |
563 | .IX Item "HIGH" | |
564 | In addition to the \s-1MEDIUM\s0 security checks, also check for the | |
565 | possibility of ``\fIchown()\fR giveaway'' using the \s-1POSIX\s0 | |
566 | \&\fIsysconf()\fR function. If this is a possibility, each directory in the | |
567 | path is checked in turn for safeness, recursively walking back to the | |
568 | root directory. | |
569 | .Sp | |
570 | For platforms that do not support the \s-1POSIX\s0 | |
571 | \&\f(CW\*(C`_PC_CHOWN_RESTRICTED\*(C'\fR symbol (for example, Windows \s-1NT\s0) it is | |
572 | assumed that ``\fIchown()\fR giveaway'' is possible and the recursive test | |
573 | is performed. | |
574 | .RE | |
575 | .RS 4 | |
576 | .Sp | |
577 | The level can be changed as follows: | |
578 | .Sp | |
579 | .Vb 1 | |
580 | \& File::Temp->safe_level( File::Temp::HIGH ); | |
581 | .Ve | |
582 | .Sp | |
583 | The level constants are not exported by the module. | |
584 | .Sp | |
585 | Currently, you must be running at least perl v5.6.0 in order to | |
586 | run with \s-1MEDIUM\s0 or \s-1HIGH\s0 security. This is simply because the | |
587 | safety tests use functions from Fcntl that are not | |
588 | available in older versions of perl. The problem is that the version | |
589 | number for Fcntl is the same in perl 5.6.0 and in 5.005_03 even though | |
590 | they are different versions. | |
591 | .Sp | |
592 | On systems that do not support the \s-1HIGH\s0 or \s-1MEDIUM\s0 safety levels | |
593 | (for example Win \s-1NT\s0 or \s-1OS/2\s0) any attempt to change the level will | |
594 | be ignored. The decision to ignore rather than raise an exception | |
595 | allows portable programs to be written with high security in mind | |
596 | for the systems that can support this without those programs failing | |
597 | on systems where the extra tests are irrelevant. | |
598 | .Sp | |
599 | If you really need to see whether the change has been accepted | |
600 | simply examine the return value of \f(CW\*(C`safe_level\*(C'\fR. | |
601 | .Sp | |
602 | .Vb 3 | |
603 | \& $newlevel = File::Temp->safe_level( File::Temp::HIGH ); | |
604 | \& die "Could not change to high security" | |
605 | \& if $newlevel != File::Temp::HIGH; | |
606 | .Ve | |
607 | .RE | |
608 | .IP "TopSystemUID" 4 | |
609 | .IX Item "TopSystemUID" | |
610 | This is the highest \s-1UID\s0 on the current system that refers to a root | |
611 | \&\s-1UID\s0. This is used to make sure that the temporary directory is | |
612 | owned by a system \s-1UID\s0 (\f(CW\*(C`root\*(C'\fR, \f(CW\*(C`bin\*(C'\fR, \f(CW\*(C`sys\*(C'\fR etc) rather than | |
613 | simply by root. | |
614 | .Sp | |
615 | This is required since on many unix systems \f(CW\*(C`/tmp\*(C'\fR is not owned | |
616 | by root. | |
617 | .Sp | |
618 | Default is to assume that any \s-1UID\s0 less than or equal to 10 is a root | |
619 | \&\s-1UID\s0. | |
620 | .Sp | |
621 | .Vb 2 | |
622 | \& File::Temp->top_system_uid(10); | |
623 | \& my $topid = File::Temp->top_system_uid; | |
624 | .Ve | |
625 | .Sp | |
626 | This value can be adjusted to reduce security checking if required. | |
627 | The value is only relevant when \f(CW\*(C`safe_level\*(C'\fR is set to \s-1MEDIUM\s0 or higher. | |
628 | .SH "WARNING" | |
629 | .IX Header "WARNING" | |
630 | For maximum security, endeavour always to avoid ever looking at, | |
631 | touching, or even imputing the existence of the filename. You do not | |
632 | know that that filename is connected to the same file as the handle | |
633 | you have, and attempts to check this can only trigger more race | |
634 | conditions. It's far more secure to use the filehandle alone and | |
635 | dispense with the filename altogether. | |
636 | .PP | |
637 | If you need to pass the handle to something that expects a filename | |
638 | then, on a unix system, use \f(CW\*(C`"/dev/fd/" . fileno($fh)\*(C'\fR for arbitrary | |
639 | programs, or more generally \f(CW\*(C`"+<=&" . fileno($fh)\*(C'\fR for Perl | |
640 | programs. You will have to clear the close-on-exec bit on that file | |
641 | descriptor before passing it to another process. | |
642 | .PP | |
643 | .Vb 3 | |
644 | \& use Fcntl qw/F_SETFD F_GETFD/; | |
645 | \& fcntl($tmpfh, F_SETFD, 0) | |
646 | \& or die "Can't clear close-on-exec flag on temp fh: $!\en"; | |
647 | .Ve | |
648 | .Sh "Temporary files and \s-1NFS\s0" | |
649 | .IX Subsection "Temporary files and NFS" | |
650 | Some problems are associated with using temporary files that reside | |
651 | on \s-1NFS\s0 file systems and it is recommended that a local filesystem | |
652 | is used whenever possible. Some of the security tests will most probably | |
653 | fail when the temp file is not local. Additionally, be aware that | |
654 | the performance of I/O operations over \s-1NFS\s0 will not be as good as for | |
655 | a local disk. | |
656 | .SH "HISTORY" | |
657 | .IX Header "HISTORY" | |
658 | Originally began life in May 1999 as an \s-1XS\s0 interface to the system | |
659 | \&\fImkstemp()\fR function. In March 2000, the OpenBSD \fImkstemp()\fR code was | |
660 | translated to Perl for total control of the code's | |
661 | security checking, to ensure the presence of the function regardless of | |
662 | operating system and to help with portability. | |
663 | .SH "SEE ALSO" | |
664 | .IX Header "SEE ALSO" | |
665 | \&\*(L"tmpnam\*(R" in \s-1POSIX\s0, \*(L"tmpfile\*(R" in \s-1POSIX\s0, File::Spec, File::Path | |
666 | .PP | |
667 | See IO::File and File::MkTemp for different implementations of | |
668 | temporary file handling. | |
669 | .SH "AUTHOR" | |
670 | .IX Header "AUTHOR" | |
671 | Tim Jenness <t.jenness@jach.hawaii.edu> | |
672 | .PP | |
673 | Copyright (C) 1999\-2001 Tim Jenness and the \s-1UK\s0 Particle Physics and | |
674 | Astronomy Research Council. All Rights Reserved. This program is free | |
675 | software; you can redistribute it and/or modify it under the same | |
676 | terms as Perl itself. | |
677 | .PP | |
678 | Original Perl implementation loosely based on the OpenBSD C code for | |
679 | \&\fImkstemp()\fR. Thanks to Tom Christiansen for suggesting that this module | |
680 | should be written and providing ideas for code improvements and | |
681 | security enhancements. |