Função SetFilePointerEx (fileapi.h)

Artigo
01/30/2024

Move o ponteiro do arquivo especificado.

Sintaxe

BOOL SetFilePointerEx(
  [in]            HANDLE         hFile,
  [in]            LARGE_INTEGER  liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD          dwMoveMethod
);

Parâmetros

[in] hFile

Um manipulador para o arquivo. O identificador de arquivo deve ter sido criado com o direito de acesso GENERIC_READ ou GENERIC_WRITE . Para obter mais informações, consulte Segurança de arquivo e direitos de acesso.

[in] liDistanceToMove

O número de bytes para mover o ponteiro do arquivo. Um valor positivo move o ponteiro para frente no arquivo e um valor negativo move o ponteiro do arquivo para trás.

[out, optional] lpNewFilePointer

Um ponteiro para uma variável para receber o novo ponteiro de arquivo. Se esse parâmetro for NULL, o novo ponteiro de arquivo não será retornado.

[in] dwMoveMethod

O ponto de partida para a movimentação do ponteiro do arquivo. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
FILE_BEGIN 0	O ponto de partida é zero ou o início do arquivo. Se esse sinalizador for especificado, o parâmetro liDistanceToMove será interpretado como um valor não assinado.
FILE_CURRENT 1	O ponto inicial é o valor atual do ponteiro do arquivo.
FILE_END 2	O ponto de partida é a posição atual do fim do arquivo.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

O ponteiro de arquivo retornado por essa função não é usado para operações de leitura e gravação sobrepostas. Para especificar o deslocamento para operações sobrepostas, use os membros Offset e OffsetHigh da estrutura OVERLAPPED .

Você não pode usar a função SetFilePointerEx com um identificador para um dispositivo que não está em contato, como um pipe ou um dispositivo de comunicação. Para determinar o tipo de arquivo para hFile, use a função GetFileType .

Tenha cuidado ao definir o ponteiro do arquivo em um aplicativo multithreaded. Você deve sincronizar o acesso aos recursos compartilhados. Por exemplo, um aplicativo cujos threads compartilham um identificador de arquivo, atualizar o ponteiro do arquivo e ler do arquivo deve proteger essa sequência usando um objeto de seção crítico ou um objeto mutex. Para obter mais informações sobre esses objetos, consulte Objetos de Seção Crítica e Objetos Mutex.

Se o identificador hFile tiver sido aberto com o sinalizador FILE_FLAG_NO_BUFFERING definido, um aplicativo poderá mover o ponteiro do arquivo apenas para posições alinhadas ao setor. Uma posição alinhada ao setor é uma posição que é um número inteiro múltiplo do tamanho do setor do volume. Um aplicativo pode obter o tamanho do setor de um volume chamando a função GetDiskFreeSpace . Se um aplicativo chamar SetFilePointerEx com valores de distância para movimentação que resultam em uma posição que não esteja alinhada ao setor e um identificador aberto com FILE_FLAG_NO_BUFFERING, a função falhará e GetLastError retornará ERROR_INVALID_PARAMETER. Para obter informações adicionais, consulte Buffer de arquivos.

Observe que não é um erro definir o ponteiro do arquivo para uma posição além do final do arquivo. O tamanho do arquivo não aumenta até que você chame a função SetEndOfFile, WriteFile ou WriteFileEx . Uma operação de gravação aumenta o tamanho do arquivo para a posição do ponteiro do arquivo mais o tamanho do buffer gravado, o que resulta na inicialização de zero dos bytes intermediários.

Você pode usar SetFilePointerEx para determinar o comprimento de um arquivo. Para fazer isso, use FILE_END para dwMoveMethod e procure o local zero. O deslocamento de arquivo retornado é o comprimento do arquivo. No entanto, essa prática pode ter efeitos colaterais não intencionais, como falha ao salvar o ponteiro do arquivo atual para que o programa possa retornar a esse local. É mais simples e seguro usar a função GetFileSizeEx .

Você também pode usar SetFilePointerEx para consultar a posição atual do ponteiro do arquivo. Para fazer isso, especifique um método de movimentação de FILE_CURRENT e uma distância de zero.

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

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