Função LockFileEx (fileapi.h)

Artigo
03/05/2024

Bloqueia o arquivo especificado para acesso exclusivo pelo processo de chamada. Esta função pode operar de forma síncrona ou assíncrona e pode solicitar um bloqueio exclusivo ou compartilhado.

Sintaxe

BOOL LockFileEx(
  [in]      HANDLE       hFile,
  [in]      DWORD        dwFlags,
            DWORD        dwReserved,
  [in]      DWORD        nNumberOfBytesToLockLow,
  [in]      DWORD        nNumberOfBytesToLockHigh,
  [in, out] LPOVERLAPPED lpOverlapped
);

Parâmetros

[in] hFile

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

[in] dwFlags

Esse parâmetro pode ser um ou mais dos valores a seguir.

Valor	Significado
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	A função solicita um bloqueio exclusivo. Caso contrário, ele solicitará um bloqueio compartilhado.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	A função retornará imediatamente se não for possível adquirir o bloqueio solicitado. Caso contrário, ele aguarda.

dwReserved

Parâmetro reservado; deve ser definido como zero.

[in] nNumberOfBytesToLockLow

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

[in] nNumberOfBytesToLockHigh

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

[in, out] lpOverlapped

Um ponteiro para uma estrutura OVERLAPPED que a função usa com a solicitação de bloqueio. Essa estrutura, que é necessária, contém o deslocamento de arquivo do início do intervalo de bloqueio. Você deve inicializar o membro hEvent para um identificador válido ou zero.

Retornar valor

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

O bloqueio de uma região de um arquivo é usado para adquirir acesso compartilhado ou 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.

O bloqueio de uma parte de um arquivo para acesso exclusivo nega a todos os outros processos acesso de leitura e gravação à região especificada do arquivo. Bloquear uma região que vai além da posição atual do fim do arquivo não é um erro.

Bloquear uma parte de um arquivo para acesso compartilhado nega a todos os processos o acesso de gravação à região especificada do arquivo, incluindo o processo que primeiro bloqueia a região. Todos os processos podem ler a região bloqueada.

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

A função LockFileEx opera de forma assíncrona se o identificador de arquivo foi aberto para E/S assíncrona, a menos que o sinalizador LOCKFILE_FAIL_IMMEDIATELY seja especificado. Se um bloqueio exclusivo for solicitado para um intervalo de um arquivo que já tenha um bloqueio compartilhado ou exclusivo, a função retornará o erro ERROR_IO_PENDING. O sistema sinalizará o evento especificado na estrutura OVERLAPPED após a concessão do bloqueio. Para determinar quando o bloqueio foi concedido, use a função GetOverlappedResult ou uma das funções de espera. Para obter mais informações, consulte E/S síncrona e assíncrona.

Se o identificador de arquivo não tiver sido aberto para E/S assíncrona e o bloqueio não estiver disponível, essa chamada aguardará até que o bloqueio seja concedido ou ocorra um erro, a menos que o sinalizador LOCKFILE_FAIL_IMMEDIATELY seja especificado.

Bloqueios exclusivos não podem sobrepor uma região bloqueada existente de um arquivo. Os bloqueios compartilhados podem sobrepor uma região bloqueada, desde que os bloqueios mantidos nessa região sejam bloqueios compartilhados. Um bloqueio compartilhado poderá sobrepor um bloqueio exclusivo se ambos os bloqueios forem criados usando o mesmo identificador de arquivo. Quando um bloqueio compartilhado se sobrepõe a um bloqueio exclusivo, o único acesso possível é uma leitura pelo proprietário dos bloqueios. Se o mesmo intervalo estiver bloqueado com um bloqueio exclusivo e compartilhado, duas operações de desbloqueio serão necessárias para desbloquear a região; a primeira operação de desbloqueio desbloqueia o bloqueio exclusivo, a segunda operação de desbloqueio desbloqueia o bloqueio compartilhado.

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 bloqueados quando ele for encerrado. Se isso não for feito, o acesso a esses arquivos poderá ser negado se o sistema operacional ainda não os desbloqueou.

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

Requisito	Valor
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