Doc/lib/libtempfile.tex

   1 \section{\module{tempfile} ---
   2          Generate temporary file names.}
   3 \declaremodule{standard}{tempfile}
   4
   5 \modulesynopsis{Generate temporary file names.}
   6
   7 \indexii{temporary}{file name}
   8 \indexii{temporary}{file}
   9
  10
  11 This module generates temporary file names.  It is not \UNIX{} specific,
  12 but it may require some help on non-\UNIX{} systems.
  13
  14 Note: the modules does not create temporary files, nor does it
  15 automatically remove them when the current process exits or dies.
  16
  17 The module defines a single user-callable function:
  18
  19 \begin{funcdesc}{mktemp}{}
  20 Return a unique temporary filename.  This is an absolute pathname of a
  21 file that does not exist at the time the call is made.  No two calls
  22 will return the same filename.
  23 \end{funcdesc}
  24
  25 The module uses two global variables that tell it how to construct a
  26 temporary name.  The caller may assign values to them; by default they
  27 are initialized at the first call to \function{mktemp()}.
  28
  29 \begin{datadesc}{tempdir}
  30 When set to a value other than \code{None}, this variable defines the
  31 directory in which filenames returned by \function{mktemp()} reside.
  32 The default is taken from the environment variable \envvar{TMPDIR}; if
  33 this is not set, either \file{/usr/tmp} is used (on \UNIX{}), or the
  34 current working directory (all other systems).  No check is made to
  35 see whether its value is valid.
  36 \end{datadesc}
  37
  38 \begin{datadesc}{template}
  39 When set to a value other than \code{None}, this variable defines the
  40 prefix of the final component of the filenames returned by
  41 \function{mktemp()}.  A string of decimal digits is added to generate
  42 unique filenames.  The default is either \file{@\var{pid}.} where
  43 \var{pid} is the current process ID (on \UNIX{}), or \file{tmp} (all
  44 other systems).
  45 \end{datadesc}
  46
  47 \strong{Warning:} if a \UNIX{} process uses \code{mktemp()}, then
  48 calls \function{fork()} and both parent and child continue to use
  49 \function{mktemp()}, the processes will generate conflicting temporary
  50 names.  To resolve this, the child process should assign \code{None}
  51 to \code{template}, to force recomputing the default on the next call
  52 to \function{mktemp()}.