Libc-1158.50.2.tar.gz

[apple/libc.git] / stdio / FreeBSD / mktemp.3

diff --git a/stdio/FreeBSD/mktemp.3 b/stdio/FreeBSD/mktemp.3
index af2eba70f0f5f8e474dd176f3eca5ea901489e3f..d4072c63189e74570c9adcb7c04067d500482672 100644 (file)
--- a/stdio/FreeBSD/mktemp.3
+++ b/stdio/FreeBSD/mktemp.3
@@ -9,7 +9,7 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
@@ -26,26 +26,50 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)mktemp.3   8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdio/mktemp.3,v 1.22 2007/01/09 00:28:07 imp Exp $
 .\"
-.Dd February 11, 1998
+.Dd December 18, 2015
 .Dt MKTEMP 3
 .Os
 .Sh NAME
-.Nm mktemp
+.Nm mktemp ,
+.Nm mkstemp ,
+.Nm mkdtemp ,
+.Nm mkstemps ,
+.Nm mkostemp ,
+.Nm mkostemps
 .Nd make temporary file name (unique)
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In unistd.h
 .Ft char *
-.Fn mktemp "char *template"
+.Fo mktemp
+.Fa "char *template"
+.Fc
 .Ft int
-.Fn mkstemp "char *template"
-.Ft int
-.Fn mkstemps "char *template" "int suffixlen"
+.Fo mkstemp
+.Fa "char *template"
+.Fc
 .Ft char *
-.Fn mkdtemp "char *template"
+.Fo mkdtemp
+.Fa "char *template"
+.Fc
+.Ft int
+.Fo mkstemps
+.Fa "char *template"
+.Fa "int suffixlen"
+.Fc
+.Ft int
+.Fo mkostemp
+.Fa "char *template"
+.Fa "int oflags"
+.Fc
+.Ft int
+.Fo mkostemps
+.Fa "char *template"
+.Fa "int suffixlen"
+.Fa "int oflags"
+.Fc
 .Sh DESCRIPTION
 The
 .Fn mktemp
@@ -84,22 +108,45 @@ This avoids the race between testing for a file's existence and opening it
 for use.
 .Pp
 The
+.Fn mkdtemp
+function makes the same replacement to the template as in
+.Fn mktemp
+and creates the template directory, mode 0700.
+.Pp
+The
+.Fn mkostemp
+function
+is like
+.Fn mkstemp
+but allows specifying additional
+.Xr open 2
+flags (defined in
+.In fcntl.h ) .
+The permitted flags are
+.Dv O_APPEND ,
+.Dv O_SHLOCK ,
+.Dv O_EXLOCK
+and
+.Dv O_CLOEXEC .
+.Pp
+The
 .Fn mkstemps
-function acts the same as
-.Fn mkstemp ,
-except it permits a suffix to exist in the template.
+and
+.Fn mkostemps
+functions act the same as
+.Fn mkstemp
+and
+.Fn mkostemp
+respectively,
+except they permit a suffix to exist in the template.
 The template should be of the form
 .Pa /tmp/tmpXXXXXXsuffix .
 The
 .Fn mkstemps
-function
-is told the length of the suffix string.
-.Pp
-The
-.Fn mkdtemp
-function makes the same replacement to the template as in
-.Fn mktemp
-and creates the template directory, mode 0700.
+and
+.Fn mkostemps
+functions
+are told the length of the suffix string.
 .Sh RETURN VALUES
 The
 .Fn mktemp
@@ -109,9 +156,11 @@ functions return a pointer to the template on success and
 .Dv NULL
 on failure.
 The
-.Fn mkstemp
-and
+.Fn mkstemp ,
+.Fn mkostemp ,
 .Fn mkstemps
+and
+.Fn mkostemps
 functions
 return \-1 if no suitable file could be created.
 If either call fails an error code is placed in the global variable
@@ -119,7 +168,9 @@ If either call fails an error code is placed in the global variable
 .Sh ERRORS
 The
 .Fn mkstemp ,
-.Fn mkstemps
+.Fn mkostemp ,
+.Fn mkstemps ,
+.Fn mkostemps ,
 and
 .Fn mkdtemp
 functions
@@ -132,8 +183,25 @@ The pathname portion of the template is not an existing directory.
 .El
 .Pp
 The
+.Fn mkostemp
+and
+.Fn mkostemps
+functions
+may also set
+.Va errno
+to the following value:
+.Bl -tag -width Er
+.It Bq Er EINVAL
+The
+.Fa oflags
+argument is invalid.
+.El
+.Pp
+The
 .Fn mkstemp ,
-.Fn mkstemps
+.Fn mkostemp ,
+.Fn mkstemps ,
+.Fn mkostemps 
 and
 .Fn mkdtemp
 functions
@@ -144,9 +212,11 @@ to any value specified by the
 function.
 .Pp
 The
-.Fn mkstemp
-and
+.Fn mkstemp ,
+.Fn mkostemp ,
 .Fn mkstemps
+and
+.Fn mkostemps 
 functions
 may also set
 .Va errno
@@ -180,18 +250,38 @@ with an argument of
 will result in a core dump due to
 .Fn mkstemp
 attempting to modify the string constant that was given.
-If the program in question makes heavy use of that type
-of function call, you do have the option of compiling the program
-so that it will store string constants in a writable segment of memory.
-See
-.Xr gcc 1
-for more information.
+.Sh LEGACY SYNOPSIS
+.Fd #include <unistd.h>
+.Pp
+The include file
+.In unistd.h
+is necessary and sufficient for all functions.
 .Sh SEE ALSO
 .Xr chmod 2 ,
 .Xr getpid 2 ,
 .Xr mkdir 2 ,
 .Xr open 2 ,
-.Xr stat 2
+.Xr stat 2 ,
+.Xr compat 5
+.Sh STANDARDS
+The
+.Fn mkstemp
+and
+.Fn mkdtemp
+functions are expected to conform to
+.St -p1003.1-2008 .
+The
+.Fn mktemp
+function is expected to conform to
+.St -p1003.1-2001
+and is not specified by
+.St -p1003.1-2008 .
+The
+.Fn mkostemp ,
+.Fn mkstemps
+and
+.Fn mkostemps
+functions do not conform to any standard.
 .Sh HISTORY
 A
 .Fn mktemp
@@ -213,6 +303,11 @@ function first appeared in
 .Ox 2.4 ,
 and later in
 .Fx 3.4 .
+The
+.Fn mkostemp
+and
+.Fn mkostemps
+functions appeared in OS X 10.12.
 .Sh BUGS
 This family of functions produces filenames which can be guessed,
 though the risk is minimized when large numbers of
@@ -229,6 +324,8 @@ and opening it for use
 particularly dangerous from a security perspective.
 Whenever it is possible,
 .Fn mkstemp
+or
+.Fn mkostemp
 should be used instead, since it does not have the race condition.
 If
 .Fn mkstemp
@@ -242,10 +339,3 @@ and the return status of the call should be tested for failure.
 This will ensure that the program does not continue blindly
 in the event that an attacker has already created the file
 with the intention of manipulating or reading its contents.
-.Pp
-The implementation of these functions calls
-.Xr arc4random 3 ,
-which is not reentrant.
-You must provide your own locking around this and other consumers of the
-.Xr arc4random 3
-API.