GetTempFileName function
Applies to: desktop apps only
Creates a name for a temporary file. If a unique file name is generated, an empty file is created and the handle to it is released; otherwise, only a file name is generated.
Syntax
UINT WINAPI GetTempFileName( __in LPCTSTR lpPathName, __in LPCTSTR lpPrefixString, __in UINT uUnique, __out LPTSTR lpTempFileName );
Parameters
- lpPathName [in]
-
The directory path for the file name. Applications typically specify a period (.) for the current directory or the result of the GetTempPath function. The string cannot be longer than MAX_PATH–14 characters or GetTempFileName will fail. If this parameter is NULL, the function fails.
- lpPrefixString [in]
-
The null-terminated prefix string. The function uses up to the first three characters of this string as the prefix of the file name. This string must consist of characters in the OEM-defined character set.
- uUnique [in]
-
An unsigned integer to be used in creating the temporary file name. For more information, see Remarks.
If uUnique is zero, the function attempts to form a unique file name using the current system time. If the file already exists, the number is increased by one and the functions tests if this file already exists. This continues until a unique filename is found; the function creates a file by that name and closes it. Note that the function does not attempt to verify the uniqueness of the file name when uUnique is nonzero.
- lpTempFileName [out]
-
A pointer to the buffer that receives the temporary file name. This buffer should be MAX_PATH characters to accommodate the path plus the terminating null character.
Return value
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.
The following is a possible return value.
| Return value | Description |
|---|---|
|
The length of the string pointed to by the lpPathName parameter is more than MAX_PATH–14 characters. |
Remarks
The GetTempFileName function creates a temporary file name of the following form:
<path>\<pre><uuuu>.TMP
The following table describes the file name syntax.
| Component | Meaning |
|---|---|
| <path> | Path specified by the lpPathName parameter |
| <pre> | First three letters of the lpPrefixString string |
| <uuuu> | Hexadecimal value of uUnique |
If uUnique is zero, GetTempFileName creates an empty file and closes it. If uUnique is not zero, you must create the file yourself. Only a file name is created, because GetTempFileName is not able to guarantee that the file name is unique.
Only the lower 16 bits of the uUnique parameter are used. This limits GetTempFileName to a maximum of 65,535 unique file names if the lpPathName and lpPrefixString parameters remain the same.
Due to the algorithm used to generate file names, GetTempFileName can perform poorly when creating a large number of files with the same prefix. In such cases, it is recommended that you construct unique file names based on GUIDs.
Temporary files whose names have been created by this function are not automatically deleted. To delete these files call DeleteFile.
To avoid problems resulting when converting an ANSI string, an application should call the CreateFile function to create a temporary file.
Examples
For an example, see Creating and Using a Temporary File.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | GetTempFileNameW (Unicode) and GetTempFileNameA (ANSI) |
See also
Send comments about this topic to Microsoft
Build date: 4/17/2012
- 3/25/2010
- danmose
[System.Security.SecuritySafeCritical]
[ResourceExposure(ResourceScope.AppDomain)]
[ResourceConsumption(ResourceScope.Machine, ResourceScope.Machine)]
public static String GetTempFileName()
For completeness, here's the P/Invoke definition I wrote in mscorlib. Compared with the other P/Invoke wrappers posted here, note the other important DllImport flags, as well as the return value which you must check to see if an error occurred.
[DllImport(KERNEL32, CharSet=CharSet.Auto, SetLastError=true, BestFitMapping=false)]
[ResourceExposure(ResourceScope.None)]
internal static extern uint GetTempFileName(String tmpPath, String prefix, uint uniqueIdOrZero, StringBuilder tmpFileName);
- 10/23/2009
- Brian Grunkemeyer - MSFT
<DllImport("kernel32.dll", CharSet:=CharSet.Auto)> _Public Shared Sub GetTempFileName(ByVal tempDirName As String, ByVal prefixName As String, ByVal unique As Integer, ByVal sb As StringBuilder)
End Sub
[DllImport("kernel32.dll", CharSet=CharSet.Auto)]
public static extern void GetTempFileName(string tempDirName, string prefixName, int unique, StringBuilder sb);
- 4/25/2009
- dmex
- 7/9/2007
- David Gardiner
- 1/13/2009
- Dennis Middleton - MSFT
