Doc/lib/libtempfile.tex

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