Função GetTempFileNameA (fileapi.h)

Artigo
08/23/2023

Cria um nome para um arquivo temporário. Se um nome de arquivo exclusivo for gerado, um arquivo vazio será criado e o identificador para ele será liberado; caso contrário, somente um nome de arquivo será gerado.

Sintaxe

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

Parâmetros

[in] lpPathName

O caminho do diretório para o nome do arquivo. Os aplicativos normalmente especificam um ponto (.) para o diretório atual ou o resultado da função GetTempPath . A cadeia de caracteres não pode ter mais de MAX_PATH-14 caracteres ou GetTempFileName falhará. Se esse parâmetro for NULL, a função falhará.

[in] lpPrefixString

A cadeia de caracteres de prefixo terminada em nulo. A função usa até os três primeiros caracteres dessa cadeia de caracteres como o prefixo do nome do arquivo. Essa cadeia de caracteres deve consistir em caracteres no conjunto de caracteres definido por OEM.

[in] uUnique

Um inteiro sem sinal a ser usado na criação do nome de arquivo temporário. Para obter mais informações, consulte Comentários.

Se uUnique for zero, a função tentará formar um nome de arquivo exclusivo usando a hora atual do sistema. Se o arquivo já existir, o número será aumentado em um e as funções testarão se esse arquivo já existir. Isso continua até que um nome de arquivo exclusivo seja encontrado; a função cria um arquivo com esse nome e o fecha. Observe que a função não tenta verificar a exclusividade do nome do arquivo quando uUnique é diferente de zero.

[out] lpTempFileName

Um ponteiro para o buffer que recebe o nome de arquivo temporário. Esse buffer deve ser MAX_PATH caracteres para acomodar o caminho mais o caractere nulo de terminação.

Valor retornado

Se a função for bem-sucedida, o valor retornado especificará o valor numérico exclusivo usado no nome de arquivo temporário. Se o parâmetro uUnique for diferente de zero, o valor retornado especificará esse mesmo número.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Veja a seguir um possível valor retornado.

Valor retornado	Descrição
ERROR_BUFFER_OVERFLOW	O comprimento da cadeia de caracteres apontada pelo parâmetro lpPathName é maior que MAX_PATH-14 caracteres.

Comentários

A função GetTempFileName cria um nome de arquivo temporário do seguinte formato:

<path>\<pre><uuuu>. TMP

A tabela a seguir descreve a sintaxe de nome de arquivo.

Componente	Significado
<caminho>	Caminho especificado pelo parâmetro lpPathName
<pre>	Primeiras três letras da cadeia de caracteres lpPrefixString
<Uuuu>	Valor hexadecimal de uUnique

Se uUnique for zero, GetTempFileName criará um arquivo vazio e o fechará. Se uUnique não for zero, você deverá criar o arquivo por conta própria. Somente um nome de arquivo é criado, pois GetTempFileName não é capaz de garantir que o nome do arquivo seja exclusivo.

Somente os 16 bits inferiores do parâmetro uUnique são usados. Isso limita GetTempFileName a um máximo de 65.535 nomes de arquivo exclusivos se os parâmetros lpPathName e lpPrefixString permanecerem os mesmos.

Devido ao algoritmo usado para gerar nomes de arquivo, GetTempFileName pode ter um desempenho ruim ao criar um grande número de arquivos com o mesmo prefixo. Nesses casos, é recomendável que você construa nomes de arquivo exclusivos com base em GUIDs.

Arquivos temporários cujos nomes foram criados por essa função não são excluídos automaticamente. Para excluir esses arquivos, chame DeleteFile.

Para evitar problemas resultantes ao converter uma cadeia de caracteres ANSI, um aplicativo deve chamar a função CreateFile para criar um arquivo temporário.

No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (SMB) 3.0	Sim
TFO (Failover transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo, consulte Criando e usando um arquivo temporário.

Observação

O cabeçalho fileapi.h define GetTempFileName como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll