| 1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
| 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 "2001-09-21" "perl v5.8.8" "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 | \& $fh = tempfile(); |
| 143 | \& ($fh, $filename) = tempfile(); |
| 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 2 |
| 152 | \& $dir = tempdir( CLEANUP => 1 ); |
| 153 | \& ($fh, $filename) = tempfile( DIR => $dir ); |
| 154 | .Ve |
| 155 | .PP |
| 156 | Object interface: |
| 157 | .PP |
| 158 | .Vb 2 |
| 159 | \& require File::Temp; |
| 160 | \& use File::Temp (); |
| 161 | .Ve |
| 162 | .PP |
| 163 | .Vb 2 |
| 164 | \& $fh = new File::Temp($template); |
| 165 | \& $fname = $fh->filename; |
| 166 | .Ve |
| 167 | .PP |
| 168 | .Vb 3 |
| 169 | \& $tmp = new File::Temp( UNLINK => 0, SUFFIX => '.dat' ); |
| 170 | \& print $tmp "Some data\en"; |
| 171 | \& print "Filename is $tmp\en"; |
| 172 | .Ve |
| 173 | .PP |
| 174 | The following interfaces are provided for compatibility with |
| 175 | existing APIs. They should not be used in new code. |
| 176 | .PP |
| 177 | MkTemp family: |
| 178 | .PP |
| 179 | .Vb 1 |
| 180 | \& use File::Temp qw/ :mktemp /; |
| 181 | .Ve |
| 182 | .PP |
| 183 | .Vb 2 |
| 184 | \& ($fh, $file) = mkstemp( "tmpfileXXXXX" ); |
| 185 | \& ($fh, $file) = mkstemps( "tmpfileXXXXXX", $suffix); |
| 186 | .Ve |
| 187 | .PP |
| 188 | .Vb 1 |
| 189 | \& $tmpdir = mkdtemp( $template ); |
| 190 | .Ve |
| 191 | .PP |
| 192 | .Vb 1 |
| 193 | \& $unopened_file = mktemp( $template ); |
| 194 | .Ve |
| 195 | .PP |
| 196 | \&\s-1POSIX\s0 functions: |
| 197 | .PP |
| 198 | .Vb 1 |
| 199 | \& use File::Temp qw/ :POSIX /; |
| 200 | .Ve |
| 201 | .PP |
| 202 | .Vb 2 |
| 203 | \& $file = tmpnam(); |
| 204 | \& $fh = tmpfile(); |
| 205 | .Ve |
| 206 | .PP |
| 207 | .Vb 1 |
| 208 | \& ($fh, $file) = tmpnam(); |
| 209 | .Ve |
| 210 | .PP |
| 211 | Compatibility functions: |
| 212 | .PP |
| 213 | .Vb 1 |
| 214 | \& $unopened_file = File::Temp::tempnam( $dir, $pfx ); |
| 215 | .Ve |
| 216 | .SH "DESCRIPTION" |
| 217 | .IX Header "DESCRIPTION" |
| 218 | \&\f(CW\*(C`File::Temp\*(C'\fR can be used to create and open temporary files in a safe |
| 219 | way. There is both a function interface and an object-oriented |
| 220 | interface. The File::Temp constructor or the \fItempfile()\fR function can |
| 221 | be used to return the name and the open filehandle of a temporary |
| 222 | file. The \fItempdir()\fR function can be used to create a temporary |
| 223 | directory. |
| 224 | .PP |
| 225 | The security aspect of temporary file creation is emphasized such that |
| 226 | a filehandle and filename are returned together. This helps guarantee |
| 227 | that a race condition can not occur where the temporary file is |
| 228 | created by another process between checking for the existence of the |
| 229 | file and its opening. Additional security levels are provided to |
| 230 | check, for example, that the sticky bit is set on world writable |
| 231 | directories. See \*(L"safe_level\*(R" for more information. |
| 232 | .PP |
| 233 | For compatibility with popular C library functions, Perl implementations of |
| 234 | the \fImkstemp()\fR family of functions are provided. These are, \fImkstemp()\fR, |
| 235 | \&\fImkstemps()\fR, \fImkdtemp()\fR and \fImktemp()\fR. |
| 236 | .PP |
| 237 | Additionally, implementations of the standard \s-1POSIX\s0 |
| 238 | \&\fItmpnam()\fR and \fItmpfile()\fR functions are provided if required. |
| 239 | .PP |
| 240 | Implementations of \fImktemp()\fR, \fItmpnam()\fR, and \fItempnam()\fR are provided, |
| 241 | but should be used with caution since they return only a filename |
| 242 | that was valid when function was called, so cannot guarantee |
| 243 | that the file will not exist by the time the caller opens the filename. |
| 244 | .SH "OBJECT-ORIENTED INTERFACE" |
| 245 | .IX Header "OBJECT-ORIENTED INTERFACE" |
| 246 | This is the primary interface for interacting with |
| 247 | \&\f(CW\*(C`File::Temp\*(C'\fR. Using the \s-1OO\s0 interface a temporary file can be created |
| 248 | when the object is constructed and the file can be removed when the |
| 249 | object is no longer required. |
| 250 | .PP |
| 251 | Note that there is no method to obtain the filehandle from the |
| 252 | \&\f(CW\*(C`File::Temp\*(C'\fR object. The object itself acts as a filehandle. Also, |
| 253 | the object is configured such that it stringifies to the name of the |
| 254 | temporary file. |
| 255 | .IP "\fBnew\fR" 4 |
| 256 | .IX Item "new" |
| 257 | Create a temporary file object. |
| 258 | .Sp |
| 259 | .Vb 1 |
| 260 | \& my $tmp = new File::Temp(); |
| 261 | .Ve |
| 262 | .Sp |
| 263 | by default the object is constructed as if \f(CW\*(C`tempfile\*(C'\fR |
| 264 | was called without options, but with the additional behaviour |
| 265 | that the temporary file is removed by the object destructor |
| 266 | if \s-1UNLINK\s0 is set to true (the default). |
| 267 | .Sp |
| 268 | Supported arguments are the same as for \f(CW\*(C`tempfile\*(C'\fR: \s-1UNLINK\s0 |
| 269 | (defaulting to true), \s-1DIR\s0 and \s-1SUFFIX\s0. Additionally, the filename |
| 270 | template is specified using the \s-1TEMPLATE\s0 option. The \s-1OPEN\s0 option |
| 271 | is not supported (the file is always opened). |
| 272 | .Sp |
| 273 | .Vb 3 |
| 274 | \& $tmp = new File::Temp( TEMPLATE => 'tempXXXXX', |
| 275 | \& DIR => 'mydir', |
| 276 | \& SUFFIX => '.dat'); |
| 277 | .Ve |
| 278 | .Sp |
| 279 | Arguments are case insensitive. |
| 280 | .IP "\fBfilename\fR" 4 |
| 281 | .IX Item "filename" |
| 282 | Return the name of the temporary file associated with this object. |
| 283 | .Sp |
| 284 | .Vb 1 |
| 285 | \& $filename = $tmp->filename; |
| 286 | .Ve |
| 287 | .Sp |
| 288 | This method is called automatically when the object is used as |
| 289 | a string. |
| 290 | .IP "\fBunlink_on_destroy\fR" 4 |
| 291 | .IX Item "unlink_on_destroy" |
| 292 | Control whether the file is unlinked when the object goes out of scope. |
| 293 | The file is removed if this value is true and \f(CW$KEEP_ALL\fR is not. |
| 294 | .Sp |
| 295 | .Vb 1 |
| 296 | \& $fh->unlink_on_destroy( 1 ); |
| 297 | .Ve |
| 298 | .Sp |
| 299 | Default is for the file to be removed. |
| 300 | .IP "\fB\s-1DESTROY\s0\fR" 4 |
| 301 | .IX Item "DESTROY" |
| 302 | When the object goes out of scope, the destructor is called. This |
| 303 | destructor will attempt to unlink the file (using \f(CW\*(C`unlink1\*(C'\fR) |
| 304 | if the constructor was called with \s-1UNLINK\s0 set to 1 (the default state |
| 305 | if \s-1UNLINK\s0 is not specified). |
| 306 | .Sp |
| 307 | No error is given if the unlink fails. |
| 308 | .Sp |
| 309 | If the global variable \f(CW$KEEP_ALL\fR is true, the file will not be removed. |
| 310 | .SH "FUNCTIONS" |
| 311 | .IX Header "FUNCTIONS" |
| 312 | This section describes the recommended interface for generating |
| 313 | temporary files and directories. |
| 314 | .IP "\fBtempfile\fR" 4 |
| 315 | .IX Item "tempfile" |
| 316 | This is the basic function to generate temporary files. |
| 317 | The behaviour of the file can be changed using various options: |
| 318 | .Sp |
| 319 | .Vb 2 |
| 320 | \& $fh = tempfile(); |
| 321 | \& ($fh, $filename) = tempfile(); |
| 322 | .Ve |
| 323 | .Sp |
| 324 | Create a temporary file in the directory specified for temporary |
| 325 | files, as specified by the \fItmpdir()\fR function in File::Spec. |
| 326 | .Sp |
| 327 | .Vb 1 |
| 328 | \& ($fh, $filename) = tempfile($template); |
| 329 | .Ve |
| 330 | .Sp |
| 331 | Create a temporary file in the current directory using the supplied |
| 332 | template. Trailing `X' characters are replaced with random letters to |
| 333 | generate the filename. At least four `X' characters must be present |
| 334 | at the end of the template. |
| 335 | .Sp |
| 336 | .Vb 1 |
| 337 | \& ($fh, $filename) = tempfile($template, SUFFIX => $suffix) |
| 338 | .Ve |
| 339 | .Sp |
| 340 | Same as previously, except that a suffix is added to the template |
| 341 | after the `X' translation. Useful for ensuring that a temporary |
| 342 | filename has a particular extension when needed by other applications. |
| 343 | But see the \s-1WARNING\s0 at the end. |
| 344 | .Sp |
| 345 | .Vb 1 |
| 346 | \& ($fh, $filename) = tempfile($template, DIR => $dir); |
| 347 | .Ve |
| 348 | .Sp |
| 349 | Translates the template as before except that a directory name |
| 350 | is specified. |
| 351 | .Sp |
| 352 | .Vb 1 |
| 353 | \& ($fh, $filename) = tempfile($template, UNLINK => 1); |
| 354 | .Ve |
| 355 | .Sp |
| 356 | Return the filename and filehandle as before except that the file is |
| 357 | automatically removed when the program exits (dependent on |
| 358 | \&\f(CW$KEEP_ALL\fR). Default is for the file to be removed if a file handle is |
| 359 | requested and to be kept if the filename is requested. In a scalar |
| 360 | context (where no filename is returned) the file is always deleted |
| 361 | either (depending on the operating system) on exit or when it is |
| 362 | closed (unless \f(CW$KEEP_ALL\fR is true when the temp file is created). |
| 363 | .Sp |
| 364 | Use the object-oriented interface if fine-grained control of when |
| 365 | a file is removed is required. |
| 366 | .Sp |
| 367 | If the template is not specified, a template is always |
| 368 | automatically generated. This temporary file is placed in \fItmpdir()\fR |
| 369 | (File::Spec) unless a directory is specified explicitly with the |
| 370 | \&\s-1DIR\s0 option. |
| 371 | .Sp |
| 372 | .Vb 1 |
| 373 | \& $fh = tempfile( $template, DIR => $dir ); |
| 374 | .Ve |
| 375 | .Sp |
| 376 | If called in scalar context, only the filehandle is returned and the |
| 377 | file will automatically be deleted when closed on operating systems |
| 378 | that support this (see the description of \fItmpfile()\fR elsewhere in this |
| 379 | document). This is the preferred mode of operation, as if you only |
| 380 | have a filehandle, you can never create a race condition by fumbling |
| 381 | with the filename. On systems that can not unlink an open file or can |
| 382 | not mark a file as temporary when it is opened (for example, Windows |
| 383 | \&\s-1NT\s0 uses the \f(CW\*(C`O_TEMPORARY\*(C'\fR flag) the file is marked for deletion when |
| 384 | the program ends (equivalent to setting \s-1UNLINK\s0 to 1). The \f(CW\*(C`UNLINK\*(C'\fR |
| 385 | flag is ignored if present. |
| 386 | .Sp |
| 387 | .Vb 1 |
| 388 | \& (undef, $filename) = tempfile($template, OPEN => 0); |
| 389 | .Ve |
| 390 | .Sp |
| 391 | This will return the filename based on the template but |
| 392 | will not open this file. Cannot be used in conjunction with |
| 393 | \&\s-1UNLINK\s0 set to true. Default is to always open the file |
| 394 | to protect from possible race conditions. A warning is issued |
| 395 | if warnings are turned on. Consider using the \fItmpnam()\fR |
| 396 | and \fImktemp()\fR functions described elsewhere in this document |
| 397 | if opening the file is not required. |
| 398 | .Sp |
| 399 | Options can be combined as required. |
| 400 | .IP "\fBtempdir\fR" 4 |
| 401 | .IX Item "tempdir" |
| 402 | This is the recommended interface for creation of temporary directories. |
| 403 | The behaviour of the function depends on the arguments: |
| 404 | .Sp |
| 405 | .Vb 1 |
| 406 | \& $tempdir = tempdir(); |
| 407 | .Ve |
| 408 | .Sp |
| 409 | Create a directory in \fItmpdir()\fR (see File::Spec). |
| 410 | .Sp |
| 411 | .Vb 1 |
| 412 | \& $tempdir = tempdir( $template ); |
| 413 | .Ve |
| 414 | .Sp |
| 415 | Create a directory from the supplied template. This template is |
| 416 | similar to that described for \fItempfile()\fR. `X' characters at the end |
| 417 | of the template are replaced with random letters to construct the |
| 418 | directory name. At least four `X' characters must be in the template. |
| 419 | .Sp |
| 420 | .Vb 1 |
| 421 | \& $tempdir = tempdir ( DIR => $dir ); |
| 422 | .Ve |
| 423 | .Sp |
| 424 | Specifies the directory to use for the temporary directory. |
| 425 | The temporary directory name is derived from an internal template. |
| 426 | .Sp |
| 427 | .Vb 1 |
| 428 | \& $tempdir = tempdir ( $template, DIR => $dir ); |
| 429 | .Ve |
| 430 | .Sp |
| 431 | Prepend the supplied directory name to the template. The template |
| 432 | should not include parent directory specifications itself. Any parent |
| 433 | directory specifications are removed from the template before |
| 434 | prepending the supplied directory. |
| 435 | .Sp |
| 436 | .Vb 1 |
| 437 | \& $tempdir = tempdir ( $template, TMPDIR => 1 ); |
| 438 | .Ve |
| 439 | .Sp |
| 440 | Using the supplied template, create the temporary directory in |
| 441 | a standard location for temporary files. Equivalent to doing |
| 442 | .Sp |
| 443 | .Vb 1 |
| 444 | \& $tempdir = tempdir ( $template, DIR => File::Spec->tmpdir); |
| 445 | .Ve |
| 446 | .Sp |
| 447 | but shorter. Parent directory specifications are stripped from the |
| 448 | template itself. The \f(CW\*(C`TMPDIR\*(C'\fR option is ignored if \f(CW\*(C`DIR\*(C'\fR is set |
| 449 | explicitly. Additionally, \f(CW\*(C`TMPDIR\*(C'\fR is implied if neither a template |
| 450 | nor a directory are supplied. |
| 451 | .Sp |
| 452 | .Vb 1 |
| 453 | \& $tempdir = tempdir( $template, CLEANUP => 1); |
| 454 | .Ve |
| 455 | .Sp |
| 456 | Create a temporary directory using the supplied template, but |
| 457 | attempt to remove it (and all files inside it) when the program |
| 458 | exits. Note that an attempt will be made to remove all files from |
| 459 | the directory even if they were not created by this module (otherwise |
| 460 | why ask to clean it up?). The directory removal is made with |
| 461 | the \fIrmtree()\fR function from the File::Path module. |
| 462 | Of course, if the template is not specified, the temporary directory |
| 463 | will be created in \fItmpdir()\fR and will also be removed at program exit. |
| 464 | .SH "MKTEMP FUNCTIONS" |
| 465 | .IX Header "MKTEMP FUNCTIONS" |
| 466 | The following functions are Perl implementations of the |
| 467 | \&\fImktemp()\fR family of temp file generation system calls. |
| 468 | .IP "\fBmkstemp\fR" 4 |
| 469 | .IX Item "mkstemp" |
| 470 | Given a template, returns a filehandle to the temporary file and the name |
| 471 | of the file. |
| 472 | .Sp |
| 473 | .Vb 1 |
| 474 | \& ($fh, $name) = mkstemp( $template ); |
| 475 | .Ve |
| 476 | .Sp |
| 477 | In scalar context, just the filehandle is returned. |
| 478 | .Sp |
| 479 | The template may be any filename with some number of X's appended |
| 480 | to it, for example \fI/tmp/temp.XXXX\fR. The trailing X's are replaced |
| 481 | with unique alphanumeric combinations. |
| 482 | .IP "\fBmkstemps\fR" 4 |
| 483 | .IX Item "mkstemps" |
| 484 | Similar to \fImkstemp()\fR, except that an extra argument can be supplied |
| 485 | with a suffix to be appended to the template. |
| 486 | .Sp |
| 487 | .Vb 1 |
| 488 | \& ($fh, $name) = mkstemps( $template, $suffix ); |
| 489 | .Ve |
| 490 | .Sp |
| 491 | For example a template of \f(CW\*(C`testXXXXXX\*(C'\fR and suffix of \f(CW\*(C`.dat\*(C'\fR |
| 492 | would generate a file similar to \fItesthGji_w.dat\fR. |
| 493 | .Sp |
| 494 | Returns just the filehandle alone when called in scalar context. |
| 495 | .IP "\fBmkdtemp\fR" 4 |
| 496 | .IX Item "mkdtemp" |
| 497 | Create a directory from a template. The template must end in |
| 498 | X's that are replaced by the routine. |
| 499 | .Sp |
| 500 | .Vb 1 |
| 501 | \& $tmpdir_name = mkdtemp($template); |
| 502 | .Ve |
| 503 | .Sp |
| 504 | Returns the name of the temporary directory created. |
| 505 | Returns undef on failure. |
| 506 | .Sp |
| 507 | Directory must be removed by the caller. |
| 508 | .IP "\fBmktemp\fR" 4 |
| 509 | .IX Item "mktemp" |
| 510 | Returns a valid temporary filename but does not guarantee |
| 511 | that the file will not be opened by someone else. |
| 512 | .Sp |
| 513 | .Vb 1 |
| 514 | \& $unopened_file = mktemp($template); |
| 515 | .Ve |
| 516 | .Sp |
| 517 | Template is the same as that required by \fImkstemp()\fR. |
| 518 | .SH "POSIX FUNCTIONS" |
| 519 | .IX Header "POSIX FUNCTIONS" |
| 520 | This section describes the re-implementation of the \fItmpnam()\fR |
| 521 | and \fItmpfile()\fR functions described in \s-1POSIX\s0 |
| 522 | using the \fImkstemp()\fR from this module. |
| 523 | .PP |
| 524 | Unlike the \s-1POSIX\s0 implementations, the directory used |
| 525 | for the temporary file is not specified in a system include |
| 526 | file (\f(CW\*(C`P_tmpdir\*(C'\fR) but simply depends on the choice of \fItmpdir()\fR |
| 527 | returned by File::Spec. On some implementations this |
| 528 | location can be set using the \f(CW\*(C`TMPDIR\*(C'\fR environment variable, which |
| 529 | may not be secure. |
| 530 | If this is a problem, simply use \fImkstemp()\fR and specify a template. |
| 531 | .IP "\fBtmpnam\fR" 4 |
| 532 | .IX Item "tmpnam" |
| 533 | When called in scalar context, returns the full name (including path) |
| 534 | of a temporary file (uses \fImktemp()\fR). The only check is that the file does |
| 535 | not already exist, but there is no guarantee that that condition will |
| 536 | continue to apply. |
| 537 | .Sp |
| 538 | .Vb 1 |
| 539 | \& $file = tmpnam(); |
| 540 | .Ve |
| 541 | .Sp |
| 542 | When called in list context, a filehandle to the open file and |
| 543 | a filename are returned. This is achieved by calling \fImkstemp()\fR |
| 544 | after constructing a suitable template. |
| 545 | .Sp |
| 546 | .Vb 1 |
| 547 | \& ($fh, $file) = tmpnam(); |
| 548 | .Ve |
| 549 | .Sp |
| 550 | If possible, this form should be used to prevent possible |
| 551 | race conditions. |
| 552 | .Sp |
| 553 | See \*(L"tmpdir\*(R" in File::Spec for information on the choice of temporary |
| 554 | directory for a particular operating system. |
| 555 | .IP "\fBtmpfile\fR" 4 |
| 556 | .IX Item "tmpfile" |
| 557 | Returns the filehandle of a temporary file. |
| 558 | .Sp |
| 559 | .Vb 1 |
| 560 | \& $fh = tmpfile(); |
| 561 | .Ve |
| 562 | .Sp |
| 563 | The file is removed when the filehandle is closed or when the program |
| 564 | exits. No access to the filename is provided. |
| 565 | .Sp |
| 566 | If the temporary file can not be created undef is returned. |
| 567 | Currently this command will probably not work when the temporary |
| 568 | directory is on an \s-1NFS\s0 file system. |
| 569 | .SH "ADDITIONAL FUNCTIONS" |
| 570 | .IX Header "ADDITIONAL FUNCTIONS" |
| 571 | These functions are provided for backwards compatibility |
| 572 | with common tempfile generation C library functions. |
| 573 | .PP |
| 574 | They are not exported and must be addressed using the full package |
| 575 | name. |
| 576 | .IP "\fBtempnam\fR" 4 |
| 577 | .IX Item "tempnam" |
| 578 | Return the name of a temporary file in the specified directory |
| 579 | using a prefix. The file is guaranteed not to exist at the time |
| 580 | the function was called, but such guarantees are good for one |
| 581 | clock tick only. Always use the proper form of \f(CW\*(C`sysopen\*(C'\fR |
| 582 | with \f(CW\*(C`O_CREAT | O_EXCL\*(C'\fR if you must open such a filename. |
| 583 | .Sp |
| 584 | .Vb 1 |
| 585 | \& $filename = File::Temp::tempnam( $dir, $prefix ); |
| 586 | .Ve |
| 587 | .Sp |
| 588 | Equivalent to running \fImktemp()\fR with \f(CW$dir\fR/$prefixXXXXXXXX |
| 589 | (using unix file convention as an example) |
| 590 | .Sp |
| 591 | Because this function uses \fImktemp()\fR, it can suffer from race conditions. |
| 592 | .SH "UTILITY FUNCTIONS" |
| 593 | .IX Header "UTILITY FUNCTIONS" |
| 594 | Useful functions for dealing with the filehandle and filename. |
| 595 | .IP "\fBunlink0\fR" 4 |
| 596 | .IX Item "unlink0" |
| 597 | Given an open filehandle and the associated filename, make a safe |
| 598 | unlink. This is achieved by first checking that the filename and |
| 599 | filehandle initially point to the same file and that the number of |
| 600 | links to the file is 1 (all fields returned by \fIstat()\fR are compared). |
| 601 | Then the filename is unlinked and the filehandle checked once again to |
| 602 | verify that the number of links on that file is now 0. This is the |
| 603 | closest you can come to making sure that the filename unlinked was the |
| 604 | same as the file whose descriptor you hold. |
| 605 | .Sp |
| 606 | .Vb 2 |
| 607 | \& unlink0($fh, $path) |
| 608 | \& or die "Error unlinking file $path safely"; |
| 609 | .Ve |
| 610 | .Sp |
| 611 | Returns false on error. The filehandle is not closed since on some |
| 612 | occasions this is not required. |
| 613 | .Sp |
| 614 | On some platforms, for example Windows \s-1NT\s0, it is not possible to |
| 615 | unlink an open file (the file must be closed first). On those |
| 616 | platforms, the actual unlinking is deferred until the program ends and |
| 617 | good status is returned. A check is still performed to make sure that |
| 618 | the filehandle and filename are pointing to the same thing (but not at |
| 619 | the time the end block is executed since the deferred removal may not |
| 620 | have access to the filehandle). |
| 621 | .Sp |
| 622 | Additionally, on Windows \s-1NT\s0 not all the fields returned by \fIstat()\fR can |
| 623 | be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be |
| 624 | different. Also, it seems that the size of the file returned by \fIstat()\fR |
| 625 | does not always agree, with \f(CW\*(C`stat(FH)\*(C'\fR being more accurate than |
| 626 | \&\f(CW\*(C`stat(filename)\*(C'\fR, presumably because of caching issues even when |
| 627 | using autoflush (this is usually overcome by waiting a while after |
| 628 | writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it). |
| 629 | .Sp |
| 630 | Finally, on \s-1NFS\s0 file systems the link count of the file handle does |
| 631 | not always go to zero immediately after unlinking. Currently, this |
| 632 | command is expected to fail on \s-1NFS\s0 disks. |
| 633 | .Sp |
| 634 | This function is disabled if the global variable \f(CW$KEEP_ALL\fR is true |
| 635 | and an unlink on open file is supported. If the unlink is to be deferred |
| 636 | to the \s-1END\s0 block, the file is still registered for removal. |
| 637 | .IP "\fBcmpstat\fR" 4 |
| 638 | .IX Item "cmpstat" |
| 639 | Compare \f(CW\*(C`stat\*(C'\fR of filehandle with \f(CW\*(C`stat\*(C'\fR of provided filename. This |
| 640 | can be used to check that the filename and filehandle initially point |
| 641 | to the same file and that the number of links to the file is 1 (all |
| 642 | fields returned by \fIstat()\fR are compared). |
| 643 | .Sp |
| 644 | .Vb 2 |
| 645 | \& cmpstat($fh, $path) |
| 646 | \& or die "Error comparing handle with file"; |
| 647 | .Ve |
| 648 | .Sp |
| 649 | Returns false if the stat information differs or if the link count is |
| 650 | greater than 1. |
| 651 | .Sp |
| 652 | On certain platofms, eg Windows, not all the fields returned by \fIstat()\fR |
| 653 | can be compared. For example, the \f(CW\*(C`dev\*(C'\fR and \f(CW\*(C`rdev\*(C'\fR fields seem to be |
| 654 | different in Windows. Also, it seems that the size of the file |
| 655 | returned by \fIstat()\fR does not always agree, with \f(CW\*(C`stat(FH)\*(C'\fR being more |
| 656 | accurate than \f(CW\*(C`stat(filename)\*(C'\fR, presumably because of caching issues |
| 657 | even when using autoflush (this is usually overcome by waiting a while |
| 658 | after writing to the tempfile before attempting to \f(CW\*(C`unlink0\*(C'\fR it). |
| 659 | .Sp |
| 660 | Not exported by default. |
| 661 | .IP "\fBunlink1\fR" 4 |
| 662 | .IX Item "unlink1" |
| 663 | Similar to \f(CW\*(C`unlink0\*(C'\fR except after file comparison using cmpstat, the |
| 664 | filehandle is closed prior to attempting to unlink the file. This |
| 665 | allows the file to be removed without using an \s-1END\s0 block, but does |
| 666 | mean that the post-unlink comparison of the filehandle state provided |
| 667 | by \f(CW\*(C`unlink0\*(C'\fR is not available. |
| 668 | .Sp |
| 669 | .Vb 2 |
| 670 | \& unlink1($fh, $path) |
| 671 | \& or die "Error closing and unlinking file"; |
| 672 | .Ve |
| 673 | .Sp |
| 674 | Usually called from the object destructor when using the \s-1OO\s0 interface. |
| 675 | .Sp |
| 676 | Not exported by default. |
| 677 | .Sp |
| 678 | This function is disabled if the global variable \f(CW$KEEP_ALL\fR is true. |
| 679 | .IP "\fBcleanup\fR" 4 |
| 680 | .IX Item "cleanup" |
| 681 | Calling this function will cause any temp files or temp directories |
| 682 | that are registered for removal to be removed. This happens automatically |
| 683 | when the process exits but can be triggered manually if the caller is sure |
| 684 | that none of the temp files are required. This method can be registered as |
| 685 | an Apache callback. |
| 686 | .Sp |
| 687 | On OSes where temp files are automatically removed when the temp file |
| 688 | is closed, calling this function will have no effect other than to remove |
| 689 | temporary directories (which may include temporary files). |
| 690 | .Sp |
| 691 | .Vb 1 |
| 692 | \& File::Temp::cleanup(); |
| 693 | .Ve |
| 694 | .Sp |
| 695 | Not exported by default. |
| 696 | .SH "PACKAGE VARIABLES" |
| 697 | .IX Header "PACKAGE VARIABLES" |
| 698 | These functions control the global state of the package. |
| 699 | .IP "\fBsafe_level\fR" 4 |
| 700 | .IX Item "safe_level" |
| 701 | Controls the lengths to which the module will go to check the safety of the |
| 702 | temporary file or directory before proceeding. |
| 703 | Options are: |
| 704 | .RS 4 |
| 705 | .IP "\s-1STANDARD\s0" 8 |
| 706 | .IX Item "STANDARD" |
| 707 | Do the basic security measures to ensure the directory exists and |
| 708 | is writable, that the \fIumask()\fR is fixed before opening of the file, |
| 709 | that temporary files are opened only if they do not already exist, and |
| 710 | that possible race conditions are avoided. Finally the unlink0 |
| 711 | function is used to remove files safely. |
| 712 | .IP "\s-1MEDIUM\s0" 8 |
| 713 | .IX Item "MEDIUM" |
| 714 | In addition to the \s-1STANDARD\s0 security, the output directory is checked |
| 715 | to make sure that it is owned either by root or the user running the |
| 716 | program. If the directory is writable by group or by other, it is then |
| 717 | checked to make sure that the sticky bit is set. |
| 718 | .Sp |
| 719 | Will not work on platforms that do not support the \f(CW\*(C`\-k\*(C'\fR test |
| 720 | for sticky bit. |
| 721 | .IP "\s-1HIGH\s0" 8 |
| 722 | .IX Item "HIGH" |
| 723 | In addition to the \s-1MEDIUM\s0 security checks, also check for the |
| 724 | possibility of ``\fIchown()\fR giveaway'' using the \s-1POSIX\s0 |
| 725 | \&\fIsysconf()\fR function. If this is a possibility, each directory in the |
| 726 | path is checked in turn for safeness, recursively walking back to the |
| 727 | root directory. |
| 728 | .Sp |
| 729 | For platforms that do not support the \s-1POSIX\s0 |
| 730 | \&\f(CW\*(C`_PC_CHOWN_RESTRICTED\*(C'\fR symbol (for example, Windows \s-1NT\s0) it is |
| 731 | assumed that ``\fIchown()\fR giveaway'' is possible and the recursive test |
| 732 | is performed. |
| 733 | .RE |
| 734 | .RS 4 |
| 735 | .Sp |
| 736 | The level can be changed as follows: |
| 737 | .Sp |
| 738 | .Vb 1 |
| 739 | \& File::Temp->safe_level( File::Temp::HIGH ); |
| 740 | .Ve |
| 741 | .Sp |
| 742 | The level constants are not exported by the module. |
| 743 | .Sp |
| 744 | Currently, you must be running at least perl v5.6.0 in order to |
| 745 | run with \s-1MEDIUM\s0 or \s-1HIGH\s0 security. This is simply because the |
| 746 | safety tests use functions from Fcntl that are not |
| 747 | available in older versions of perl. The problem is that the version |
| 748 | number for Fcntl is the same in perl 5.6.0 and in 5.005_03 even though |
| 749 | they are different versions. |
| 750 | .Sp |
| 751 | On systems that do not support the \s-1HIGH\s0 or \s-1MEDIUM\s0 safety levels |
| 752 | (for example Win \s-1NT\s0 or \s-1OS/2\s0) any attempt to change the level will |
| 753 | be ignored. The decision to ignore rather than raise an exception |
| 754 | allows portable programs to be written with high security in mind |
| 755 | for the systems that can support this without those programs failing |
| 756 | on systems where the extra tests are irrelevant. |
| 757 | .Sp |
| 758 | If you really need to see whether the change has been accepted |
| 759 | simply examine the return value of \f(CW\*(C`safe_level\*(C'\fR. |
| 760 | .Sp |
| 761 | .Vb 3 |
| 762 | \& $newlevel = File::Temp->safe_level( File::Temp::HIGH ); |
| 763 | \& die "Could not change to high security" |
| 764 | \& if $newlevel != File::Temp::HIGH; |
| 765 | .Ve |
| 766 | .RE |
| 767 | .IP "TopSystemUID" 4 |
| 768 | .IX Item "TopSystemUID" |
| 769 | This is the highest \s-1UID\s0 on the current system that refers to a root |
| 770 | \&\s-1UID\s0. This is used to make sure that the temporary directory is |
| 771 | 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 |
| 772 | simply by root. |
| 773 | .Sp |
| 774 | This is required since on many unix systems \f(CW\*(C`/tmp\*(C'\fR is not owned |
| 775 | by root. |
| 776 | .Sp |
| 777 | Default is to assume that any \s-1UID\s0 less than or equal to 10 is a root |
| 778 | \&\s-1UID\s0. |
| 779 | .Sp |
| 780 | .Vb 2 |
| 781 | \& File::Temp->top_system_uid(10); |
| 782 | \& my $topid = File::Temp->top_system_uid; |
| 783 | .Ve |
| 784 | .Sp |
| 785 | This value can be adjusted to reduce security checking if required. |
| 786 | The value is only relevant when \f(CW\*(C`safe_level\*(C'\fR is set to \s-1MEDIUM\s0 or higher. |
| 787 | .IP "\fB$KEEP_ALL\fR" 4 |
| 788 | .IX Item "$KEEP_ALL" |
| 789 | Controls whether temporary files and directories should be retained |
| 790 | regardless of any instructions in the program to remove them |
| 791 | automatically. This is useful for debugging but should not be used in |
| 792 | production code. |
| 793 | .Sp |
| 794 | .Vb 1 |
| 795 | \& $File::Temp::KEEP_ALL = 1; |
| 796 | .Ve |
| 797 | .Sp |
| 798 | Default is for files to be removed as requested by the caller. |
| 799 | .Sp |
| 800 | In some cases, files will only be retained if this variable is true |
| 801 | when the file is created. This means that you can not create a temporary |
| 802 | file, set this variable and expect the temp file to still be around |
| 803 | when the program exits. |
| 804 | .IP "\fB$DEBUG\fR" 4 |
| 805 | .IX Item "$DEBUG" |
| 806 | Controls whether debugging messages should be enabled. |
| 807 | .Sp |
| 808 | .Vb 1 |
| 809 | \& $File::Temp::DEBUG = 1; |
| 810 | .Ve |
| 811 | .Sp |
| 812 | Default is for debugging mode to be disabled. |
| 813 | .SH "WARNING" |
| 814 | .IX Header "WARNING" |
| 815 | For maximum security, endeavour always to avoid ever looking at, |
| 816 | touching, or even imputing the existence of the filename. You do not |
| 817 | know that that filename is connected to the same file as the handle |
| 818 | you have, and attempts to check this can only trigger more race |
| 819 | conditions. It's far more secure to use the filehandle alone and |
| 820 | dispense with the filename altogether. |
| 821 | .PP |
| 822 | If you need to pass the handle to something that expects a filename |
| 823 | then, on a unix system, use \f(CW\*(C`"/dev/fd/" . fileno($fh)\*(C'\fR for arbitrary |
| 824 | programs, or more generally \f(CW\*(C`"+<=&" . fileno($fh)\*(C'\fR for Perl |
| 825 | programs. You will have to clear the close-on-exec bit on that file |
| 826 | descriptor before passing it to another process. |
| 827 | .PP |
| 828 | .Vb 3 |
| 829 | \& use Fcntl qw/F_SETFD F_GETFD/; |
| 830 | \& fcntl($tmpfh, F_SETFD, 0) |
| 831 | \& or die "Can't clear close-on-exec flag on temp fh: $!\en"; |
| 832 | .Ve |
| 833 | .Sh "Temporary files and \s-1NFS\s0" |
| 834 | .IX Subsection "Temporary files and NFS" |
| 835 | Some problems are associated with using temporary files that reside |
| 836 | on \s-1NFS\s0 file systems and it is recommended that a local filesystem |
| 837 | is used whenever possible. Some of the security tests will most probably |
| 838 | fail when the temp file is not local. Additionally, be aware that |
| 839 | the performance of I/O operations over \s-1NFS\s0 will not be as good as for |
| 840 | a local disk. |
| 841 | .Sh "Forking" |
| 842 | .IX Subsection "Forking" |
| 843 | In some cases files created by File::Temp are removed from within an |
| 844 | \&\s-1END\s0 block. Since \s-1END\s0 blocks are triggered when a child process exits |
| 845 | (unless \f(CW\*(C`POSIX::_exit()\*(C'\fR is used by the child) File::Temp takes care |
| 846 | to only remove those temp files created by a particular process \s-1ID\s0. This |
| 847 | means that a child will not attempt to remove temp files created by the |
| 848 | parent process. |
| 849 | .Sh "\s-1BINMODE\s0" |
| 850 | .IX Subsection "BINMODE" |
| 851 | The file returned by File::Temp will have been opened in binary mode |
| 852 | if such a mode is available. If that is not correct, use the \fIbinmode()\fR |
| 853 | function to change the mode of the filehandle. |
| 854 | .SH "HISTORY" |
| 855 | .IX Header "HISTORY" |
| 856 | Originally began life in May 1999 as an \s-1XS\s0 interface to the system |
| 857 | \&\fImkstemp()\fR function. In March 2000, the OpenBSD \fImkstemp()\fR code was |
| 858 | translated to Perl for total control of the code's |
| 859 | security checking, to ensure the presence of the function regardless of |
| 860 | operating system and to help with portability. The module was shipped |
| 861 | as a standard part of perl from v5.6.1. |
| 862 | .SH "SEE ALSO" |
| 863 | .IX Header "SEE ALSO" |
| 864 | \&\*(L"tmpnam\*(R" in \s-1POSIX\s0, \*(L"tmpfile\*(R" in \s-1POSIX\s0, File::Spec, File::Path |
| 865 | .PP |
| 866 | See IO::File and File::MkTemp, Apachae::TempFile for |
| 867 | different implementations of temporary file handling. |
| 868 | .SH "AUTHOR" |
| 869 | .IX Header "AUTHOR" |
| 870 | Tim Jenness <tjenness@cpan.org> |
| 871 | .PP |
| 872 | Copyright (C) 1999\-2005 Tim Jenness and the \s-1UK\s0 Particle Physics and |
| 873 | Astronomy Research Council. All Rights Reserved. This program is free |
| 874 | software; you can redistribute it and/or modify it under the same |
| 875 | terms as Perl itself. |
| 876 | .PP |
| 877 | Original Perl implementation loosely based on the OpenBSD C code for |
| 878 | \&\fImkstemp()\fR. Thanks to Tom Christiansen for suggesting that this module |
| 879 | should be written and providing ideas for code improvements and |
| 880 | security enhancements. |