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