NtCreateFile 함수(winternl.h)
새 파일 또는 디렉터리를 만들거나 기존 파일, 디바이스, 디렉터리 또는 볼륨을 엽니다.
이 함수는 WDK(Windows 드라이버 키트)에 설명된 ZwCreateFile 함수와 동일한 사용자 모드입니다.
통사론
__kernel_entry NTSTATUS NtCreateFile(
[out] PHANDLE FileHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in, optional] PLARGE_INTEGER AllocationSize,
[in] ULONG FileAttributes,
[in] ULONG ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] PVOID EaBuffer,
[in] ULONG EaLength
);
매개 변수
[out] FileHandle
호출에 성공하면 파일 핸들을 받는 변수에 대한 포인터입니다.
[in] DesiredAccess
호출자가 파일 또는 디렉터리에 필요한 액세스 유형을 나타내는 ACCESS_MASK 값입니다. 시스템 정의 DesiredAccess 플래그 집합은 파일 개체에 대한 다음과 같은 특정 액세스 권한을 결정합니다.
NtCreateFile 호출자는 디렉터리 파일을 나타내지 않는 파일 개체에 대해 이전 DesiredAccess 플래그 목록의 추가 호환 플래그가 있는 비트 OR을 사용하여 다음 중 하나 또는 조합을 지정할 수 있습니다.
FILE_GENERIC_EXECUTE 값은 디바이스 및 중간 드라이버와 관련이 없습니다.
STANDARD_RIGHTS_XXX 시스템 개체에 보안을 적용하는 데 사용되는 미리 정의된 시스템 값입니다.
CreateOptions 매개 변수와 함께 표시된 대로 디렉터리 파일을 열거나 만들려면 NtCreateFile 호출자는 이전 DesiredAccess 플래그 목록에서 하나 이상의 호환 플래그가 있는 비트 OR을 사용하여 다음 중 하나 또는 조합을 지정할 수 있습니다.
| 값 | 의미 |
|---|---|
|
디렉터리의 파일을 나열할 수 있습니다. |
|
디렉터리를 트래버스할 수 있습니다. 즉, 파일의 경로 이름에 속할 수 있습니다. |
[in] ObjectAttributes
InitializeObjectAttributes사용하여 이미 초기화된 구조체에 대한 포인터입니다. 파일 개체에 대한 이 구조체의 멤버는 다음과 같습니다.
[out] IoStatusBlock
요청된 작업에 대한 최종 완료 상태 및 정보를 받는 변수에 대한 포인터입니다. NtCreateFile반환할 때 Information 멤버에는 다음 값 중 하나가 포함됩니다.
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
파일의 초기 할당 크기(바이트)입니다. 파일이 생성, 덮어쓰기 또는 대체되지 않는 한 0이 아닌 값은 적용되지 않습니다.
[in] FileAttributes
파일 특성입니다. 명시적으로 지정된 특성은 파일을 만들거나, 대체하거나, 경우에 따라 덮어쓸 때만 적용됩니다. 기본적으로 이 값은 Wdm.h 및 NtDdk.h에 정의된 하나 이상의 FILE_ATTRIBUTE_xxxx 플래그의 ORed 조합으로 재정의할 수 있는 FILE_ATTRIBUTE_NORMAL.
[in] ShareAccess
호출자가 파일에서 사용하려는 공유 액세스 유형(0) 또는 다음 값 중 하나 또는 조합으로 사용됩니다.
자세한 내용은 Windows SDK를 참조하세요.
[in] CreateDisposition
파일이 이미 있는지 여부에 따라 다음 값 중 하나로 수행할 작업을 지정합니다.
[in] CreateOptions
다음 플래그의 호환 가능한 조합으로 파일을 만들거나 열 때 적용할 옵션입니다.
[in] EaBuffer
확장 특성을 전달하는 데 사용되는 EA 버퍼에 대한 포인터입니다.
[in] EaLength
EA 버퍼의 길이입니다.
반환 값
NtCreateFileSTATUS_SUCCESS 또는 적절한 오류 상태를 반환합니다. 오류 상태를 반환하는 경우 호출자는 IoStatusBlock확인하여 오류의 원인에 대한 자세한 정보를 찾을 수 있습니다. 이 검사를 간소화하기 위해 애플리케이션은 NT_SUCCESS, NT_ERROR및 NT_WARNING 매크로를 사용할 수 있습니다.
발언
NtCreateFile지정된 핸들은 후속 호출에서 파일 또는 파일 개체의 상태 또는 특성 내에서 데이터를 조작하는 데 사용할 수 있습니다.
NtCreateFile사용하여 만들거나 열 파일의 이름을 지정하는 두 가지 다른 방법이 있습니다.
- 입력 ObjectAttributes의 ObjectName 멤버에 제공된 정규화된 경로 이름으로
- 입력 ObjectAttributes의 RootDirectory 멤버에서 핸들이 나타내는 디렉터리 파일을 기준으로 하는 경로 이름으로
특정 DesiredAccess 플래그 및 플래그 조합에는 다음과 같은 효과가 있습니다.
- 호출자가 반환된 FileHandle대기하여 I/O 완성을 동기화하려면 SYNCHRONIZE 플래그를 설정해야 합니다.
- DesiredFlags
0을 전달하는 것은 유효하지 않습니다. - FILE_APPEND_DATA 및 SYNCHRONIZE 플래그만 설정된 경우 호출자는 파일의 끝에만 쓸 수 있으며 파일에 대한 쓰기에 대한 오프셋 정보는 무시됩니다. 그러나 이 유형의 쓰기 작업에 필요한 경우 파일이 자동으로 확장됩니다.
- 파일에 대한 FILE_WRITE_DATA 플래그를 설정하면 파일 끝 이후의 쓰기도 발생할 수 있습니다. 이 형식의 쓰기에 대해서도 파일이 자동으로 확장됩니다.
- FILE_EXECUTE 및 SYNCHRONIZE 플래그만 설정된 경우 호출자는 반환된 FileHandle사용하여 파일의 데이터를 직접 읽거나 쓸 수 없습니다. 즉, 파일의 모든 작업은 명령 및 데이터 액세스에 대한 응답으로 시스템 호출기를 통해 발생합니다.
ShareAccess 매개 변수는 개별 스레드가 동일한 파일에 동시에 액세스할 수 있는지 여부를 결정합니다. 두 파일 열기 모두 지정된 방식으로 파일에 액세스할 수 있는 권한이 있는 경우 파일을 성공적으로 열고 공유할 수 있습니다. NtCreateFile 원래 호출자가 FILE_SHARE_READ, FILE_SHARE_WRITE또는 FILE_SHARE_DELETE지정하지 않으면 파일에 대해 다른 열린 작업을 수행할 수 없습니다. 즉, 원래 호출자에게 파일에 대한 단독 액세스 권한이 부여됩니다.
공유 파일을 성공적으로 열려면 요청된 DesiredAccess 매개 변수가 NtClose아직 릴리스되지 않은 모든 이전 열기의 DesiredAccess 및 ShareAccess 사양과 호환되어야 합니다. 즉, 지정된 파일에 대해 NtCreateFile
CreateDisposition 값 FILE_SUPERSEDE 호출자에게 기존 파일 개체에 대한 DELETE 액세스 권한이 있어야 합니다. 그렇다면 기존 파일의 FILE_SUPERSEDE 사용하여 NtCreateFile 성공적으로 호출하면 해당 파일이 효과적으로 삭제된 다음 다시 생성됩니다. 즉, 파일이 다른 스레드에서 이미 열려 있는 경우 FILE_SHARE_DELETE 플래그가 설정된 ShareAccess 매개 변수를 지정하여 파일을 열었습니다.
이러한 유형의 처리는 덮어쓰기 파일의 POSIX 스타일과 일치합니다. CreateDisposition 값 FILE_OVERWRITE_IF 및 FILE_SUPERSEDE 비슷합니다. ZwCreateFile 기존 파일과 이러한 CreateDisposition 값 중 하나를 사용하여 호출되면 파일이 대체됩니다.
파일을 덮어쓰는 것은 다음을 제외하고 대체 작업과 의미상 동일합니다.
- 호출자는 액세스 권한을 삭제하는 대신 파일에 대한 쓰기 권한이 있어야 합니다. 이는 파일이 다른 스레드에서 이미 열려 있는 경우 입력 ShareAccess 매개 변수에 설정된 FILE_SHARE_WRITE 플래그를 사용하여 파일을 열었다는 것을 의미합니다.
- 지정된 파일 특성은 파일에 이미 있는 특성과 논리적으로 ORed됩니다. 즉, 다른 스레드에서 파일을 이미 연 경우 NtCreateFile 후속 호출자는 기존 FileAttributes 플래그를 사용하지 않도록 설정할 수 없지만 동일한 파일에 대해 추가 플래그를 사용하도록 설정할 수 있습니다. 이 덮어쓰기 파일 스타일은 MS-DOS, Windows 3.1 및 OS/2 운영 체제와 일치합니다.
CreateOptionsFILE_DIRECTORY_FILE 값은 만들거나 열 파일이 디렉터리 파일임을 지정합니다. 디렉터리 파일을 만들 때 파일 시스템은 디스크에 해당 특정 파일 시스템의 디스크 내 구조에 대한 빈 디렉터리를 나타내는 적절한 구조를 만듭니다. 이 옵션을 지정하고 열 지정된 파일이 디렉터리 파일이 아니거나 호출자가 CreateOptions 또는 CreateDisposition 값을
CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING 플래그를 사용하면 파일 시스템이 호출자를 대신하여 중간 버퍼링을 수행할 수 없습니다. 이 값을 지정하면 다음을 포함하여 다른 NtXXX파일 루틴에 호출자의 매개 변수에 대한 특정 제한이 적용됩니다.
- NtReadFile 또는 NtWriteFile 함수에 전달되는 선택적 ByteOffset 섹터 크기의 정수여야 합니다.
- NtReadFile 또는 NtWriteFile전달되는 Length 섹터 크기의 정수여야 합니다. 길이가 정확히 섹터 크기인 버퍼에 읽기 작업을 지정하면 전송 중에 파일의 끝에 도달한 경우 해당 버퍼로 전송되는 유효 바이트 수가 줄어들 수 있습니다.
- 버퍼는 기본 디바이스의 맞춤 요구 사항에 따라 조정되어야 합니다. 이 정보는 NtCreateFile 호출하여 물리적 디바이스를 나타내는 파일 개체에 대한 핸들을 가져온 다음 해당 핸들로 NtQueryInformationFile 호출하여 가져올 수 있습니다. 시스템 FILE_XXX_ALIGNMENT 값 목록은 Windows SDK 설명서를 참조하세요.
- filePositionInformation
FileInformationClass 매개 변수로 설정된NtSetInformationFile 호출은 섹터 크기의 정수 계열 오프셋을 지정해야 합니다.
CreateOptions 매개 변수가 FILE_OPEN_REPARSE_POINT 플래그를 지정하고 NtCreateFile 재분석 지점이 있는 파일을 여는 경우 정상적인 재분석 처리가 수행되지 않으며 NtCreateFile 재분석 지점 파일을 직접 열려고 시도합니다. FILE_OPEN_REPARSE_POINT 플래그를 지정하지 않으면 파일에 대한 일반 재처리 지점 처리가 수행됩니다. 두 경우 모두 열기 작업이 성공한 경우 NtCreateFileSTATUS_SUCCESS반환합니다. 그렇지 않으면 오류 코드입니다. NtCreateFile 함수는 STATUS_REPARSE반환하지 않습니다.
CreateOptions 매개 변수의 FILE_OPEN_REQUIRING_OPLOCK 플래그를 사용하면 파일을 열고 타사에서 파일을 열 수 있는 oplock을 요청하는 시점 사이의 시간을 제거하여 공유 위반이 발생할 수 있습니다. 애플리케이션은 NtCreateFileFILE_OPEN_REQUIRING_OPLOCK 플래그를 사용한 다음 oplock을 요청할 수 있습니다. 이렇게 하면 공유 위반을 유발하는 후속 미해결 요청에 대해 oplock 소유자에게 알림을 받습니다.
Windows 7에서 애플리케이션이 이 플래그를 사용할 때 파일에 다른 핸들이 있으면 STATUS_OPLOCK_NOT_GRANTED함께 만들기 작업이 실패합니다. 이 제한은 더 이상 Windows 8부터 존재하지 않습니다.
이 만들기 작업이 파일에 이미 있는 oplock을 중단하는 경우 FILE_OPEN_REQUIRING_OPLOCK 플래그를 설정하면 STATUS_CANNOT_BREAK_OPLOCK인해 만들기 작업이 실패합니다. 기존 oplock은 이 만들기 작업으로 인해 손상되지 않습니다.
이 플래그를 사용하는 애플리케이션은 이 호출이 성공한 후 oplock을 요청해야 합니다. 그렇지 않으면 일반적인 oplock 처리의 이점 없이 파일을 열려는 모든 후속 시도가 차단됩니다. 마찬가지로 이 호출이 성공하지만 후속 oplock 요청이 실패하는 경우 이 플래그를 사용하는 애플리케이션은 oplock 요청이 실패했음을 감지한 후 핸들을 닫아야 합니다.
CreateOptions 매개 변수의 FILE_RESERVE_OPFILTER 플래그를 사용하면 애플리케이션이 수준 1, Batch 또는 Filter oplock을 요청하여 다른 애플리케이션이 공유 위반을 받지 못하도록 할 수 있습니다. 그러나 실질적으로 FILE_RESERVE_OPFILTER 필터 oplock에만 유용합니다. 이를 사용하려면 다음 단계를 완료해야 합니다.
FILE_RESERVE_OPFILTER CreateOptions , 정확히FILE_READ_ATTRIBUTES DesiredAccess, 정확히 ShareAccess 만들기 요청을 실행합니다. 가능한 오류는 다음과 같습니다. - 열려 있는 핸들이 이미 있는 경우 STATUS_OPLOCK_NOT_GRANTED생성 요청이 실패하고 다음 요청된 oplock도 실패합니다.
-
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)FILE_READ_ATTRIBUTES 이상의 액세스 권한으로 열거나 공유하지 않는 경우 STATUS_OPLOCK_NOT_GRANTED요청이 실패합니다.
- 만들기 요청이 성공하면 oplock을 요청합니다.
- 파일에 대한 다른 핸들을 열어 I/O를 수행합니다.
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL) 포함하고 필터 oplock을 중단하지 않는 DesiredAccess 가질 수 있습니다. 그러나 NTFS는 FILE_RESERVE_OPFILTER구현하는 유일한 Microsoft 파일 시스템입니다.
oplock에 대한 자세한 내용은 기회 잠금참조하세요.
WDK 헤더 파일 NtDef.h는 많은 상수 정의뿐만 아니라 InitializeObjectAttributes 매크로에도 필요합니다. 또한
요구 사항
| 요구 | 값 |
|---|---|
| 대상 플랫폼 | Windows |
| 헤더 | winternl.h |
| 라이브러리 | ntdll.lib |
| DLL | ntdll.dll |