GetTempFileName

The GetTempFileName function creates a name for a temporary file. The file name is the concatenation of specified path and prefix strings, a hexadecimal string formed from a specified integer, and the .tmp extension.

The specified integer can be nonzero, in which case, the function creates the file name but does not create the file. If you specify zero for the integer, the function creates a unique file name and creates the file in the specified directory.

UINT GetTempFileName(
  LPCTSTR lpPathName,      // directory name
  LPCTSTR lpPrefixString,  // file name prefix
  UINT uUnique,            // integer
  LPTSTR lpTempFileName    // file name buffer
);

Parameters

lpPathName

[in] Pointer to a null-terminated string that specifies the directory path for the file name. This string must consist of characters in the ANSI character set. Applications typically specify a period (.) or the result of the GetTempPath function for this parameter. If this parameter is NULL, the function fails.

lpPrefixString

[in] Pointer to a null-terminated prefix string. The function uses the first three characters of this string as the prefix of the file name. This string must consist of characters in the ANSI character set.

uUnique

[in] Specifies an unsigned integer that the function converts to a hexadecimal string for use in creating the temporary file name.

If uUnique is nonzero, the function appends the hexadecimal string to lpPrefixString to form the temporary file name. In this case, the function does not create the specified file, and does not test whether the file name is unique.

If uUnique is zero, the function uses a hexadecimal string derived from the current system time. In this case, the function uses different values until it finds a unique file name, and then it creates the file in the lpPathName directory.

lpTempFileName

[out] Pointer to the buffer that receives the temporary file name. This null-terminated string consists of characters in the ANSI character set. This buffer should be at least the length, in bytes, specified by MAX_PATH to accommodate the path.

Return Values

If the function succeeds, the return value specifies the unique numeric value used in the temporary file name. If the uUnique parameter is nonzero, the return value specifies that same number.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The GetTempFileName function creates a temporary file name of the following form:

path\preuuuu.TMP

The following table describes the file name syntax.

When the system shuts down, temporary files whose names have been created by this function are not automatically deleted.

To avoid problems resulting when converting an ANSI string, an application should call the CreateFile function to create a temporary file.

If the uUnique parameter is zero, GetTempFileName attempts to form a unique number based on the current system time. If a file with the resulting file name exists, the number is increased by one and the test for existence is repeated. Testing continues until a unique file name is found. GetTempFileName then creates a file by that name and closes it. When uUnique is nonzero, no attempt is made to create and open the file.

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

File I/O Overview, File I/O Functions, CreateFile, GetTempPath