document why you want to use this and why other ways are bad.

1 files changed, 17 insertions, 3 deletions

diff --git a/usr.bin/mktemp/mktemp.1 b/usr.bin/mktemp/mktemp.1
index 4e48352f2e5..f8622c6a3a9 100644
--- a/usr.bin/mktemp/mktemp.1
+++ b/usr.bin/mktemp/mktemp.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: mktemp.1,v 1.7 1998/03/07 22:18:16 millert Exp $
+.\"	$OpenBSD: mktemp.1,v 1.8 1998/03/19 06:13:37 millert Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -76,6 +76,19 @@ is created with mode 0600 (unless the
 .Fl u
 flag is given) and the filename is printed
 to standard output.
+.Pp
+.Nm Mktemp
+is provided to allow shell scripts to safely use temporary files.
+Traditionally, many shell scripts take the name of the program with
+the pid as a suffix and use that as a temporary file name.  This
+kind of naming scheme is predictable and the race condition it creates
+is easy for an attacker to win.  A safer, though still inferior, approach
+is to make a temporary directory using the same naming scheme.  While
+this does allow one to guarantee that a temporary file will not be
+subverted, it still allows a simple denial of service attack.  For these
+reasons it is suggested that
+.Nm
+be used instead.
 .Sh OPTIONS
 .Bl -tag -width indent
 The available options are as follows:
@@ -125,8 +138,9 @@ zero length instead of checking $?.  This would allow
 the check to be done later one in the script (since
 $? would get clobbered by the next shell command).
 .Sh SEE ALSO
-.Xr mkstemp 3 ,
-.Xr mktemp 3
+.Xr mktemp 3 ,
+.Xr mkdtemp 3 ,
+.Xr mkstemp 3
 .Sh HISTORY
 The
 .Nm