IoCreateFile 함수(wdm.h)

아티클
02/07/2025

IoCreateFile 루틴은 새 파일 또는 디렉터리를 만들거나 기존 파일, 디바이스, 디렉터리 또는 볼륨을 열어 호출자에게 파일 개체에 대한 핸들을 제공합니다.

통사론

NTSTATUS IoCreateFile(
  [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              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

매개 변수

[out] FileHandle

호출에 성공하면 파일 핸들을 받는 변수에 대한 포인터입니다. 핸들이 더 이상 사용되지 않는 경우 드라이버는 ZwClose 핸들을 닫아야 합니다.

[in] DesiredAccess

호출자가 필요로 하는 파일 또는 디렉터리에 대한 액세스 유형을 지정하는 플래그의 비트 마스크입니다. 이 매개 변수에 대한 자세한 내용과 플래그 값 목록은 IoCreateFileExDesiredAccess 매개 변수를 참조하세요.

[in] ObjectAttributes

InitializeObjectAttributes사용하여 이미 초기화된 불투명 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 자세한 내용 및 각 구조체 멤버에 대한 설명은 IoCreateFileExObjectAttributes 매개 변수를 참조하세요.

[out] IoStatusBlock

요청된 작업에 대한 최종 완료 상태 및 정보를 수신하는 IO_STATUS_BLOCK 구조체에 대한 포인터입니다. IoCreateFileExIoStatusBlock 매개 변수를 참조하세요.

[in, optional] AllocationSize

필요에 따라 파일에 대한 초기 할당 크기(바이트)를 지정합니다. 파일이 생성, 덮어쓰기 또는 대체되지 않는 한 0이 아닌 값은 적용되지 않습니다.

[in] FileAttributes

명시적으로 지정된 특성은 파일을 만들거나, 대체하거나, 경우에 따라 덮어쓸 때만 적용됩니다. 기본적으로 이 값은 FILE_ATTRIBUTE_NORMAL Wdm.h에 정의된 하나 이상의 FILE_ATTRIBUTE_XXX 플래그의 ORed 조합으로 재정의할 수 있습니다. IoCreateFile사용할 수 있는 플래그 목록은 CreateFile참조하세요.

[in] ShareAccess

호출자가 필요로 하는 파일에 대한 공유 액세스 유형을 0 또는 1 또는 플래그 조합으로 지정합니다. 자세한 내용 및 플래그 목록은 IoCreateFileExShareAccess 매개 변수를 참조하세요.

[in] Disposition

파일이 이미 있는지 여부에 따라 수행할 작업을 결정하는 값을 지정합니다. 가능한 값 목록은 IoCreateFileEx처리 매개 변수를 참조하세요.

[in] CreateOptions

파일을 만들거나 열 때 적용할 옵션을 지정합니다. 이 매개 변수는 IoCreateFileExCreateOptions 매개 변수에 나열되고 설명된 플래그의 호환 가능한 조합입니다.

[in, optional] EaBuffer

디바이스 및 중간 드라이버의 경우 이 매개 변수는 NULL 포인터여야 합니다.

[in] EaLength

디바이스 및 중간 드라이버의 경우 이 매개 변수는 0이어야 합니다.

[in] CreateFileType

드라이버는 CreateFileTypeNone 이 매개 변수를 설정해야 합니다.

[in, optional] InternalParameters

드라이버는 NULL 이 매개 변수를 설정해야 합니다.

[in] Options

만들기 요청을 만드는 동안 사용할 옵션을 지정합니다. 가능한 옵션 목록은 IoCreateFileExOptions 매개 변수를 참조하세요.

반환 값

IoCreateFile STATUS_SUCCESS 또는 적절한 오류 상태를 반환합니다. NTSTATUS 값입니다. 가능한 반환 코드 목록은 IoCreateFileEx반환 값 섹션을 참조하세요.

발언

IoCreateFileEx 루틴은 IoCreateFile 루틴과 유사하지만 추가 만들기 매개 변수(ECP), 디바이스 개체 및 트랜잭션 정보에 대한 액세스를 포함하여 IoCreateFile 루틴보다 더 큰 기능을 제공합니다.

IoCreateFile 가져온 핸들은 후속 호출에서 파일 또는 파일 개체의 상태 또는 특성 내에서 데이터를 조작하는 데 사용할 수 있습니다.

IoCreateFile사용하여 만들거나 열 파일의 이름을 지정하는 두 가지 다른 방법이 있습니다.

입력 ObjectAttributes의 ObjectName 멤버에 제공된 정규화된 경로 이름으로
입력 ObjectAttributes의 RootDirectory 멤버에서 핸들이 나타내는 디렉터리 파일을 기준으로 하는 경로 이름으로

특정 DesiredAccess 플래그 및 플래그 조합에는 다음과 같은 효과가 있습니다.

호출자가 반환된 FileHandle대기하여 I/O 완성을 동기화하려면 SYNCHRONIZE 플래그를 설정해야 합니다. 그렇지 않으면 디바이스 또는 중간 드라이버인 호출자는 이벤트 개체를 사용하여 I/O 완성을 동기화해야 합니다.
FILE_APPEND_DATA 및 SYNCHRONIZE 플래그만 설정된 경우 호출자는 파일의 끝에만 쓸 수 있으며 파일에 대한 쓰기에 대한 오프셋 정보는 무시됩니다. 그러나 이 유형의 쓰기 작업에 필요한 경우 파일이 자동으로 확장됩니다.
파일에 대한 FILE_WRITE_DATA 플래그를 설정하면 파일 끝 이후의 쓰기도 가능합니다. 이 형식의 쓰기에 대해서도 파일이 자동으로 확장됩니다.
FILE_EXECUTE 및 SYNCHRONIZE 플래그만 설정된 경우 호출자는 반환된 FileHandle사용하여 파일의 데이터를 직접 읽거나 쓸 수 없습니다. 즉, 명령 및 데이터 액세스에 대한 응답으로 파일의 모든 작업이 시스템 호출기를 통해 발생합니다. 디바이스 및 중간 드라이버는 desiredAccess FILE_EXECUTE 플래그를 설정해서는 안 됩니다.

ShareAccess 매개 변수는 개별 스레드가 동일한 파일에 동시에 액세스할 수 있는지 여부를 결정합니다. 두 파일 열기 모두 지정된 방식으로 파일에 액세스할 수 있는 권한이 있는 경우 파일을 성공적으로 열고 공유할 수 있습니다. IoCreateFile 원래 호출자가 FILE_SHARE_READ, FILE_SHARE_WRITE 또는 FILE_SHARE_DELETE 지정하지 않으면 파일에 대해 다른 열린 작업을 수행할 수 없습니다. 즉, 원래 호출자에게 파일에 대한 단독 액세스 권한이 부여됩니다.

공유 파일을 성공적으로 열려면 파일에 대한 요청된 DesiredAccessDesiredAccess 및 ZwClose아직 릴리스되지 않은 모든 이전 열기의 ShareAccess 사양과 호환되어야 합니다. 즉, 지정된 파일에 대해 IoCreateFile 지정한 DesiredAccess 파일의 다른 오프너가 허용하지 않은 액세스와 충돌해서는 안 됩니다.

처리 값 FILE_SUPERSEDE 호출자에게 기존 파일 개체에 대한 DELETE 액세스 권한이 있어야 합니다. 그렇다면 기존 파일의 FILE_SUPERSEDE 사용하여 IoCreateFile 성공적으로 호출하면 해당 파일이 효과적으로 삭제된 다음 다시 만들어집니다. 즉, 파일이 다른 스레드에서 이미 열려 있는 경우 FILE_SHARE_DELETE 플래그가 설정된 ShareAccess매개 변수를 지정하여 파일을 열었습니다. 이러한 유형의 처리는 덮어쓰기 파일의 POSIX 스타일과 일치합니다.

FILE_OVERWRITE_IF 값과 FILE_SUPERSEDE 처리 값은 비슷합니다. IoCreateFile 기존 파일과 이러한 처리 값 중 하나를 사용하여 호출되면 파일이 바뀝 있습니다.

파일을 덮어쓰는 것은 다음을 제외하고 대체 작업과 의미상 동일합니다.

호출자는 액세스 권한을 삭제하는 대신 파일에 대한 쓰기 권한이 있어야 합니다. 이는 파일이 다른 스레드에서 이미 열려 있는 경우 입력 ShareAccess설정된 FILE_SHARE_WRITE 플래그를 사용하여 파일을 열었다는 것을 의미합니다.
지정된 파일 특성은 파일에 이미 있는 특성과 논리적으로 ORed됩니다. 즉, 다른 스레드에서 파일을 이미 연 경우 IoCreateFile 후속 호출자는 기존 FileAttributes 플래그를 사용하지 않도록 설정할 수 없지만 동일한 파일에 대해 추가 플래그를 사용하도록 설정할 수 있습니다.

CreateOptions FILE_DIRECTORY_FILE 값은 만들거나 열 파일이 디렉터리 파일임을 지정합니다. 디렉터리 파일을 만들 때 파일 시스템은 디스크에 해당 특정 파일 시스템의 디스크 내 구조에 대한 빈 디렉터리를 나타내는 적절한 구조를 만듭니다. 이 옵션을 지정하고 열려는 지정된 파일이 디렉터리 파일이 아니거나 호출자가 CreateOptions 또는 처리 값을 일관성이 없도록 지정한 경우 IoCreateFile 호출이 실패합니다.

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 플래그를 사용하면 파일 시스템이 호출자를 대신하여 중간 버퍼링을 수행할 수 없습니다. 이 값을 지정하면 다음을 포함하여 호출자의 매개 변수에 대한 특정 제한 사항이 ZwXxx파일 루틴에 배치됩니다.

ZwReadFile 또는 ZwWriteFile 전달되는 선택적 ByteOffset 섹터 크기의 정수여야 합니다.
ZwReadFile 또는 ZwWriteFile 전달되는 Length 섹터 크기의 정수여야 합니다. 길이가 정확히 섹터 크기인 버퍼에 읽기 작업을 지정하면 전송 중에 파일의 끝에 도달한 경우 해당 버퍼로 전송되는 유효 바이트 수가 줄어들 수 있습니다.
버퍼는 기본 디바이스의 맞춤 요구 사항에 따라 정렬되어야 합니다. 이 정보는 IoCreateFile 호출하여 물리적 디바이스를 나타내는 파일 개체에 대한 핸들을 가져온 다음, 해당 핸들을 사용하여 ZwQueryInformationFile 호출하여 가져올 수 있습니다. 시스템 FILE_XXX_ALIGNMENT 값 목록은 DEVICE_OBJECT참조하세요.
filePositionInformation FileInformationClass 매개 변수로 설정된 ZwSetInformationFile 호출은 섹터 크기의 정수 계열인 오프셋을 지정해야 합니다.

이름에서 알 수 있듯이 상호 배타적인 CreateOptions FILE_SYNCHRONOUS_IO_ALERT 및 FILE_SYNCHRONOUS_IO_NONALERT 반환된 FileHandle참조하는 파일 개체를 통해 발생하는 한 파일의 모든 I/O 작업이 동기되도록 지정합니다. 이러한 파일의 모든 I/O는 반환된 핸들을 사용하여 모든 스레드에서 직렬화됩니다. 이러한 CreateOptions중 하나를 사용하면 I/O 관리자가 파일 개체를 동기화 개체로 사용할 수 있도록 DesiredAccess SYNCHRONIZE 플래그를 설정해야 합니다. 이러한 CreateOptions 설정하면 I/O 관리자는 파일 개체의 "파일 위치 컨텍스트"를 내부, 현재 파일 위치 오프셋으로 유지 관리합니다. 이 오프셋은 ZwReadFile ZwWriteFile 호출에 사용할 수 있습니다. ZwQueryInformationFile 및 ZwSetInformationFile사용하여 해당 위치를 쿼리하거나 설정할 수도 있습니다.

CreateOptions FILE_OPEN_REPARSE_POINT 플래그가 지정되지 않고 IoCreateFile 재분석 지점이 있는 파일을 열려고 하면 파일에 대해 정상적인 재분석 지점 처리가 수행됩니다. 반면에 FILE_OPEN_REPARSE_POINT 플래그가 지정된 경우 정상적인 재구매 처리가 수행되지 않으며 IoCreateFile 다시 분석 지점 파일을 직접 열려고 시도합니다. 두 경우 모두 열기 작업이 성공한 경우 IoCreateFile STATUS_SUCCESS 반환합니다. 그렇지 않으면 루틴은 NTSTATUS 오류 코드를 반환합니다. IoCreateFile STATUS_REPARSE 반환하지 않습니다.

CreateOptions FILE_OPEN_REQUIRING_OPLOCK 플래그는 파일을 열고 타사에서 파일을 열고 공유 위반을 가져올 수 있는 oplock을 요청하는 시점 사이의 시간을 제거합니다. 애플리케이션은 IoCreateFile FILE_OPEN_REQUIRING_OPLOCK 플래그를 사용한 다음 oplock을 요청할 수 있습니다. 이렇게 하면 공유 위반을 유발하는 나중에 열려 있는 요청에 대해 oplock 소유자에게 알림을 받게 됩니다.

Windows 7에서 애플리케이션이 FILE_OPEN_REQUIRING_OPLOCK 플래그를 사용할 때 파일에 다른 핸들이 있는 경우 STATUS_OPLOCK_NOT_GRANTED 함께 만들기 작업이 실패합니다. 이 제한은 더 이상 Windows 8부터 존재하지 않습니다.

이 만들기 작업이 파일에 이미 있는 oplock을 중단하는 경우 FILE_OPEN_REQUIRING_OPLOCK 플래그를 설정하면 만들기 작업이 STATUS_CANNOT_BREAK_OPLOCK 실패합니다. 기존 oplock은 이 만들기 작업으로 인해 손상되지 않습니다.

FILE_OPEN_REQUIRING_OPLOCK 플래그를 사용하는 애플리케이션은 이 호출이 성공한 후 oplock을 요청해야 합니다. 그렇지 않으면 일반적인 oplock 처리의 이점 없이 파일을 열려는 모든 후속 시도가 차단됩니다. 마찬가지로 이 호출이 성공하지만 후속 oplock 요청이 실패하는 경우 이 플래그를 사용하는 애플리케이션은 oplock 요청이 실패했음을 감지한 후 핸들을 닫아야 합니다.

FILE_OPEN_REQUIRING_OPLOCK 플래그는 Windows 7, Windows Server 2008 R2 이상 버전의 Windows에서 사용할 수 있습니다. Windows 7에서 이 플래그를 구현하는 Microsoft 파일 시스템은 NTFS, FAT 및 exFAT입니다.

FILE_RESERVE_OPFILTER CreateOptions 플래그를 사용하면 애플리케이션이 수준 1, 일괄 처리 또는 필터 oplock을 요청하여 다른 애플리케이션에서 공유 위반을 방지할 수 있습니다. 그러나 FILE_RESERVE_OPFILTER 필터 oplock에만 유용합니다. 이를 사용하려면 다음 단계를 수행해야 합니다.

FILE_RESERVE_OPFILTER CreateOptions, 정확히 FILE_READ_ATTRIBUTES DesiredAccess , 정확히 FILE_SHARE_READ ShareAccess 만들기 요청 발급 | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
- 열려 있는 핸들이 이미 있는 경우 STATUS_OPLOCK_NOT_GRANTED 사용하여 만들기 요청이 실패하고 다음 요청된 oplock도 실패합니다.
- 더 많은 액세스 권한 또는 더 적은 공유로 열면 STATUS_OPLOCK_NOT_GRANTED 오류가 발생합니다.
만들기 요청이 성공하면 oplock을 요청합니다.
파일에 대한 다른 핸들을 열어 I/O를 수행합니다.

옵션 IO_NO_PARAMETER_CHECKING 플래그는 드라이버가 사용자 모드 애플리케이션에서 시작한 작업을 대신하여 커널 모드 만들기 요청을 실행하는 경우에 유용할 수 있습니다. 요청은 사용자 모드 컨텍스트 내에서 발생하므로 I/O 관리자는 기본적으로 제공된 매개 변수 값을 검색하므로 매개 변수가 커널 모드 주소인 경우 액세스 위반이 발생할 수 있습니다. 이 플래그를 사용하면 호출자가 이 기본 동작을 재정의하고 액세스 위반을 방지할 수 있습니다.

사용자 모드에서 시작된 만들기 요청의 경우 드라이버가 IoCreateFileOptions 매개 변수에서 IO_NO_PARAMETER_CHECKING 및 IO_FORCE_ACCESS_CHECK 설정하는 경우 ObjectAttributes 매개 변수에서도 OBJ_FORCE_ACCESS_CHECK 설정해야 합니다. 이 플래그에 대한 자세한 내용은 OBJECT_ATTRIBUTES특성 멤버를 참조하세요.

NTFS는 FILE_RESERVE_OPFILTER 구현하는 유일한 Microsoft 파일 시스템입니다.

시스템 프로세스 이외의 프로세스 컨텍스트에서 실행되는 드라이버 루틴은 IoCreateFileObjectAttributes 매개 변수에 대한 OBJ_KERNEL_HANDLE 특성을 설정해야 합니다. 이렇게 하면 IoCreateFile 반환된 핸들을 커널 모드에서만 실행되는 프로세스로 제한합니다. 그렇지 않으면 드라이버가 실행 중인 컨텍스트의 프로세스에서 핸들에 액세스할 수 있습니다. 드라이버는 InitializeObjectAttributes 호출하여 다음과 같이 OBJ_KERNEL_HANDLE 특성을 설정할 수 있습니다.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

요구 사항

요구	값
대상 플랫폼	보편적
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)