Technical Reference: Base Operating System and Extensions , Volume 2

tmpnam or tempnam Subroutine

Purpose

Constructs the name for a temporary file.

Syntax

#include <stdio.h> char *tmpnam ( String) char *String;

char *tempnam ( Directory, FileXPointer) const char *Directory, *FileXPointer;

Description

Attention: The tmpnam and tempnam subroutines generate a different file name each time they are called. If called more than 16,384 (TMP_MAX) times by a single process, these subroutines recycle previously used names.

The tmpnam and the tempnam subroutines generate file names for temporary files. The tmpnam subroutine generates a file name using the path name defined as P_tmpdir in the stdio.h file.

Files created using the tmpnam subroutine reside in a directory intended for temporary use. The file names are unique. The application must create and remove the file.

The tempnam subroutine enables you to define the directory. The Directory parameter points to the name of the directory in which the file is to be created. If the Directory parameter is a null pointer or points to a string that is not a name for a directory, the path prefix defined as P_tmpdir in the stdio.h file is used. For an application that has temporary files with initial letter sequences, use the FileXPointer parameter to define the sequence. The FileXPointer parameter (a null pointer or a string of up to 5 bytes) is used as the beginning of the file name.

Between the time a file name is created and the file is opened, another process can create a file with the same name. Name duplication is unlikely if the other process uses these subroutines or the mktemp subroutine, and if the file names are chosen to avoid duplication by other means.

Parameters

String

Specifies the address of an array of at least the number of bytes specified by L_tmpnam, a constant defined in the stdio.h file.

If the String parameter has a null value, the tmpnam subroutine places its result into an internal static area and returns a pointer to that area. The next call to this subroutine destroys the contents of the area.

If the String parameter's value is not null, the tmpnam subroutine places its results into the specified array and returns the value of the String parameter.

Directory

Points to the path name of the directory in which the file is to be created.

The tempnam subroutine controls the choice of a directory. If the Directory parameter is a null pointer or points to a string that is not a path name for an appropriate directory, the path name defined as P_tmpdir in the stdio.h file is used. If that path name is not accessible, the /tmp directory is used. You can bypass the selection of a path name by providing an environment variable, TMPDIR, in the user's environment. The value of the TMPDIR environment variable is a path name for the desired temporary-file directory.

FileXPointer

A pointer to an initial character sequence with which the file name begins. The FileXPointer parameter value can be a null pointer, or it can point to a string of characters to be used as the first characters of the temporary-file name. The number of characters allowed is file system dependent, but 5 bytes is the maximum allowed.

Return Values

Upon completion, the tempnam subroutine allocates space for the string using the malloc subroutine, puts the generated path name in that space, and returns a pointer to the space. Otherwise, it returns a null pointer and sets the errno global variable to indicate the error. The pointer returned by tempnam may be used in the free subroutine when the space is no longer needed.

Error Codes

The tempnam subroutine returns the following error code if unsuccessful:

ENOMEM

Insufficient storage space is available.

ENINVAL

Indicates an invalid string value.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The fopen, freopen, fdopen subroutine, malloc, free, realloc, calloc, mallopt, mallinfo, or alloca subroutine, mktemp or mkstemp subroutine, openx, open, creat subroutine, tmpfile (tmpfile Subroutine) subroutine, unlink (unlink Subroutine) subroutine.

The environment file.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

Input and Output Handling Programmer's Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.