Annotation of src/usr.bin/mktemp/mktemp.1, Revision 1.31
1.31 ! naddy 1: .\" $OpenBSD: mktemp.1,v 1.30 2019/01/25 00:19:26 millert Exp $
1.1 millert 2: .\"
1.27 millert 3: .\" Copyright (c) 1996, 2000, 2001, 2003, 2010, 2013
1.30 millert 4: .\" Todd C. Miller <millert@openbsd.org>
1.1 millert 5: .\"
1.21 millert 6: .\" Permission to use, copy, modify, and distribute this software for any
7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
1.1 millert 9: .\"
1.23 millert 10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 millert 17: .\"
1.31 ! naddy 18: .Dd $Mdocdate: January 25 2019 $
1.1 millert 19: .Dt MKTEMP 1
20: .Os
21: .Sh NAME
22: .Nm mktemp
1.20 millert 23: .Nd make temporary filename (unique)
1.1 millert 24: .Sh SYNOPSIS
25: .Nm mktemp
1.19 millert 26: .Op Fl dqtu
27: .Op Fl p Ar directory
1.20 millert 28: .Op Ar template
1.1 millert 29: .Sh DESCRIPTION
30: The
31: .Nm mktemp
1.20 millert 32: utility takes the given filename
33: .Ar template
34: and overwrites a portion of it to create a unique filename.
35: The
36: .Ar template
1.27 millert 37: may be any filename with at least six
1.1 millert 38: .Ql X Ns s
39: appended
40: to it, for example
1.20 millert 41: .Pa /tmp/tfile.XXXXXXXXXX .
42: If no
43: .Ar template
1.31 ! naddy 44: is specified, a default of
1.20 millert 45: .Pa tmp.XXXXXXXXXX
46: is used and the
47: .Fl t
48: flag is implied (see below).
1.15 aaron 49: .Pp
1.1 millert 50: The trailing
51: .Ql X Ns s
1.26 millert 52: are replaced with a unique digit and letter combination.
1.15 aaron 53: The name chosen depends both on the number of
1.13 millert 54: .Ql X Ns s
1.20 millert 55: in the
56: .Ar template
57: and the number of collisions with pre-existing files.
58: The number of unique filenames
1.1 millert 59: .Nm
60: can return depends on the number of
61: .Ql X Ns s
1.13 millert 62: provided; ten
1.1 millert 63: .Ql X Ns s
64: will
65: result in
66: .Nm
1.13 millert 67: testing roughly 26 ** 10 combinations.
1.1 millert 68: .Pp
69: If
70: .Nm
1.20 millert 71: can successfully generate a unique filename, the file (or directory)
1.13 millert 72: is created with file permissions such that it is only readable and writable
73: by its owner (unless the
1.1 millert 74: .Fl u
1.13 millert 75: flag is given) and the filename is printed to standard output.
1.8 millert 76: .Pp
1.10 aaron 77: .Nm mktemp
1.8 millert 78: is provided to allow shell scripts to safely use temporary files.
79: Traditionally, many shell scripts take the name of the program with
1.20 millert 80: the PID as a suffix and use that as a temporary filename.
1.15 aaron 81: This kind of naming scheme is predictable and the race condition it creates
82: is easy for an attacker to win.
83: A safer, though still inferior approach
84: is to make a temporary directory using the same naming scheme.
85: While this does allow one to guarantee that a temporary file will not be
86: subverted, it still allows a simple denial of service attack.
87: For these reasons it is suggested that
1.8 millert 88: .Nm
89: be used instead.
1.14 aaron 90: .Pp
91: The options are as follows:
1.18 aaron 92: .Bl -tag -width Ds
1.5 millert 93: .It Fl d
94: Make a directory instead of a file.
1.19 millert 95: .It Fl p Ar directory
96: Use the specified
97: .Ar directory
1.20 millert 98: as a prefix when generating the temporary filename.
1.19 millert 99: The
100: .Ar directory
101: will be overridden by the user's
102: .Ev TMPDIR
103: environment variable if it is set.
104: This option implies the
105: .Fl t
106: flag (see below).
1.5 millert 107: .It Fl q
1.15 aaron 108: Fail silently if an error occurs.
109: This is useful if
1.5 millert 110: a script does not want error output to go to standard error.
1.19 millert 111: .It Fl t
1.20 millert 112: Generate a path rooted in a temporary directory.
113: This directory is chosen as follows:
1.19 millert 114: .Bl -bullet
115: .It
116: If the user's
117: .Ev TMPDIR
118: environment variable is set, the directory contained therein is used.
119: .It
120: Otherwise, if the
121: .Fl p
122: flag was given the specified directory is used.
123: .It
124: If none of the above apply,
125: .Pa /tmp
126: is used.
127: .El
128: .Pp
129: In this mode, the
130: .Ar template
1.20 millert 131: (if specified) should be a directory component (as opposed to a full path)
132: and thus should not contain any forward slashes.
1.1 millert 133: .It Fl u
134: Operate in
135: .Dq unsafe
1.15 aaron 136: mode.
137: The temp file will be unlinked before
1.1 millert 138: .Nm
1.15 aaron 139: exits.
140: This is slightly better than
1.26 millert 141: .Xr mktemp 3
1.15 aaron 142: but still introduces a race condition.
143: Use of this option is not encouraged.
1.6 millert 144: .El
1.22 jmc 145: .Sh ENVIRONMENT
146: .Bl -tag -width TMPDIR
147: .It Ev TMPDIR
148: directory in which to place the temporary file when in
149: .Fl t
150: mode
151: .El
1.29 jmc 152: .Sh EXIT STATUS
153: .Ex -std mktemp
1.1 millert 154: .Sh EXAMPLES
155: The following
156: .Xr sh 1
157: fragment illustrates a simple use of
158: .Nm
159: where the script should quit if it cannot get a safe
160: temporary file.
161: .Bd -literal -offset indent
1.20 millert 162: TMPFILE=`mktemp /tmp/example.XXXXXXXXXX` || exit 1
1.1 millert 163: echo "program output" >> $TMPFILE
164: .Ed
165: .Pp
1.19 millert 166: The same fragment with support for a user's
167: .Ev TMPDIR
168: environment variable can be written as follows.
1.1 millert 169: .Bd -literal -offset indent
1.20 millert 170: TMPFILE=`mktemp -t example.XXXXXXXXXX` || exit 1
171: echo "program output" >> $TMPFILE
172: .Ed
173: .Pp
174: This can be further simplified if we don't care about the actual name of
1.22 jmc 175: the temporary file.
176: In this case the
1.20 millert 177: .Fl t
178: flag is implied.
179: .Bd -literal -offset indent
180: TMPFILE=`mktemp` || exit 1
1.19 millert 181: echo "program output" >> $TMPFILE
182: .Ed
183: .Pp
184: In some cases, it may be desirable to use a default temporary directory
185: other than
186: .Pa /tmp .
187: In this example the temporary file will be created in
188: .Pa /extra/tmp
189: unless the user's
190: .Ev TMPDIR
191: environment variable specifies otherwise.
192: .Bd -literal -offset indent
1.20 millert 193: TMPFILE=`mktemp -p /extra/tmp example.XXXXXXXXXX` || exit 1
1.19 millert 194: echo "program output" >> $TMPFILE
195: .Ed
196: .Pp
1.27 millert 197: In other cases, we want the script to catch the error.
1.19 millert 198: For instance, if we attempt to create two temporary files and
199: the second one fails we need to remove the first before exiting.
200: .Bd -literal -offset indent
1.20 millert 201: TMP1=`mktemp -t example.1.XXXXXXXXXX` || exit 1
202: TMP2=`mktemp -t example.2.XXXXXXXXXX`
1.2 millert 203: if [ $? -ne 0 ]; then
1.19 millert 204: rm -f $TMP1
1.1 millert 205: exit 1
206: fi
1.12 millert 207: .Ed
208: .Pp
209: Or perhaps you don't want to exit if
210: .Nm
1.15 aaron 211: is unable to create the file.
1.19 millert 212: In this case you can protect that part of the script thusly.
1.12 millert 213: .Bd -literal -offset indent
1.20 millert 214: TMPFILE=`mktemp -q -t example.XXXXXXXXXX` && {
1.12 millert 215: # Safe to use $TMPFILE in this block
216: echo data > $TMPFILE
217: ...
218: rm -f $TMPFILE
219: }
1.1 millert 220: .Ed
1.27 millert 221: .Sh DIAGNOSTICS
222: One of the following error messages may be displayed if
223: .Nm
224: does not succeed and the
225: .Fl q
226: option was not specified:
227: .Bl -tag -width indent
228: .It Li "insufficient number of Xs in template"
229: The specified
230: .Ar template
231: contained fewer than six
232: .Ql X Ns s
233: at the end.
234: .It Li "template must not contain directory separators in -t mode"
235: The
236: .Ar template
237: contained one or more directory components and the
238: .Fl t
239: option was specified.
240: .It Li "cannot make temp dir"
241: .Nm
242: was unable to create the temporary directory for any of the reasons
243: specified by
1.28 deraadt 244: .Xr mkdtemp 3 .
1.27 millert 245: .It Li "cannot make temp file"
246: .Nm
247: was unable to create the temporary file for any of the reasons
248: specified by
1.28 deraadt 249: .Xr mkstemp 3 .
1.27 millert 250: .It Li "cannot allocate memory"
251: .Nm
252: was unable to allocate memory for any of the reasons specified by
253: .Xr malloc 3 .
254: .El
1.1 millert 255: .Sh SEE ALSO
1.10 aaron 256: .Xr mktemp 3
1.1 millert 257: .Sh HISTORY
258: The
259: .Nm
1.24 jmc 260: utility first appeared in
1.7 millert 261: .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