usr.bin/mktemp/mktemp.1

   1 .\" $NetBSD: mktemp.1,v 1.18 2009/08/15 20:02:28 christos Exp $
   2 .\" From: $FreeBSD: src/usr.bin/mktemp/mktemp.1,v 1.5 1999/08/28 01:04:13 peter Exp $
   3 .\" From: $OpenBSD: mktemp.1,v 1.8 1998/03/19 06:13:37 millert Exp $
   4 .\"
   5 .\" Copyright (c) 1989, 1991, 1993
   6 .\"     The Regents of the University of California.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD: src/usr.bin/mktemp/mktemp.1,v 1.5 1999/08/28 01:04:13 peter Exp $
  33 .\"
  34 .Dd August 15, 2009
  35 .Dt MKTEMP 1
  36 .Os
  37 .Sh NAME
  38 .Nm mktemp
  39 .Nd make temporary file name (unique)
  40 .Sh SYNOPSIS
  41 .Nm mktemp
  42 .Op Fl dqu
  43 .Op Fl p Ar tmpdir
  44 .Bro
  45 .Fl t Ar prefix
  46 .No |
  47 .Ar template ...
  48 .Brc
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility takes each of the given file name templates and overwrites a
  53 portion of it to create a file name.
  54 This file name is unique and suitable for use by the application.
  55 The template may be any file name with some number of
  56 .Ql X Ns s
  57 appended to it, for example
  58 .Pa /tmp/temp.XXXX .
  59 The trailing
  60 .Ql X Ns s
  61 are replaced with the current process number and/or a
  62 unique letter combination.
  63 The number of unique file names
  64 .Nm
  65 can return depends on the number of
  66 .Ql X Ns s
  67 provided; six
  68 .Ql X Ns s
  69 will result in
  70 .Nm
  71 testing roughly 26 ** 6 combinations.
  72 .Pp
  73 If
  74 .Nm
  75 can successfully generate a unique file name, the file
  76 is created with mode 0600 (unless the
  77 .Fl u
  78 flag is given) and the filename is printed to standard output.
  79 .Pp
  80 If the
  81 .Fl t Ar prefix
  82 option is given,
  83 .Nm
  84 will generate a template string based on the
  85 .Ar prefix
  86 and the
  87 .Ev TMPDIR
  88 environment variable, if set.
  89 The default location if
  90 .Ev TMPDIR
  91 is not set is
  92 .Pa /tmp .
  93 The default location of the temporary directory can be overridden with the
  94 .Fl p Ar tmpdir
  95 option.
  96 The template string created will consist of the
  97 .Ar prefix
  98 followed by a
  99 .So . Sc
 100 and an eight character unique letter combination.
 101 .Ql X Ns s
 102 in the
 103 .Ar prefix
 104 string will be treated as literal.
 105 If an additional
 106 .Ar template
 107 argument is passed, a second file will be created.
 108 Care should be taken to ensure that it is appropriate to use an
 109 environment variable potentially supplied by the user.
 110 .Pp
 111 Any number of temporary files may be created in a single invocation
 112 using multiple
 113 .Ar template
 114 arguments, also a single one based on the internal template with the
 115 .Fl t
 116 option value as filename prefix.
 117 .Pp
 118 At least one
 119 .Ar template
 120 argument or the
 121 .Fl t
 122 option must be present.
 123 .Pp
 124 .Nm
 125 is provided to allow shell scripts to safely use temporary files.
 126 Traditionally, many shell scripts take the name of the program with
 127 the pid as a suffix and use that as a temporary file name.
 128 This kind of naming scheme is predictable and the race condition
 129 it creates is easy for an attacker to win.
 130 A safer, though still inferior, approach
 131 is to make a temporary directory using the same naming scheme.
 132 While this does allow one to guarantee that a temporary file will
 133 not be subverted, it still allows a simple denial of service attack.
 134 For these reasons it is suggested that
 135 .Nm
 136 be used instead.
 137 .Sh OPTIONS
 138 The available options are as follows:
 139 .Bl -tag -width indent
 140 .It Fl d
 141 Make a directory instead of a file.
 142 .It Fl q
 143 Fail silently if an error occurs.
 144 This is useful if
 145 a script does not want error output to go to standard error.
 146 .It Fl t Ar prefix
 147 Generate a template (using the supplied
 148 .Ar prefix
 149 and
 150 .Ev TMPDIR
 151 if set) to create a filename template.
 152 If
 153 .Fl t Ar prefix
 154 and
 155 .Ar template
 156 are both given,
 157 .Ar prefix
 158 will not apply to
 159 .Ar template .
 160 .It Fl u
 161 Operate in
 162 .Dq unsafe
 163 mode.
 164 The temp file will be unlinked before
 165 .Nm
 166 exits.
 167 This is slightly better than
 168 .Xr mktemp 3
 169 but still introduces a race condition.
 170 Use of this option is not encouraged.
 171 .El
 172 .Sh EXIT STATUS
 173 The
 174 .Nm
 175 utility exits with a value of 0 on success, and 1 on any failure.
 176 .Sh EXAMPLES
 177 The following
 178 .Xr sh 1
 179 fragment illustrates a simple use of
 180 .Nm
 181 where the script should quit if it cannot get a safe
 182 temporary file.
 183 .Bd -literal -offset indent
 184 TMPFILE=`mktemp /tmp/${0##*/}.XXXXXX` || exit 1
 185 echo "program output" \*[Gt]\*[Gt] $TMPFILE
 186 .Ed
 187 .Pp
 188 To allow the use of $TMPDIR:
 189 .Bd -literal -offset indent
 190 TMPFILE=`mktemp -t ${0##*/}` || exit 1
 191 echo "program output" \*[Gt]\*[Gt] $TMPFILE
 192 .Ed
 193 .Pp
 194 In this case, we want the script to catch the error itself.
 195 .Bd -literal -offset indent
 196 TMPFILE=`mktemp -q /tmp/${0##*/}.XXXXXX`
 197 if [ $? -ne 0 ]; then
 198         echo "$0: Can't create temp file, exiting..."
 199         exit 1
 200 fi
 201 .Ed
 202 .Sh SEE ALSO
 203 .Xr mkdtemp 3 ,
 204 .Xr mkstemp 3 ,
 205 .Xr mktemp 3 ,
 206 .Xr environ 7
 207 .Sh HISTORY
 208 The
 209 .Nm
 210 utility appeared in
 211 .Nx 1.5 .
 212 It has been imported from
 213 .Fx ,
 214 the idea and the manual page were taken from
 215 .Ox .