raw/man1/mktemp.1

   1 .\"     $Id: mktemp.1,v 1.1 2003/12/20 03:31:53 bbbush Exp $
   2 .\"
   3 .\" Copyright (c) 1996, 2000, 2001 Todd C. Miller <Todd.Miller@courtesan.com>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. The name of the author may not be used to endorse or promote products
  15 .\"    derived from this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  19 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
  20 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  21 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  23 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  25 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  26 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .TH MKTEMP 1 "30 September 2001"
  29 .SH NAME
  30 \fBmktemp\fP \- make temporary filename (unique)
  31 .SH SYNOPSIS
  32 \fBmktemp\fP [\fB\-V\fP] | [\fB\-dqtu\fP] [\fB\-p\fP \fIdirectory\fP] [\fItemplate\fP]
  33 .SH DESCRIPTION
  34 The
  35 .B mktemp
  36 utility takes the given filename
  37 .I template
  38 and overwrites a portion of it to create a unique filename.
  39 The
  40 .I template
  41 may be any filename with some number of
  42 `Xs' appended to it, for example
  43 .I /tmp/tfile.XXXXXXXXXX.
  44 If no
  45 .I template
  46 is specified a default of
  47 .I tmp.XXXXXXXXXX
  48 is used and the
  49 .B \-t
  50 flag is implied (see below).
  51 .PP
  52 The trailing `Xs' are replaced with a combination
  53 of the current process number and random letters.
  54 The name chosen depends both on the number of `Xs' in the
  55 .I template
  56 and the number of collisions with pre\-existing files.
  57 The number of unique filenames
  58 .B mktemp
  59 can return depends on the number of
  60 `Xs' provided; ten `Xs' will result in
  61 .B mktemp
  62 testing roughly 26 ** 10 combinations.
  63 .PP
  64 If
  65 .B mktemp
  66 can successfully generate a unique filename, the file (or directory)
  67 is created with file permissions such that it is only readable and writable
  68 by its owner (unless the
  69 .B \-u
  70 flag is given) and the filename is printed to standard output.
  71 .PP
  72 .B mktemp
  73 is provided to allow shell scripts to safely use temporary
  74 files.  Traditionally, many shell scripts take the name of the program with
  75 the PID as a suffix and use that as a temporary filename.
  76 This kind of naming scheme is predictable and the race condition it creates
  77 is easy for an attacker to win.
  78 A safer, though still inferior approach
  79 is to make a temporary directory using the same naming scheme.
  80 While this does allow one to guarantee that a temporary file will not be
  81 subverted, it still allows a simple denial of service attack.
  82 For these reasons it is suggested that
  83 .B mktemp
  84 be used instead.
  85 .PP
  86 The options are as follows:
  87 .TP
  88 .B \-V
  89 Print the version and exit.
  90 .TP
  91 .B \-d
  92 Make a directory instead of a file.
  93 .TP
  94 .BI "\-p " directory
  95 Use the specified
  96 .I directory
  97 as a prefix when generating the temporary filename.
  98 The
  99 .I directory
 100 will be overridden by the user's
 101 .SM TMPDIR
 102 environment variable if it is set.
 103 This option implies the
 104 .B \-t
 105 flag (see below).
 106 .TP
 107 .B \-q
 108 Fail silently if an error occurs.
 109 This is useful if
 110 a script does not want error output to go to standard error.
 111 .TP
 112 .B \-t
 113 Generate a path rooted in a temporary directory.
 114 This directory is chosen as follows:
 115 .RS
 116 .IP \(bu
 117 If the user's
 118 .SM TMPDIR
 119 environment variable is set, the directory contained therein is used.
 120 .IP \(bu
 121 Otherwise, if the
 122 .B \-p
 123 flag was given the specified directory is used.
 124 .IP \(bu
 125 If none of the above apply,
 126 .I /tmp
 127 is used.
 128 .RE
 129 .PP
 130 In this mode, the
 131 .I template
 132 (if specified) should be a directory component (as opposed to a full path)
 133 and thus should not contain any forward slashes.
 134 .TP
 135 .B \-u
 136 Operate in ``unsafe'' mode.
 137 The temp file will be unlinked before
 138 .B mktemp
 139 exits.  This is slightly better than mktemp(3)
 140 but still introduces a race condition.  Use of this
 141 option is not encouraged.
 142 .PP
 143 The
 144 .B mktemp
 145 utility
 146 exits with a value of 0 on success or 1 on failure.
 147 .SH EXAMPLES
 148 The following sh(1)
 149 fragment illustrates a simple use of
 150 .B mktemp
 151 where the script should quit if it cannot get a safe
 152 temporary file.
 153 .RS
 154 .nf
 155
 156 TMPFILE=`mktemp /tmp/example.XXXXXXXXXX` || exit 1
 157 echo "program output" >> $TMPFILE
 158
 159 .fi
 160 .RE
 161 The same fragment with support for a user's
 162 .SM TMPDIR
 163 environment variable can be written as follows.
 164 .RS
 165 .nf
 166
 167 TMPFILE=`mktemp \-t example.XXXXXXXXXX` || exit 1
 168 echo "program output" >> $TMPFILE
 169
 170 .fi
 171 .RE
 172 This can be further simplified if we don't care about the actual name of
 173 the temporary file.  In this case the
 174 .B \-t
 175 flag is implied.
 176 .RS
 177 .nf
 178
 179 TMPFILE=`mktemp` || exit 1
 180 echo "program output" >> $TMPFILE
 181
 182 .fi
 183 .RE
 184 In some cases, it may be desirable to use a default temporary directory
 185 other than
 186 .I /tmp.
 187 In this example the temporary file will be created in
 188 .I /extra/tmp
 189 unless the user's
 190 .SM TMPDIR
 191 environment variable specifies otherwise.
 192 .RS
 193 .nf
 194
 195 TMPFILE=`mktemp \-p /extra/tmp example.XXXXXXXXXX` || exit 1
 196 echo "program output" >> $TMPFILE
 197
 198 .fi
 199 .RE
 200 In some cases, we want the script to catch the error.
 201 For instance, if we attempt to create two temporary files and
 202 the second one fails we need to remove the first before exiting.
 203 .RS
 204 .nf
 205
 206 TMP1=`mktemp \-t example.1.XXXXXXXXXX` || exit 1
 207 TMP2=`mktemp \-t example.2.XXXXXXXXXX`
 208 if [ $? \-ne 0 ]; then
 209         rm \-f $TMP1
 210         exit 1
 211 fi
 212
 213 .fi
 214 .RE
 215 Or perhaps you don't want to exit if
 216 .B mktemp
 217 is unable to create the file.
 218 In this case you can protect that part of the script thusly.
 219 .RS
 220 .nf
 221
 222 TMPFILE=`mktemp \-t example.XXXXXXXXXX` && {
 223         # Safe to use $TMPFILE in this block
 224         echo data > $TMPFILE
 225         ...
 226         rm \-f $TMPFILE
 227 }
 228
 229 .fi
 230 .RE
 231 .SH ENVIRONMENT
 232 .IP TMPDIR 8
 233 directory in which to place the temporary file when in
 234 .B \-t
 235 mode
 236 .SH SEE ALSO
 237 .BR mkdtemp (3),
 238 .BR mkstemp (3),
 239 .BR mktemp (3)
 240 .SH HISTORY
 241 The
 242 .B mktemp
 243 utility appeared in OpenBSD 2.1.