date and time created 90/06/23 16:23:27 by bostic

[unix-history] / usr / src / lib / libc / stdio / tmpnam.3

.\" Copyright (c) 1988 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)tmpnam.3	5.10 (Berkeley) %G%
.\"
.TH TMPFILE 3 ""
.UC 7
.SH NAME
tempnam, tmpfile, tmpnam \- temporary file routines
.SH SYNOPSIS
.nf
.ft B
#include <stdio.h>

FILE *
tmpfile(void);

char *
tmpnam(char *str);

char *
tempnam(const char *tmpdir, const char *prefix);
.ft R
.fi
.SH DESCRIPTION
.I Tmpfile
opens a file using a file name generated by the routine
.IR tmpnam (3),
and returns a pointer to the stream associated with the file.
The created file is unlinked before
.I tmpfile
returns, causing the contents of the file to be deleted automatically
when the last reference to it is closed.
The file is opened with the access value ``w+''.
If
.I tmpnam
returns NULL, or if
.I tmpfile
is unable to open the file, a NULL pointer is returned.
.PP
.I Tmpnam
returns a pointer to a file name, in the directory ``/usr/tmp'', which
did not reference an existing file at some indeterminate point in the
past.
If the argument
.I s
is non-NULL, this file name is copied to the buffer it references.
Otherwise, memory to contain this file name is allocated by
.IR tmpnam .
In either case,
.I tmpnam
returns a pointer to the file name; in the latter case, the return
value may be used as a subsequent argument to
.IR free (3).
.PP
In the current implementation, the memory buffer referenced by
.I s
must be at least 16 bytes long.
.PP
.I Tempnam
is similar to
.I tmpnam,
but provides the ability to specify the directory which will
contain the temporary file and the file name prefix.
.PP
The environmental variable ``TMPDIR'' (if set), the argument
.I dir
(if non-NULL), the directory ``/usr/tmp'' and the directory ``/tmp''
are tried, in the listed order, as directories in which to store the
temporary file.
.I Tempnam
allocates memory in which to store the file name; the returned pointer
may be used as a subsequent argument to
.IR free (3).
The argument
.IR prefix ,
if non-NULL, is used to specify a file name prefix, which will be the
first part of the created file name.
.PP
.I Tmpnam
and
.I tempname
return a NULL pointer if unable to allocate memory or find a file
which may be created.
.PP
The manifest constants ``TMP_MAX'', ``P_tmpdir'' and ``L_tmpnam'',
documented for the routines
.I tmpnam
and
.I tempnam
in other systems, are not available in this implementation.
If the source code requires them, simply use:
.sp
.RS
#define	TMP_MAX		308915776
.br
#define	P_tmpdir		"/usr/tmp"
.br
#define	L_tmpnam		1024
.RE
.PP
.SH BUGS
These interfaces are provided for System V compatibility only.
The
.IR mkstemp (3)
interface is strongly preferred.
.PP
There are three important problems with these interfaces (as well as
with the historic
.IR mktemp (3)
interface).
First, there is an obvious race between file name selection and file
creation.
Second, most implementations provide only a limited number (usually
26) of possible temporary file names before file names will start being
recycled.
Third, the System V implementations of these functions (and
.IR mktemp )
use the
.IR access (2)
system call to determine whether or not the temporary file may be created.
This has obvious ramifications for setuid or setgid programs, complicating
the portable use of these interfaces in such programs.
.PP
The
.IR mkstemp (3)
interface has none of these problems;
the
.IR mktemp(3)
implementation in this system suffers only from the race condition described
above.
.PP
The
.I tmpfile
interface should not be used if there is any possibility that the user
does not wish the temporary file to be publicly readable or writable.
.PP
.SH SEE ALSO
fopen(3), mkstemp(3), mktemp(3)