Annotation of src/usr.bin/mktemp/mktemp.1, Revision 1.26
1.26 ! millert 1: .\" $OpenBSD: mktemp.1,v 1.25 2007/05/31 19:20:13 jmc Exp $
1.1 millert 2: .\"
1.19 millert 3: .\" Copyright (c) 1996, 2000, 2001 Todd C. Miller <Todd.Miller@courtesan.com>
1.1 millert 4: .\"
1.21 millert 5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
1.1 millert 8: .\"
1.23 millert 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 millert 16: .\"
1.25 jmc 17: .Dd $Mdocdate$
1.1 millert 18: .Dt MKTEMP 1
19: .Os
20: .Sh NAME
21: .Nm mktemp
1.20 millert 22: .Nd make temporary filename (unique)
1.1 millert 23: .Sh SYNOPSIS
24: .Nm mktemp
1.19 millert 25: .Op Fl dqtu
26: .Op Fl p Ar directory
1.20 millert 27: .Op Ar template
1.1 millert 28: .Sh DESCRIPTION
29: The
30: .Nm mktemp
1.20 millert 31: utility takes the given filename
32: .Ar template
33: and overwrites a portion of it to create a unique filename.
34: The
35: .Ar template
36: may be any filename with some number of
1.1 millert 37: .Ql X Ns s
38: appended
39: to it, for example
1.20 millert 40: .Pa /tmp/tfile.XXXXXXXXXX .
41: If no
42: .Ar template
43: is specified a default of
44: .Pa tmp.XXXXXXXXXX
45: is used and the
46: .Fl t
47: flag is implied (see below).
1.15 aaron 48: .Pp
1.1 millert 49: The trailing
50: .Ql X Ns s
1.26 ! millert 51: are replaced with a unique digit and letter combination.
1.15 aaron 52: The name chosen depends both on the number of
1.13 millert 53: .Ql X Ns s
1.20 millert 54: in the
55: .Ar template
56: and the number of collisions with pre-existing files.
57: The number of unique filenames
1.1 millert 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.20 millert 70: can successfully generate a unique filename, the file (or directory)
1.13 millert 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.20 millert 79: the PID as a suffix and use that as a temporary filename.
1.15 aaron 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
1.20 millert 97: as a prefix when generating the temporary filename.
1.19 millert 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
1.20 millert 111: Generate a path rooted in a temporary directory.
112: This directory is chosen as follows:
1.19 millert 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
1.20 millert 130: (if specified) should be a directory component (as opposed to a full path)
131: and thus 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.26 ! millert 140: .Xr 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.22 jmc 149: .Sh ENVIRONMENT
150: .Bl -tag -width TMPDIR
151: .It Ev TMPDIR
152: directory in which to place the temporary file when in
153: .Fl t
154: mode
155: .El
1.1 millert 156: .Sh EXAMPLES
157: The following
158: .Xr sh 1
159: fragment illustrates a simple use of
160: .Nm
161: where the script should quit if it cannot get a safe
162: temporary file.
163: .Bd -literal -offset indent
1.20 millert 164: TMPFILE=`mktemp /tmp/example.XXXXXXXXXX` || exit 1
1.1 millert 165: echo "program output" >> $TMPFILE
166: .Ed
167: .Pp
1.19 millert 168: The same fragment with support for a user's
169: .Ev TMPDIR
170: environment variable can be written as follows.
1.1 millert 171: .Bd -literal -offset indent
1.20 millert 172: TMPFILE=`mktemp -t example.XXXXXXXXXX` || exit 1
173: echo "program output" >> $TMPFILE
174: .Ed
175: .Pp
176: This can be further simplified if we don't care about the actual name of
1.22 jmc 177: the temporary file.
178: In this case the
1.20 millert 179: .Fl t
180: flag is implied.
181: .Bd -literal -offset indent
182: TMPFILE=`mktemp` || exit 1
1.19 millert 183: echo "program output" >> $TMPFILE
184: .Ed
185: .Pp
186: In some cases, it may be desirable to use a default temporary directory
187: other than
188: .Pa /tmp .
189: In this example the temporary file will be created in
190: .Pa /extra/tmp
191: unless the user's
192: .Ev TMPDIR
193: environment variable specifies otherwise.
194: .Bd -literal -offset indent
1.20 millert 195: TMPFILE=`mktemp -p /extra/tmp example.XXXXXXXXXX` || exit 1
1.19 millert 196: echo "program output" >> $TMPFILE
197: .Ed
198: .Pp
199: In some cases, we want the script to catch the error.
200: For instance, if we attempt to create two temporary files and
201: the second one fails we need to remove the first before exiting.
202: .Bd -literal -offset indent
1.20 millert 203: TMP1=`mktemp -t example.1.XXXXXXXXXX` || exit 1
204: TMP2=`mktemp -t example.2.XXXXXXXXXX`
1.2 millert 205: if [ $? -ne 0 ]; then
1.19 millert 206: rm -f $TMP1
1.1 millert 207: exit 1
208: fi
1.12 millert 209: .Ed
210: .Pp
211: Or perhaps you don't want to exit if
212: .Nm
1.15 aaron 213: is unable to create the file.
1.19 millert 214: In this case you can protect that part of the script thusly.
1.12 millert 215: .Bd -literal -offset indent
1.20 millert 216: TMPFILE=`mktemp -q -t example.XXXXXXXXXX` && {
1.12 millert 217: # Safe to use $TMPFILE in this block
218: echo data > $TMPFILE
219: ...
220: rm -f $TMPFILE
221: }
1.1 millert 222: .Ed
223: .Sh SEE ALSO
1.10 aaron 224: .Xr mktemp 3
1.1 millert 225: .Sh HISTORY
226: The
227: .Nm
1.24 jmc 228: utility first appeared in
1.7 millert 229: .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