summaryrefslogtreecommitdiffstats
path: root/man3/tempnam.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/tempnam.3')
-rw-r--r--man3/tempnam.3176
1 files changed, 176 insertions, 0 deletions
diff --git a/man3/tempnam.3 b/man3/tempnam.3
new file mode 100644
index 0000000..fd68643
--- /dev/null
+++ b/man3/tempnam.3
@@ -0,0 +1,176 @@
+'\" t
+.\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH tempnam 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+tempnam \- create a name for a temporary file
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.PP
+.BI "char *tempnam(const char *" dir ", const char *" pfx );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR tempnam ():
+.nf
+ Since glibc 2.19:
+ _DEFAULT_SOURCE
+ glibc 2.19 and earlier:
+ _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+.I "Never use this function."
+Use
+.BR mkstemp (3)
+or
+.BR tmpfile (3)
+instead.
+.PP
+The
+.BR tempnam ()
+function returns a pointer to a string that is a valid filename,
+and such that a file with this name did not exist when
+.BR tempnam ()
+checked.
+The filename suffix of the pathname generated will start with
+.I pfx
+in case
+.I pfx
+is a non-NULL string of at most five bytes.
+The directory prefix part of the pathname generated is required to
+be "appropriate" (often that at least implies writable).
+.PP
+Attempts to find an appropriate directory go through the following
+steps:
+.TP 3
+a)
+In case the environment variable
+.B TMPDIR
+exists and
+contains the name of an appropriate directory, that is used.
+.TP
+b)
+Otherwise, if the
+.I dir
+argument is non-NULL and appropriate, it is used.
+.TP
+c)
+Otherwise,
+.I P_tmpdir
+(as defined in
+.IR <stdio.h> )
+is used when appropriate.
+.TP
+d)
+Finally an implementation-defined directory may be used.
+.PP
+The string returned by
+.BR tempnam ()
+is allocated using
+.BR malloc (3)
+and hence should be freed by
+.BR free (3).
+.SH RETURN VALUE
+On success, the
+.BR tempnam ()
+function returns a pointer to a unique temporary filename.
+It returns NULL if a unique name cannot be generated, with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B ENOMEM
+Allocation of storage failed.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR tempnam ()
+T} Thread safety MT-Safe env
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+SVr4, 4.3BSD, POSIX.1-2001.
+Obsoleted in POSIX.1-2008.
+.SH NOTES
+Although
+.BR tempnam ()
+generates names that are difficult to guess,
+it is nevertheless possible that between the time that
+.BR tempnam ()
+returns a pathname, and the time that the program opens it,
+another program might create that pathname using
+.BR open (2),
+or create it as a symbolic link.
+This can lead to security holes.
+To avoid such possibilities, use the
+.BR open (2)
+.B O_EXCL
+flag to open the pathname.
+Or better yet, use
+.BR mkstemp (3)
+or
+.BR tmpfile (3).
+.PP
+SUSv2 does not mention the use of
+.BR TMPDIR ;
+glibc will use it only
+when the program is not set-user-ID.
+On SVr4, the directory used under \fBd)\fP is
+.I /tmp
+(and this is what glibc does).
+.PP
+Because it dynamically allocates memory used to return the pathname,
+.BR tempnam ()
+is reentrant, and thus thread safe, unlike
+.BR tmpnam (3).
+.PP
+The
+.BR tempnam ()
+function generates a different string each time it is called,
+up to
+.B TMP_MAX
+(defined in
+.IR <stdio.h> )
+times.
+If it is called more than
+.B TMP_MAX
+times,
+the behavior is implementation defined.
+.PP
+.BR tempnam ()
+uses at most the first five bytes from
+.IR pfx .
+.PP
+The glibc implementation of
+.BR tempnam ()
+fails with the error
+.B EEXIST
+upon failure to find a unique name.
+.SH BUGS
+The precise meaning of "appropriate" is undefined;
+it is unspecified how accessibility of a directory is determined.
+.SH SEE ALSO
+.BR mkstemp (3),
+.BR mktemp (3),
+.BR tmpfile (3),
+.BR tmpnam (3)