usr.bin/mktemp/mktemp.1

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. 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 .\" From: $OpenBSD: mktemp.1,v 1.8 1998/03/19 06:13:37 millert Exp $
  33 .\" $FreeBSD: src/usr.bin/mktemp/mktemp.1,v 1.7.2.8 2003/02/24 22:37:42 trhodes Exp $
  34 .\" $DragonFly: src/usr.bin/mktemp/mktemp.1,v 1.3 2004/03/11 12:28:58 hmp Exp $
  35 .\"
  36 .Dd November 20, 1996
  37 .Dt MKTEMP 1
  38 .Os
  39 .Sh NAME
  40 .Nm mktemp
  41 .Nd make temporary file name (unique)
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl d
  45 .Op Fl q
  46 .Op Fl t Ar prefix
  47 .Op Fl u
  48 .Ar template ...
  49 .Nm
  50 .Op Fl d
  51 .Op Fl q
  52 .Op Fl u
  53 .Fl t Ar prefix
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 utility takes each of the given file name templates and overwrites a
  58 portion of it to create a file name.  This file name is unique
  59 and suitable for use by the application.  The template may be
  60 any file name with some number of
  61 .Ql X Ns s
  62 appended
  63 to it, for example
  64 .Pa /tmp/temp.XXXX .
  65 The trailing
  66 .Ql X Ns s
  67 are replaced with the current process number and/or a
  68 unique letter combination.
  69 The number of unique file names
  70 .Nm
  71 can return depends on the number of
  72 .Ql X Ns s
  73 provided; six
  74 .Ql X Ns s
  75 will
  76 result in
  77 .Nm
  78 testing roughly 26 ** 6 combinations.
  79 .Pp
  80 If
  81 .Nm
  82 can successfully generate a unique file name, the file
  83 is created with mode 0600 (unless the
  84 .Fl u
  85 flag is given) and the filename is printed
  86 to standard output.
  87 .Pp
  88 If the
  89 .Fl t Ar prefix
  90 option is given,
  91 .Nm
  92 will generate a template string based on the
  93 .Ar prefix
  94 and the
  95 .Ev TMPDIR
  96 environment variable if set.
  97 The default location if
  98 .Ev TMPDIR
  99 is not set is
 100 .Pa /tmp .
 101 Care should
 102 be taken to ensure that it is appropriate to use an environment variable
 103 potentially supplied by the user.
 104 .Pp
 105 Any number of temporary files may be created in a single invocation,
 106 including one based on the internal template resulting from the
 107 .Fl t
 108 flag.
 109 .Pp
 110 The
 111 .Nm
 112 utility is provided to allow shell scripts to safely use temporary files.
 113 Traditionally, many shell scripts take the name of the program with
 114 the pid as a suffix and use that as a temporary file name.  This
 115 kind of naming scheme is predictable and the race condition it creates
 116 is easy for an attacker to win.  A safer, though still inferior, approach
 117 is to make a temporary directory using the same naming scheme.  While
 118 this does allow one to guarantee that a temporary file will not be
 119 subverted, it still allows a simple denial of service attack.  For these
 120 reasons it is suggested that
 121 .Nm
 122 be used instead.
 123 .Sh OPTIONS
 124 The available options are as follows:
 125 .Bl -tag -width indent
 126 .It Fl d
 127 Make a directory instead of a file.
 128 .It Fl q
 129 Fail silently if an error occurs.  This is useful if
 130 a script does not want error output to go to standard error.
 131 .It Fl t Ar prefix
 132 Generate a template (using the supplied
 133 .Ar prefix
 134 and
 135 .Ev TMPDIR
 136 if set) to create a filename template.
 137 .It Fl u
 138 Operate in
 139 .Dq unsafe
 140 mode.  The temp file will be unlinked before
 141 .Nm
 142 exits.  This is slightly better than
 143 .Xr mktemp 3
 144 but still introduces a race condition.  Use of this
 145 option is not encouraged.
 146 .El
 147 .Sh DIAGNOSTICS
 148 The
 149 .Nm
 150 utility
 151 exits 0 on success, and 1 if an error occurs.
 152 .Sh EXAMPLES
 153 The following
 154 .Xr sh 1
 155 fragment illustrates a simple use of
 156 .Nm
 157 where the script should quit if it cannot get a safe
 158 temporary file.
 159 .Bd -literal -offset indent
 160 tempfoo=`basename $0`
 161 TMPFILE=`mktemp /tmp/${tempfoo}.XXXXXX` || exit 1
 162 echo "program output" >> $TMPFILE
 163 .Ed
 164 .Pp
 165 To allow the use of $TMPDIR:
 166 .Bd -literal -offset indent
 167 tempfoo=`basename $0`
 168 TMPFILE=`mktemp -t ${tempfoo}` || exit 1
 169 echo "program output" >> $TMPFILE
 170 .Ed
 171 .Pp
 172 In this case, we want the script to catch the error itself.
 173 .Bd -literal -offset indent
 174 tempfoo=`basename $0`
 175 TMPFILE=`mktemp -q /tmp/${tempfoo}.XXXXXX`
 176 if [ $? -ne 0 ]; then
 177         echo "$0: Can't create temp file, exiting..."
 178         exit 1
 179 fi
 180 .Ed
 181 .Sh SEE ALSO
 182 .Xr mkdtemp 3 ,
 183 .Xr mkstemp 3 ,
 184 .Xr mktemp 3 ,
 185 .Xr environ 7
 186 .Sh HISTORY
 187 A
 188 .Nm
 189 utility appeared in
 190 .Ox 2.1 .
 191 This implementation was written independently based on the
 192 .Ox
 193 man page, and
 194 first appeared in
 195 .Fx 2.2.7 .
 196 This man page is taken from
 197 .Ox .