LockFileEx 함수(fileapi.h)

아티클
08/23/2023

호출 프로세스의 배타적 액세스를 위해 지정된 파일을 잠급니다. 이 함수는 동기적으로 또는 비동기적으로 작동할 수 있으며 배타적 잠금 또는 공유 잠금을 요청할 수 있습니다.

구문

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

매개 변수

[in] hFile

파일에 대한 핸들입니다. 핸들은 GENERIC_READ 또는GENERIC_WRITE 액세스 권한으로 만들어졌어야 합니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

[in] dwFlags

이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값	의미
LOCKFILE_EXCLUSIVE_LOCK 0x00000002	함수는 배타적 잠금을 요청합니다. 그렇지 않으면 공유 잠금을 요청합니다.
LOCKFILE_FAIL_IMMEDIATELY 0x00000001	함수는 요청된 잠금을 획득할 수 없는 경우 즉시 반환됩니다. 그렇지 않으면 대기합니다.

dwReserved

예약된 매개 변수; 를 0으로 설정해야 합니다.

[in] nNumberOfBytesToLockLow

잠글 바이트 범위 길이의 하위 32비트입니다.

[in] nNumberOfBytesToLockHigh

잠글 바이트 범위 길이의 상위 32비트입니다.

[in, out] lpOverlapped

함수가 잠금 요청과 함께 사용하는 OVERLAPPED 구조체에 대한 포인터입니다. 필요한 이 구조체에는 잠금 범위 시작 부분의 파일 오프셋이 포함됩니다. hEvent 멤버를 유효한 핸들 또는 0으로 초기화해야 합니다.

반환 값

함수가 성공하면 반환 값은 0이 아닌 값(TRUE)입니다.

함수가 실패하면 반환 값은 0(FALSE)입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

파일의 영역 잠금은 이 파일 핸들을 사용하여 지정된 지역에 대한 공유 또는 배타적 액세스를 얻는 데 사용됩니다. 파일 핸들이 잠금 프로세스에서 만든 프로세스에 의해 상속되는 경우 자식 프로세스에는 잠긴 지역에 대한 액세스 권한이 부여되지 않습니다. 잠금 프로세스가 파일을 두 번째로 열면 영역 잠금을 해제할 때까지 이 두 번째 핸들을 통해 지정된 지역에 액세스할 수 없습니다.

전용 액세스를 위해 파일의 일부를 잠그면 파일의 지정된 영역에 대한 읽기 및 쓰기 액세스가 모두 거부됩니다. 현재 파일 끝 위치를 벗어나는 지역을 잠그는 것은 오류가 아닙니다.

공유 액세스를 위해 파일의 일부를 잠그면 먼저 지역을 잠그는 프로세스를 포함하여 파일의 지정된 영역에 대한 모든 프로세스 쓰기 액세스가 거부됩니다. 모든 프로세스는 잠긴 지역을 읽을 수 있습니다.

파일 영역을 잠그면 매핑된 파일 뷰에서 읽거나 쓰는 것을 방지할 수 없습니다.

lockFileEx 함수는 LOCKFILE_FAIL_IMMEDIATELY 플래그를 지정하지 않는 한 비동기 I/O에 대해 파일 핸들을 연 경우 비동기적으로 작동합니다. 공유 또는 배타적 잠금이 이미 있는 파일 범위에 대해 배타적 잠금이 요청되면 함수는 오류 ERROR_IO_PENDING 반환합니다. 시스템은 잠금이 부여된 후 OVERLAPPED 구조체에 지정된 이벤트에 신호를 보냅니다. 잠금이 부여된 시기를 확인하려면 GetOverlappedResult 함수 또는 대기 함수 중 하나를 사용합니다. 자세한 내용은 동기 및 비동기 I/O를 참조하세요.

비동기 I/O에 대해 파일 핸들을 열지 않고 잠금을 사용할 수 없는 경우 이 호출은 LOCKFILE_FAIL_IMMEDIATELY 플래그를 지정하지 않는 한 잠금이 부여되거나 오류가 발생할 때까지 기다립니다.

배타적 잠금은 파일의 기존 잠긴 영역과 겹칠 수 없습니다. 공유 잠금은 해당 지역에 보관된 잠금이 공유 잠금인 경우 잠긴 영역과 겹칠 수 있습니다. 동일한 파일 핸들을 사용하여 두 잠금을 모두 만든 경우 공유 잠금이 배타적 잠금과 겹칠 수 있습니다. 공유 잠금이 배타적 잠금과 겹치는 경우 가능한 유일한 액세스는 잠금 소유자가 읽는 것입니다. 동일한 범위가 배타적 잠금 및 공유 잠금으로 잠겨 있는 경우 지역의 잠금을 해제하려면 두 가지 잠금 해제 작업이 필요합니다. 첫 번째 잠금 해제 작업은 배타적 잠금을 잠금 해제하고, 두 번째 잠금 해제 작업은 공유 잠금을 잠금 해제합니다.

프로세스가 잠긴 파일의 일부로 종료되거나 미해결 잠금이 있는 파일을 닫으면 운영 체제에서 잠금이 잠금 해제됩니다. 그러나 운영 체제에서 이러한 잠금을 해제하는 데 걸리는 시간은 사용 가능한 시스템 리소스에 따라 달라집니다. 따라서 프로세스가 종료 시 잠긴 모든 파일의 잠금을 명시적으로 해제하는 것이 좋습니다. 이 작업을 수행하지 않으면 운영 체제에서 아직 잠금을 해제하지 않은 경우 이러한 파일에 대한 액세스가 거부될 수 있습니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	Yes

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll