Функция GetTempFileNameA (fileapi.h)

Статья
08/23/2023

Создает имя для временного файла. Если создается уникальное имя файла, создается пустой файл и дескриптор для него освобождается; В противном случае создается только имя файла.

Синтаксис

UINT GetTempFileNameA(
  [in]  LPCSTR lpPathName,
  [in]  LPCSTR lpPrefixString,
  [in]  UINT   uUnique,
  [out] LPSTR  lpTempFileName
);

Параметры

[in] lpPathName

Путь к каталогу для имени файла. Приложения обычно указывают точку (.) для текущего каталога или результата функции GetTempPath . Строка не может быть длиннее MAX_PATH–14 символов, иначе getTempFileName завершится ошибкой. Если этот параметр имеет значение NULL, функция завершается ошибкой.

[in] lpPrefixString

Строка префикса, заканчивающаяся null. Функция использует до трех первых символов этой строки в качестве префикса имени файла. Эта строка должна состоять из символов в наборе символов, определяемом OEM.

[in] uUnique

Целое число без знака, используемое при создании временного имени файла. Дополнительные сведения см. в подразделе "Примечания".

Если uUnique равно нулю, функция пытается сформировать уникальное имя файла, используя текущее системное время. Если файл уже существует, число увеличивается на один, и функции проверяют, существует ли этот файл. Это продолжается до тех пор, пока не будет найдено уникальное имя файла; функция создает файл с таким именем и закрывает его. Обратите внимание, что функция не пытается проверить уникальность имени файла, если uUnique не имеет нуля.

[out] lpTempFileName

Указатель на буфер, получающий имя временного файла. Этот буфер должен содержать MAX_PATH символы, чтобы вместить путь, а также завершающий символ NULL.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение указывает уникальное числовое значение, используемое во временном имени файла. Если параметр uUnique не равен нулю, то возвращаемое значение указывает это же число.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Ниже приведено возможное возвращаемое значение.

Возвращаемое значение	Описание
ERROR_BUFFER_OVERFLOW	Длина строки, на которую указывает параметр lpPathName , превышает MAX_PATH–14 символов.

Компонент	Значение
<Путь>	Путь, заданный параметром lpPathName
<pre>	Первые три буквы строки lpPrefixString
<uuuuuu>	Шестнадцатеричное значение uUnique

Если значение uUnique равно нулю, GetTempFileName создает пустой файл и закрывает его. Если значение uUnique не равно нулю, необходимо создать файл самостоятельно. Создается только имя файла, так как GetTempFileName не может гарантировать уникальность имени файла.

Используются только нижние 16 бит параметра uUnique . Это ограничивает GetTempFileName до 65 535 уникальных имен файлов, если параметры lpPathName и lpPrefixString остаются неизменными.

Из-за алгоритма, используемого для создания имен файлов, GetTempFileName может работать плохо при создании большого количества файлов с одинаковым префиксом. В таких случаях рекомендуется создавать уникальные имена файлов на основе GUID.

Временные файлы, имена которых были созданы этой функцией, не удаляются автоматически. Чтобы удалить эти файлы, вызовите DeleteFile.

Чтобы избежать проблем, возникающих при преобразовании строки ANSI, приложение должно вызвать функцию CreateFile для создания временного файла.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
Прозрачная отработка отказа (TFO) SMB 3.0	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

Пример см. в статье Создание и использование временного файла.

Примечание

Заголовок fileapi.h определяет GetTempFileName как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	fileapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll