Função LockFile (fileapi.h)

Artigo
08/23/2023

Bloqueia o arquivo especificado para acesso exclusivo pelo processo de chamada.

Para especificar opções adicionais, por exemplo, criar um bloqueio compartilhado ou para a operação de bloqueio em caso de falha, use a função LockFileEx .

Sintaxe

BOOL LockFile(
  [in] HANDLE hFile,
  [in] DWORD  dwFileOffsetLow,
  [in] DWORD  dwFileOffsetHigh,
  [in] DWORD  nNumberOfBytesToLockLow,
  [in] DWORD  nNumberOfBytesToLockHigh
);

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] dwFileOffsetLow

Os 32 bits de ordem inferior do deslocamento de bytes inicial no arquivo em que o bloqueio deve começar.

[in] dwFileOffsetHigh

Os 32 bits de ordem alta do deslocamento de bytes inicial no arquivo em que o bloqueio deve começar.

[in] nNumberOfBytesToLockLow

Os 32 bits de ordem inferior do comprimento do intervalo de bytes a serem bloqueados.

[in] nNumberOfBytesToLockHigh

A ordem alta de 32 bits do comprimento do intervalo de bytes a ser bloqueado.

Valor retornado

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

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

Comentários

Se a chamada para LockFile for concluída de forma síncrona, uma entrada de conclusão poderá não ser enfileirada quando uma porta de conclusão estiver associada ao identificador de arquivo.

A função UnlockFile desbloqueia uma região de arquivo bloqueada pelo LockFile.

Bloquear uma região de um arquivo fornece aos threads do processo de bloqueio acesso exclusivo à região especificada usando esse identificador de arquivo. Se o identificador de arquivo for herdado por um processo criado pelo processo de bloqueio, o processo filho não receberá acesso à região bloqueada. Se o processo de bloqueio abrir o arquivo uma segunda vez, ele não poderá acessar a região especificada por meio desse segundo identificador até desbloquear a região.

Bloquear uma região de um arquivo não impede a leitura ou gravação de uma exibição de arquivo mapeada.

Você pode bloquear bytes que estão além do final do arquivo atual. Isso é útil para coordenar a adição de registros ao final de um arquivo.

Bloqueios exclusivos não podem sobrepor uma região bloqueada existente de um arquivo. Para obter mais informações, consulte LockFileEx.

Se LockFile não puder bloquear uma região de um arquivo, ele retornará zero imediatamente. Ele não bloqueia. Para emitir uma solicitação de bloqueio de arquivo que será bloqueada até que o bloqueio seja adquirido, use LockFileEx sem o sinalizador LOCKFILE_FAIL_IMMEDIATELY .

Se um processo terminar com uma parte de um arquivo bloqueado ou fechar um arquivo com bloqueios pendentes, os bloqueios serão desbloqueados pelo sistema operacional. No entanto, o tempo necessário para o sistema operacional desbloquear esses bloqueios depende dos recursos do sistema disponíveis. Portanto, é recomendável que o processo desbloqueie explicitamente todos os arquivos que ele bloqueou quando terminar. Se isso não for feito, o acesso a esses arquivos poderá ser negado se o sistema operacional ainda não os tiver desbloqueado.

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 Anexando um arquivo a outro arquivo.

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