usr/src/man/man1/mktemp.1

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MKTEMP 1 "Jan 10, 2008"
   7 .SH NAME
   8 mktemp \- make temporary filename
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBmktemp\fR [\fB-dtqu\fR] [\fB-p\fR \fIdirectory\fR] [\fItemplate\fR]
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBmktemp\fR utility makes a temporary filename. To do this, \fBmktemp\fR
  19 takes the specified filename template and overwrites a portion of it to create
  20 a unique filename. See \fBOPERANDS\fR.
  21 .sp
  22 .LP
  23 The template is passed to \fBmkdtemp\fR(3C) for directories or
  24 \fBmkstemp\fR(3C) for ordinary files.
  25 .sp
  26 .LP
  27 If \fBmktemp\fR can successfully generate a unique filename, the file (or
  28 directory) is created with file permissions such that it is only readable and
  29 writable by its owner (unless the \fB-u\fR flag is given) and the filename is
  30 printed to standard output.
  31 .sp
  32 .LP
  33 \fBmktemp\fR allows shell scripts to safely use temporary files. Traditionally,
  34 many shell scripts take the name of the program with the \fBPID\fR as a suffix
  35 and used that as a temporary filename. This kind of naming scheme is
  36 predictable and the race condition it creates is easy for an attacker to win. A
  37 safer, though still inferior approach is to make a temporary directory using
  38 the same naming scheme. While this guarantees that a temporary file is not
  39 subverted, it still allows a simple denial of service attack. Use \fBmktemp\fR
  40 instead.
  41 .SH OPTIONS
  42 .sp
  43 .LP
  44 The following options are supported:
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fB-d\fR\fR
  49 .ad
  50 .RS 16n
  51 Make a directory instead of a file.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fB-p\fR \fIdirectory\fR\fR
  58 .ad
  59 .RS 16n
  60 Use the specified directory as a prefix when generating the temporary filename.
  61 The directory is overridden by the user's TMPDIR environment variable if it is
  62 set. This option implies the \fB-t\fR flag.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fB-q\fR\fR
  69 .ad
  70 .RS 16n
  71 Fail silently if an error occurs. This is useful if a script does not want
  72 error output to go to standard error.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fB-t\fR\fR
  79 .ad
  80 .RS 16n
  81 Generate a path rooted in a temporary directory. This directory is chosen as
  82 follows: If the user's TMPDIR environment variable is set, the directory
  83 contained therein is used. Otherwise, if the \fB-p\fR flag was given the
  84 specified directory is used. If none of the above apply, \fB/tmp\fR is used. In
  85 this mode, the template (if specified) should be a directory component (as
  86 opposed to a full path) and thus should not contain any forward slashes.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB-u\fR\fR
  93 .ad
  94 .RS 16n
  95 Operate in unsafe mode. The temp file is unlinked before \fBmktemp\fR exits.
  96 This is slightly better than \fBmktemp\fR(3C), but still introduces a race
  97 condition. Use of this option is discouraged.
  98 .RE
  99
 100 .SH OPERANDS
 101 .sp
 102 .LP
 103 The following operands are supported:
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fItemplate\fR\fR
 108 .ad
 109 .RS 12n
 110 \fItemplate\fR can be any filename with one or more \fBX\fRs appended to it,
 111 for example \fB/tmp/tfile.XXXXXX\fR.
 112 .sp
 113 If \fItemplate\fR is not specified, a default of \fBtmp.XXXXXX\fR is used and
 114 the \fB-t\fR flag is implied.
 115 .RE
 116
 117 .SH EXAMPLES
 118 .LP
 119 \fBExample 1 \fRUsing \fBmktemp\fR
 120 .sp
 121 .LP
 122 The following example illustrates a simple use of \fBmktemp\fR in a \fBsh\fR(1)
 123 script. In this example, the script quits if it cannot get a safe temporary
 124 file.
 125
 126 .sp
 127 .in +2
 128 .nf
 129 TMPFILE=`mktemp /tmp/example.XXXXXX`
 130 if [ -z "$TMPFILE" ]; then exit 1; fi
 131 echo "program output" >> $TMPFILE
 132 .fi
 133 .in -2
 134 .sp
 135
 136 .LP
 137 \fBExample 2 \fRUsing \fBmktemp\fR to Support \fBTMPDIR\fR
 138 .sp
 139 .LP
 140 The following example uses \fBmktemp\fR to support for a user's \fBTMPDIR\fR
 141 environment variable:
 142
 143 .sp
 144 .in +2
 145 .nf
 146 TMPFILE=`mktemp -t example.XXXXXX`
 147 if [ -z "$TMPFILE" ]; then exit 1; fi
 148 echo "program output" >> $TMPFILE
 149 .fi
 150 .in -2
 151 .sp
 152
 153 .LP
 154 \fBExample 3 \fRUsing \fBmktemp\fR Without Specifying the Name of the Temporary
 155 File
 156 .sp
 157 .LP
 158 The following example uses \fBmktemp\fR without specifying the name of the
 159 temporary file. In this case the \fB-t\fR flag is implied.
 160
 161 .sp
 162 .in +2
 163 .nf
 164 TMPFILE=`mktemp`
 165 if [ -z "$TMPFILE" ]; then exit 1; fi
 166 echo "program output" >> $TMPFILE
 167 .fi
 168 .in -2
 169 .sp
 170
 171 .LP
 172 \fBExample 4 \fRUsing \fBmktemp\fR with a Default Temporary Directory Other
 173 than \fB/tmp\fR
 174 .sp
 175 .LP
 176 The following example creates the temporary file in \fB/extra/tmp\fR unless the
 177 user's \fBTMPDIR\fR environment variable specifies otherwise:
 178
 179 .sp
 180 .in +2
 181 .nf
 182 TMPFILE=`mktemp -p /extra/tmp example.XXXXX`
 183 if [ -z "$TMPFILE" ]; then exit 1; fi
 184 echo "program output" >> $TMPFILE
 185 .fi
 186 .in -2
 187 .sp
 188
 189 .LP
 190 \fBExample 5 \fRUsing \fBmktemp\fR to Remove a File
 191 .sp
 192 .LP
 193 The following example attempts to create two temporary files. If creation of
 194 the second temporary file fails, \fBmktemp\fR removes the first file before
 195 exiting:
 196
 197 .sp
 198 .in +2
 199 .nf
 200 TMP1=`mktemp -t example.1.XXXXXX`
 201 if [ -z "$TMP1" ]; then exit 1; fi
 202 TMP2=`mktemp -t example.2.XXXXXX`
 203 if [ -z "$TMP2" ]; then
 204         rm -f $TMP1
 205         exit 1
 206 fi
 207 .fi
 208 .in -2
 209 .sp
 210
 211 .LP
 212 \fBExample 6 \fRUsing \fBmktemp\fR
 213 .sp
 214 .LP
 215 The following example does not exit if \fBmktemp\fR is unable to create the
 216 file. That part of the script has been protected.
 217
 218 .sp
 219 .in +2
 220 .nf
 221 TMPFILE=`mktemp -q -t example.XXXXXX`
 222 if [ ! -z "$TMPFILE" ]
 223 then
 224         # Safe to use $TMPFILE in this block
 225         echo data > $TMPFILE
 226         ...
 227         rm -f $TMPFILE
 228 fi
 229 .fi
 230 .in -2
 231 .sp
 232
 233 .SH ENVIRONMENT VARIABLES
 234 .sp
 235 .LP
 236 See \fBenviron\fR(5) for descriptions of the following environment variables
 237 that affect the execution of \fBmktemp\fR with the \fB-t\fR option:
 238 \fBTMPDIR.\fR
 239 .SH EXIT STATUS
 240 .sp
 241 .LP
 242 The following exit values are returned:
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fB0\fR\fR
 247 .ad
 248 .RS 5n
 249 Successful completion.
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fB1\fR\fR
 256 .ad
 257 .RS 5n
 258 An error occurred.
 259 .RE
 260
 261 .SH ATTRIBUTES
 262 .sp
 263 .LP
 264 See \fBattributes\fR(5) for descriptions of the following attributes:
 265 .sp
 266
 267 .sp
 268 .TS
 269 box;
 270 c | c
 271 l | l .
 272 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 273 _
 274 Interface Stability     Committed
 275 .TE
 276
 277 .SH SEE ALSO
 278 .sp
 279 .LP
 280 \fBsh\fR(1), \fBmkdtemp\fR(3C), \fBmkstemp\fR(3C), \fBattributes\fR(5),
 281 \fBenviron\fR(5)
 282 .SH NOTES
 283 .sp
 284 .LP
 285 The \fBmktemp\fR utility appeared in OpenBSD 2.1. The Solaris implementation
 286 uses only as many `Xs' as are significant for \fBmktemp\fR(3C) and
 287 \fBmkstemp\fR(3C).