Previous: Making Special Files, Up: File System Interface


14.11 Temporary Files

If you need to use a temporary file in your program, you can use the tmpfile function to open it. Or you can use the tmpnam (better: tmpnam_r) function to provide a name for a temporary file and then you can open it in the usual way with fopen.

The tempnam function is like tmpnam but lets you choose what directory temporary files will go in, and something about what their file names will look like. Important for multi-threaded programs is that tempnam is reentrant, while tmpnam is not since it returns a pointer to a static buffer.

These facilities are declared in the header file stdio.h.

— Function: FILE * tmpfile (void)

Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd lock | See POSIX Safety Concepts.

This function creates a temporary binary file for update mode, as if by calling fopen with mode "wb+". The file is deleted automatically when it is closed or when the program terminates. (On some other ISO C systems the file may fail to be deleted if the program terminates abnormally).

This function is reentrant.

When the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32-bit system this function is in fact tmpfile64, i.e., the LFS interface transparently replaces the old interface.

— Function: FILE * tmpfile64 (void)

Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd lock | See POSIX Safety Concepts.

This function is similar to tmpfile, but the stream it returns a pointer to was opened using tmpfile64. Therefore this stream can be used for files larger than 2^31 bytes on 32-bit machines.

Please note that the return type is still FILE *. There is no special FILE type for the LFS interface.

If the sources are compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is available under the name tmpfile and so transparently replaces the old interface.

— Function: char * tmpnam (char *result)

Preliminary: | MT-Unsafe race:tmpnam/!result | AS-Unsafe | AC-Safe | See POSIX Safety Concepts.

This function constructs and returns a valid file name that does not refer to any existing file. If the result argument is a null pointer, the return value is a pointer to an internal static string, which might be modified by subsequent calls and therefore makes this function non-reentrant. Otherwise, the result argument should be a pointer to an array of at least L_tmpnam characters, and the result is written into that array.

It is possible for tmpnam to fail if you call it too many times without removing previously-created files. This is because the limited length of the temporary file names gives room for only a finite number of different names. If tmpnam fails it returns a null pointer.

Warning: Between the time the pathname is constructed and the file is created another process might have created a file with the same name using tmpnam, leading to a possible security hole. The implementation generates names which can hardly be predicted, but when opening the file you should use the O_EXCL flag. Using tmpfile or mkstemp is a safe way to avoid this problem.

— Function: char * tmpnam_r (char *result)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is nearly identical to the tmpnam function, except that if result is a null pointer it returns a null pointer.

This guarantees reentrancy because the non-reentrant situation of tmpnam cannot happen here.

Warning: This function has the same security problems as tmpnam.

— Macro: int L_tmpnam

The value of this macro is an integer constant expression that represents the minimum size of a string large enough to hold a file name generated by the tmpnam function.

— Macro: int TMP_MAX

The macro TMP_MAX is a lower bound for how many temporary names you can create with tmpnam. You can rely on being able to call tmpnam at least this many times before it might fail saying you have made too many temporary file names.

With the GNU C Library, you can create a very large number of temporary file names. If you actually created the files, you would probably run out of disk space before you ran out of names. Some other systems have a fixed, small limit on the number of temporary files. The limit is never less than 25.

— Function: char * tempnam (const char *dir, const char *prefix)

Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

This function generates a unique temporary file name. If prefix is not a null pointer, up to five characters of this string are used as a prefix for the file name. The return value is a string newly allocated with malloc, so you should release its storage with free when it is no longer needed.

Because the string is dynamically allocated this function is reentrant.

The directory prefix for the temporary file name is determined by testing each of the following in sequence. The directory must exist and be writable.

This function is defined for SVID compatibility.

Warning: Between the time the pathname is constructed and the file is created another process might have created a file with the same name using tempnam, leading to a possible security hole. The implementation generates names which can hardly be predicted, but when opening the file you should use the O_EXCL flag. Using tmpfile or mkstemp is a safe way to avoid this problem.

— SVID Macro: char * P_tmpdir

This macro is the name of the default directory for temporary files.

Older Unix systems did not have the functions just described. Instead they used mktemp and mkstemp. Both of these functions work by modifying a file name template string you pass. The last six characters of this string must be ‘XXXXXX’. These six ‘X’s are replaced with six characters which make the whole string a unique file name. Usually the template string is something like ‘/tmp/prefixXXXXXX’, and each program uses a unique prefix.

NB: Because mktemp and mkstemp modify the template string, you must not pass string constants to them. String constants are normally in read-only storage, so your program would crash when mktemp or mkstemp tried to modify the string. These functions are declared in the header file stdlib.h.

— Function: char * mktemp (char *template)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The mktemp function generates a unique file name by modifying template as described above. If successful, it returns template as modified. If mktemp cannot find a unique file name, it makes template an empty string and returns that. If template does not end with ‘XXXXXX’, mktemp returns a null pointer.

Warning: Between the time the pathname is constructed and the file is created another process might have created a file with the same name using mktemp, leading to a possible security hole. The implementation generates names which can hardly be predicted, but when opening the file you should use the O_EXCL flag. Using mkstemp is a safe way to avoid this problem.

— Function: int mkstemp (char *template)

Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | See POSIX Safety Concepts.

The mkstemp function generates a unique file name just as mktemp does, but it also opens the file for you with open (see Opening and Closing Files). If successful, it modifies template in place and returns a file descriptor for that file open for reading and writing. If mkstemp cannot create a uniquely-named file, it returns -1. If template does not end with ‘XXXXXX’, mkstemp returns -1 and does not modify template.

The file is opened using mode 0600. If the file is meant to be used by other users this mode must be changed explicitly.

Unlike mktemp, mkstemp is actually guaranteed to create a unique file that cannot possibly clash with any other program trying to create a temporary file. This is because it works by calling open with the O_EXCL flag, which says you want to create a new file and get an error if the file already exists.

— Function: char * mkdtemp (char *template)

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

The mkdtemp function creates a directory with a unique name. If it succeeds, it overwrites template with the name of the directory, and returns template. As with mktemp and mkstemp, template should be a string ending with ‘XXXXXX’.

If mkdtemp cannot create an uniquely named directory, it returns NULL and sets errno appropriately. If template does not end with ‘XXXXXX’, mkdtemp returns NULL and does not modify template. errno will be set to EINVAL in this case.

The directory is created using mode 0700.

The directory created by mkdtemp cannot clash with temporary files or directories created by other users. This is because directory creation always works like open with O_EXCL. See Creating Directories.

The mkdtemp function comes from OpenBSD.