Annotation of src/usr.bin/mktemp/mktemp.1, Revision 1.19
1.19 ! millert 1: .\" $OpenBSD: mktemp.1,v 1.18 2000/11/09 17:52:25 aaron Exp $
1.1 millert 2: .\"
1.19 ! millert 3: .\" Copyright (c) 1996, 2000, 2001 Todd C. Miller <Todd.Miller@courtesan.com>
1.13 millert 4: .\" All rights reserved.
1.1 millert 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.
1.13 millert 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.
1.1 millert 16: .\"
1.13 millert 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.
1.1 millert 27: .\"
1.19 ! millert 28: .Dd September 30, 2001
1.1 millert 29: .Dt MKTEMP 1
30: .Os
31: .Sh NAME
32: .Nm mktemp
33: .Nd make temporary file name (unique)
34: .Sh SYNOPSIS
35: .Nm mktemp
1.19 ! millert 36: .Op Fl dqtu
! 37: .Op Fl p Ar directory
1.1 millert 38: .Ar template
39: .Sh DESCRIPTION
40: The
41: .Nm mktemp
42: utility takes the given file name template and overwrites a
1.15 aaron 43: portion of it to create a unique file name.
44: The template may be any file name with some number of
1.1 millert 45: .Ql X Ns s
46: appended
47: to it, for example
1.12 millert 48: .Pa /tmp/temp.XXXXXXXXXX .
1.15 aaron 49: .Pp
1.1 millert 50: The trailing
51: .Ql X Ns s
1.16 aaron 52: are replaced with a combination of the current process number and
1.15 aaron 53: random letters.
54: The name chosen depends both on the number of
1.13 millert 55: .Ql X Ns s
56: in the template and the number of collisions with pre-existing files.
1.1 millert 57: The number of unique file names
58: .Nm
59: can return depends on the number of
60: .Ql X Ns s
1.13 millert 61: provided; ten
1.1 millert 62: .Ql X Ns s
63: will
64: result in
65: .Nm
1.13 millert 66: testing roughly 26 ** 10 combinations.
1.1 millert 67: .Pp
68: If
69: .Nm
1.13 millert 70: can successfully generate a unique file name, the file (or directory)
71: is created with file permissions such that it is only readable and writable
72: by its owner (unless the
1.1 millert 73: .Fl u
1.13 millert 74: flag is given) and the filename is printed to standard output.
1.8 millert 75: .Pp
1.10 aaron 76: .Nm mktemp
1.8 millert 77: is provided to allow shell scripts to safely use temporary files.
78: Traditionally, many shell scripts take the name of the program with
1.15 aaron 79: the PID as a suffix and use that as a temporary file name.
80: This kind of naming scheme is predictable and the race condition it creates
81: is easy for an attacker to win.
82: A safer, though still inferior approach
83: is to make a temporary directory using the same naming scheme.
84: While this does allow one to guarantee that a temporary file will not be
85: subverted, it still allows a simple denial of service attack.
86: For these reasons it is suggested that
1.8 millert 87: .Nm
88: be used instead.
1.14 aaron 89: .Pp
90: The options are as follows:
1.18 aaron 91: .Bl -tag -width Ds
1.5 millert 92: .It Fl d
93: Make a directory instead of a file.
1.19 ! millert 94: .It Fl p Ar directory
! 95: Use the specified
! 96: .Ar directory
! 97: as a prefix when generating the temporary file name.
! 98: The
! 99: .Ar directory
! 100: will be overridden by the user's
! 101: .Ev TMPDIR
! 102: environment variable if it is set.
! 103: This option implies the
! 104: .Fl t
! 105: flag (see below).
1.5 millert 106: .It Fl q
1.15 aaron 107: Fail silently if an error occurs.
108: This is useful if
1.5 millert 109: a script does not want error output to go to standard error.
1.19 ! millert 110: .It Fl t
! 111: Generate a temporary file rooted in a temporary directory.
! 112: The temporary directory is chosen as follows:
! 113: .Bl -bullet
! 114: .It
! 115: If the user's
! 116: .Ev TMPDIR
! 117: environment variable is set, the directory contained therein is used.
! 118: .It
! 119: Otherwise, if the
! 120: .Fl p
! 121: flag was given the specified directory is used.
! 122: .It
! 123: If none of the above apply,
! 124: .Pa /tmp
! 125: is used.
! 126: .El
! 127: .Pp
! 128: In this mode, the
! 129: .Ar template
! 130: should be a directory component (as opposed to a full path) and thus
! 131: should not contain any forward slashes.
1.1 millert 132: .It Fl u
133: Operate in
134: .Dq unsafe
1.15 aaron 135: mode.
136: The temp file will be unlinked before
1.1 millert 137: .Nm
1.15 aaron 138: exits.
139: This is slightly better than
1.1 millert 140: .Fn mktemp 3
1.15 aaron 141: but still introduces a race condition.
142: Use of this option is not encouraged.
1.6 millert 143: .El
1.15 aaron 144: .Pp
1.1 millert 145: The
146: .Nm
147: utility
1.10 aaron 148: exits with a value of 0 on success or 1 on failure.
1.1 millert 149: .Sh EXAMPLES
150: The following
151: .Xr sh 1
152: fragment illustrates a simple use of
153: .Nm
154: where the script should quit if it cannot get a safe
155: temporary file.
156: .Bd -literal -offset indent
1.17 pjanzen 157: CMD=`basename $0`
158: TMPFILE=`mktemp /tmp/$CMD.XXXXXXXXXX` || exit 1
1.1 millert 159: echo "program output" >> $TMPFILE
160: .Ed
161: .Pp
1.19 ! millert 162: The same fragment with support for a user's
! 163: .Ev TMPDIR
! 164: environment variable can be written as follows.
1.1 millert 165: .Bd -literal -offset indent
1.17 pjanzen 166: CMD=`basename $0`
1.19 ! millert 167: TMPFILE=`mktemp -t $CMD.XXXXXXXXXX` || exit 1
! 168: echo "program output" >> $TMPFILE
! 169: .Ed
! 170: .Pp
! 171: In some cases, it may be desirable to use a default temporary directory
! 172: other than
! 173: .Pa /tmp .
! 174: In this example the temporary file will be created in
! 175: .Pa /extra/tmp
! 176: unless the user's
! 177: .Ev TMPDIR
! 178: environment variable specifies otherwise.
! 179: .Bd -literal -offset indent
! 180: CMD=`basename $0`
! 181: TMPFILE=`mktemp -t -p /extra/tmp $CMD.XXXXXXXXXX` || exit 1
! 182: echo "program output" >> $TMPFILE
! 183: .Ed
! 184: .Pp
! 185: In some cases, we want the script to catch the error.
! 186: For instance, if we attempt to create two temporary files and
! 187: the second one fails we need to remove the first before exiting.
! 188: .Bd -literal -offset indent
! 189: CMD=`basename $0`
! 190: TMP1=`mktemp -t $CMD.1.XXXXXXXXXX` || exit 1
! 191: TMP2=`mktemp -t $CMD.2.XXXXXXXXXX`
1.2 millert 192: if [ $? -ne 0 ]; then
1.19 ! millert 193: rm -f $TMP1
1.1 millert 194: exit 1
195: fi
1.12 millert 196: .Ed
197: .Pp
198: Or perhaps you don't want to exit if
199: .Nm
1.15 aaron 200: is unable to create the file.
1.19 ! millert 201: In this case you can protect that part of the script thusly.
1.12 millert 202: .Bd -literal -offset indent
1.17 pjanzen 203: CMD=`basename $0`
1.19 ! millert 204: TMPFILE=`mktemp -q -t $CMD.XXXXXXXXXX` && {
1.12 millert 205: # Safe to use $TMPFILE in this block
206: echo data > $TMPFILE
207: ...
208: rm -f $TMPFILE
209: }
1.1 millert 210: .Ed
1.19 ! millert 211: .Sh ENVIRONMENT
! 212: .Bl -tag -width TMPDIR
! 213: .It Ev TMPDIR
! 214: directory in which to place the temporary file when in
! 215: .Fl t
! 216: mode
! 217: .El
1.1 millert 218: .Sh SEE ALSO
1.8 millert 219: .Xr mkdtemp 3 ,
1.10 aaron 220: .Xr mkstemp 3 ,
221: .Xr mktemp 3
1.1 millert 222: .Sh HISTORY
223: The
224: .Nm
225: utility appeared in
1.7 millert 226: .Ox 2.1 .
![[BACK]](/icons/back.gif){kind=icon}
Return to mktemp.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mktemp