IoCreateFileEx 함수(ntddk.h)

아티클
03/08/2023

IoCreateFileEx 루틴은 새 파일 또는 디렉터리를 만들거나 기존 파일, 디바이스, 디렉터리 또는 볼륨을 열고 호출자에게 파일 개체에 대한 핸들을 제공합니다. 파일 시스템 필터 드라이버(레거시 필터 드라이버)는 이 루틴을 호출합니다.

구문

NTSTATUS IoCreateFileEx(
  [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,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

매개 변수

[out] FileHandle

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

[in] DesiredAccess

호출자가 파일 또는 디렉터리에 필요한 액세스 유형을 지정하는 플래그 비트 마스크( ACCESS_MASK 참조)입니다. 이 시스템 정의 DesiredAccess 플래그 집합은 파일 개체에 대해 다음과 같은 특정 액세스 권한을 결정합니다.

DesiredAccess 플래그	의미
DELETE	파일을 삭제할 수 있습니다.
FILE_READ_DATA	데이터를 파일에서 읽을 수 있습니다.
FILE_READ_ATTRIBUTES	아래에 설명된 FileAttributes 플래그를 읽을 수 있습니다.
FILE_READ_EA	파일과 연결된 EA(확장 특성)를 읽을 수 있습니다.
READ_CONTROL	파일과 연결된 ACL(액세스 제어 목록) 및 소유권 정보를 읽을 수 있습니다.
FILE_WRITE_DATA	데이터를 파일에 쓸 수 있습니다.
FILE_WRITE_ATTRIBUTES	FileAttributes 플래그를 작성할 수 있습니다.
FILE_WRITE_EA	파일과 연결된 EA를 작성할 수 있습니다.
FILE_APPEND_DATA	파일에 데이터를 추가할 수 있습니다.
WRITE_DAC	파일과 연결된 DACL(임의 액세스 제어 목록)을 작성할 수 있습니다.
WRITE_OWNER	파일과 연결된 소유권 정보를 작성할 수 있습니다.
SYNCHRONIZE	호출자는 반환된 FileHandle 이 신호됨 상태로 설정될 때까지 대기하여 I/O 작업의 완료를 동기화할 수 있습니다. CreateOptions FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT 플래그가 설정된 경우 이 플래그를 설정해야 합니다.
FILE_EXECUTE	시스템 페이징 I/O를 사용하여 파일에서 메모리로 데이터를 읽을 수 있습니다.

또는 디렉터리를 나타내지 않는 파일 개체의 경우 다음 제네릭 ACCESS_MASK 플래그 중 하나 이상을 지정할 수 있습니다. STANDARD_RIGHTS_XXX 플래그는 시스템 개체에 보안을 적용하는 데 사용되는 미리 정의된 시스템 값입니다. 이러한 제네릭 플래그를 이전 테이블의 추가 플래그와 결합할 수도 있습니다.

파일 값에 대한 원하는 액세스	DesiredAccess 플래그에 매핑
GENERIC_READ	STANDARD_RIGHTS_READ, FILE_READ_DATA, FILE_READ_ATTRIBUTES, FILE_READ_EA, SYNCHRONIZE.
GENERIC_WRITE	STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_WRITE_ATTRIBUTES, FILE_WRITE_EA, FILE_APPEND_DATA, SYNCHRONIZE.
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, SYNCHRONIZE, FILE_READ_ATTRIBUTES, FILE_EXECUTE.

디렉터리(FILE_DIRECTORY_FILE CreateOptions 플래그가 설정됨)의 경우 다음 ACCESS_MASK 플래그 중 하나 이상을 지정할 수 있으며, 앞에서 설명한 호환 플래그와 결합할 수도 있습니다.

디렉터리 값에 대한 원하는 액세스	의미
FILE_LIST_DIRECTORY	디렉터리의 파일을 나열할 수 있습니다.
FILE_TRAVERSE	디렉터리를 트래버스할 수 있습니다. 즉, 파일의 경로 이름에 속할 수 있습니다.

FILE_READ_DATA, FILE_WRITE_DATA, FILE_EXECUTE 및 FILE_APPEND_DATA DesiredAccess 플래그는 디렉터리 파일을 만들거나 여는 작업과 호환되지 않습니다.

[in] ObjectAttributes

InitializeObjectAttributes 루틴에 의해 이미 초기화된 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 호출자가 시스템 프로세스 컨텍스트에서 실행 중인 경우 이 매개 변수는 NULL일 수 있습니다. 그렇지 않으면 호출자는 InitializeObjectAttributes 호출에서 OBJ_KERNEL_HANDLE 특성을 설정해야 합니다. 파일 개체에 대한 이 구조체의 멤버는 다음과 같습니다.

멤버	값
ULONG 길이	제공된 ObjectAttributes 데이터의 바이트 수입니다. 이 값은 적어도 `sizeof(OBJECT_ATTRIBUTES)`이어야 합니다.
PUNICODE_STRING ObjectName	만들거나 열 파일의 이름을 포함하는 버퍼링된 유니코드 문자열에 대한 포인터입니다. 이 값은 RootDirectory에서 지정한 디렉터리를 기준으로 하는 파일의 이름이 아니면 정규화된 파일 사양이어야 합니다. 예를 들어 "\Device\Floppy1\myfile.dat" 또는 "?? \B:\myfile.dat"는 플로피 디스크 드라이브 드라이버와 오버레이 파일 시스템이 이미 로드되어 있는 한 정규화된 파일 사양일 수 있습니다. (참고: "??"는 "\DosDevices"를 Win32 개체 네임스페이스의 이름으로 바꿉니다. "\DosDevices"는 계속 작동하지만 개체 관리자가 "??"를 더 빠르게 변환합니다.)
HANDLE RootDirectory	IoCreateFileEx에 대한 이전 호출에서 가져온 디렉터리에 대한 선택적 핸들입니다. 이 값이 NULL인 경우 ObjectName 멤버는 대상 파일의 전체 경로를 포함하는 정규화된 파일 사양이어야 합니다. 이 값이 NULL이 아닌 경우 ObjectName 멤버는 이 디렉터리를 기준으로 파일 이름을 지정합니다.
PSECURITY_DESCRIPTOR SecurityDescriptor	파일에 적용할 선택적 보안 설명자입니다. 이러한 보안 설명자로 지정된 ACL은 파일을 만들 때만 적용됩니다. 파일을 만들 때 값이 NULL 이면 파일에 배치된 ACL은 파일 시스템에 종속됩니다. 대부분의 파일 시스템은 호출자의 기본 ACL과 결합된 부모 디렉터리 파일에서 이러한 ACL의 일부를 전파합니다.
ULONG 특성	파일 개체 특성을 제어하는 플래그 집합입니다. 호출자가 시스템 프로세스 컨텍스트에서 실행 중인 경우 이 매개 변수는 0일 수 있습니다. 그렇지 않으면 호출자가 OBJ_KERNEL_HANDLE 플래그를 설정해야 합니다. 호출자는 필요에 따라 OBJ_CASE_INSENSITIVE 플래그를 설정할 수 있습니다. 이는 이름 조회 코드가 정확한 일치 검색을 수행하는 대신 ObjectName 의 대/소문자를 무시해야 함을 나타냅니다.

[out] IoStatusBlock

최종 완료 상태 수신하는 형식 IO_STATUS_BLOCK 변수 및 요청된 작업에 대한 정보를 가리키는 포인터입니다. IoCreateFileEx에서 반환되는 경우 변수의 정보 멤버에는 다음 값 중 하나가 포함됩니다.

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

명시적으로 지정된 특성은 파일을 만들거나, 대체하거나, 경우에 따라 덮어쓸 때만 적용됩니다. 기본적으로 이 값은 FILE_ATTRIBUTE_NORMAL, 다른 플래그 또는 호환 플래그의 조합(비트 OR 연산을 통해)으로 재정의할 수 있습니다. 가능한 FileAttributes 플래그에는 다음이 포함됩니다.

FileAttributes 플래그	의미
FILE_ATTRIBUTE_NORMAL	표준 특성이 있는 파일을 만들어야 합니다.
FILE_ATTRIBUTE_READONLY	읽기 전용 파일을 만들어야 합니다.
FILE_ATTRIBUTE_HIDDEN	숨겨진 파일을 만들어야 합니다.
FILE_ATTRIBUTE_SYSTEM	시스템 파일을 만들어야 합니다.
FILE_ATTRIBUTE_ARCHIVE	파일이 보관되도록 표시되어야 합니다.
FILE_ATTRIBUTE_TEMPORARY	임시 파일을 만들어야 합니다.

[in] ShareAccess

호출자가 원하는 파일에 대한 공유 액세스 유형을 0 또는 1 또는 다음 플래그의 조합으로 지정합니다. 단독 액세스를 요청하려면 이 매개 변수를 0으로 설정합니다. options 매개 변수에 IO_IGNORE_SHARE_ACCESS_CHECK 플래그를 지정하면 I/O 관리자가 ShareAccess 매개 변수를 무시합니다. 그러나 파일 시스템은 여전히 액세스 검사를 수행할 수 있습니다. 따라서 IO_IGNORE_SHARE_ACCESS_CHECK 플래그를 사용하는 경우에도 이 매개 변수에 대해 원하는 공유 모드를 지정해야 합니다. 위반 오류를 공유하지 않도록 하려면 다음 공유 액세스 플래그를 모두 지정합니다.

ShareAccess 플래그	의미
FILE_SHARE_READ	다른 스레드의 파일 만들기 호출에서 읽기 액세스를 위해 파일을 열 수 있습니다.
FILE_SHARE_WRITE	다른 스레드의 파일 만들기 호출을 통해 쓰기 액세스를 위해 파일을 열 수 있습니다.
FILE_SHARE_DELETE	다른 스레드의 파일 만들기 호출에 의해 액세스 삭제를 위해 파일을 열 수 있습니다.

디바이스 드라이버 및 중간 드라이버는 일반적으로 ShareAccess 를 0으로 설정하므로 호출자에게 열려 있는 파일에 대한 단독 액세스 권한을 부여합니다.

[in] Disposition

파일이 이미 있을 때 파일을 처리하는 방법을 결정하는 값입니다. 처리는 다음 중 하나일 수 있습니다.

값	의미
FILE_SUPERSEDE	파일이 이미 있는 경우 지정된 파일로 바꿉니다. 존재하지 않는 경우 지정된 파일을 만듭니다.
FILE_CREATE	파일이 이미 있는 경우 요청에 실패하고 지정된 파일을 만들거나 열지 않습니다. 존재하지 않는 경우 지정된 파일을 만듭니다.
FILE_OPEN	파일이 이미 있는 경우 새 파일을 만드는 대신 엽니다. 존재하지 않는 경우 요청에 실패하고 새 파일을 만들지 않습니다.
FILE_OPEN_IF	파일이 이미 있는 경우 엽니다. 존재하지 않는 경우 지정된 파일을 만듭니다.
FILE_OVERWRITE	파일이 이미 있는 경우 파일을 열고 덮어씁니다. 존재하지 않는 경우 요청을 실패합니다.
FILE_OVERWRITE_IF	파일이 이미 있는 경우 파일을 열고 덮어씁니다. 존재하지 않는 경우 지정된 파일을 만듭니다.

[in] CreateOptions

파일을 만들거나 열 때 적용할 옵션을 다음 플래그의 호환 가능한 조합으로 지정합니다.

CreateOptions 플래그	의미
FILE_DIRECTORY_FILE(0x00000001)	만들거나 여는 파일은 디렉터리 파일입니다. 이 플래그를 사용하면 처리 매개 변수를 FILE_CREATE, FILE_OPEN 또는 FILE_OPEN_IF 중 하나로 설정해야 합니다. 이 플래그와 호환되는 CreateOptions 플래그는 다음과 같습니다. FILE_SYNCHRONOUS_IO_ALERT, FILE_SYNCHRONOUS_IO_NONALERT, FILE_WRITE_THROUGH, FILE_OPEN_FOR_BACKUP_INTENT 및 FILE_OPEN_BY_FILE_ID.
FILE_WRITE_THROUGH(0x00000002)	요청된 쓰기 작업이 완료된 것으로 간주되기 전에 파일에 데이터를 쓰는 시스템 서비스, 파일 시스템 및 드라이버는 실제로 데이터를 파일로 전송해야 합니다.
FILE_SEQUENTIAL_ONLY(0x00000004)	파일에 대한 모든 액세스는 순차적으로 적용됩니다.
FILE_NO_INTERMEDIATE_BUFFERING(0x00000008)	파일은 드라이버의 내부 버퍼에서 캐시하거나 버퍼링할 수 없습니다. 이 플래그는 DesiredAccessFILE_APPEND_DATA 플래그와 호환되지 않습니다.
FILE_SYNCHRONOUS_IO_ALERT(0x00000010)	파일에 대한 모든 작업은 동기적으로 수행됩니다. 호출자를 대신하여 대기하는 모든 대기는 경고에서 조기 종료될 수 있습니다. 또한 이 플래그는 I/O 시스템에서 파일 위치 컨텍스트를 유지 관리하도록 합니다. 이 플래그를 설정하면 I/O 관리자가 파일 개체를 동기화 개체로 사용하도록 DesiredAccess SYNCHRONIZE 플래그도 설정해야 합니다.
FILE_SYNCHRONOUS_IO_NONALERT(0x00000020)	파일에 대한 모든 작업은 동기적으로 수행됩니다. 시스템에서 I/O 큐를 동기화하기 위한 대기 및 완료에는 경고가 적용되지 않습니다. 또한 이 플래그는 I/O 시스템에서 파일 위치 컨텍스트를 유지 관리하도록 합니다. 이 플래그를 설정하면 I/O 관리자가 파일 개체를 동기화 개체로 사용하도록 DesiredAccess SYNCHRONIZE 플래그도 설정해야 합니다.
FILE_NON_DIRECTORY_FILE(0x00000040)	열려 있는 파일이 디렉터리 파일이거나 이 호출이 실패하면 안 됩니다. 열려 있는 파일 개체는 데이터 파일을 나타낼 수 있습니다. 논리적, 가상 또는 물리적 디바이스 또는 볼륨입니다.
FILE_CREATE_TREE_CONNECTION(0x00000080)	네트워크를 통해 열려면 이 파일에 대한 트리 연결을 만듭니다.
FILE_COMPLETE_IF_OPLOCKED(0x00000100)	호출자의 스레드를 차단하는 대신 대상 파일이 잠겨 있는 경우 대체 성공 코드로 이 작업을 즉시 완료합니다. 파일이 잠겨 있으면 다른 호출자가 이미 네트워크를 통해 파일에 액세스할 수 있습니다.
FILE_NO_EA_KNOWLEDGE(0x00000200)	열려 있는 기존 파일의 확장 특성이 호출자가 파일을 제대로 해석하기 위해 확장 특성을 이해해야 함을 나타내는 경우 호출자가 확장 특성을 처리하는 방법을 이해하지 못하기 때문에 이 요청에 실패합니다.
FILE_OPEN_REMOTE_INSTANCE(0x00000400)	시스템 사용을 위해 예약됨; 를 사용하지 마세요.
FILE_RANDOM_ACCESS(0x00000800)	파일에 대한 액세스는 임의일 수 있으므로 파일 시스템 또는 운영 체제에서 파일에서 순차적 미리 읽기 작업을 수행해서는 안 됩니다.
FILE_DELETE_ON_CLOSE(0x00001000)	마지막 핸들이 FltClose에 전달되면 파일을 삭제합니다.
FILE_OPEN_BY_FILE_ID(0x00002000)	ID로 파일을 열고 있습니다. 파일 이름에는 디바이스 이름과 파일을 여는 데 사용할 64비트 ID가 포함됩니다.
FILE_OPEN_FOR_BACKUP_INTENT(0x000004000)	백업 의도를 위해 파일이 열리고 있습니다. 따라서 시스템은 특정 액세스 권한을 검사 호출자에게 파일의 보안 설명자에 대해 DesiredAccess 입력을 확인하기 전에 파일에 대한 적절한 액세스 권한을 부여해야 합니다.
FILE_NO_COMPRESSION(0x00008000)	부모 디렉터리에서 FILE_ATTRIBUTE_COMPRESSED 상속을 표시하지 않습니다. 이렇게 하면 압축된 것으로 표시된 디렉터리에서 압축되지 않은 파일을 만들 수 있습니다.
FILE_OPEN_REQUIRING_OPLOCK(0x00010000)	파일이 열리고 파일의 기회 잠금(oplock)이 단일 원자성 작업으로 요청됩니다. 파일 시스템은 만들기 작업을 수행하기 전에 oplock을 확인하고 만들기 작업이 기존 oplock을 중단하는 경우 STATUS_CANNOT_BREAK_OPLOCK 반환 코드로 만들기 작업이 실패합니다. 이 플래그는 Windows 7, Windows Server 2008 R2 이상 Windows 운영 체제에서 사용할 수 있습니다.
FILE_DISALLOW_EXCLUSIVE(0x00020000)	기존 파일을 열 때 FILE_SHARE_READ 지정되지 않고 파일 시스템 액세스 검사에서 호출자에게 파일에 대한 쓰기 권한을 부여하지 않는 경우 STATUS_ACCESS_DENIED 이 열기에 실패합니다. 이는 Windows 7 이전의 기본 동작이었습니다.
FILE_SESSION_AWARE(0x00040000)	세션 인식으로 파일 또는 디바이스가 열리고 있습니다. 이 플래그를 지정하지 않으면 세션 0에서 실행되는 프로세스에서 세션별 디바이스(예: RemoteFX USB 리디렉션을 사용하는 디바이스)를 열 수 없습니다. 이 플래그는 세션 0에 없는 호출자에게는 영향을 주지 않습니다. 이 플래그는 Windows 서버 버전에서만 지원됩니다. 이 플래그는 Windows Server 2012 전에 지원되지 않습니다.
FILE_RESERVE_OPFILTER(0x00100000)	이 플래그를 사용하면 애플리케이션이 필터 기회 잠금(oplock)을 요청하여 다른 애플리케이션이 공유 위반을 가져오지 못하도록 할 수 있습니다. 열려 있는 핸들이 이미 있는 경우 만들기 요청은 STATUS_OPLOCK_NOT_GRANTED 실패합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.
FILE_OPEN_REPARSE_POINT(0x00200000)	재분석 지점이 있는 파일을 열고 파일에 대한 일반 재분석 지점 처리를 무시합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.
FILE_OPEN_NO_RECALL(0x00400000)	오프라인 스토리지 또는 가상화를 수행하는 필터에 이 열기의 결과로 파일의 내용을 회수하지 않도록 지시합니다.
FILE_OPEN_FOR_FREE_SPACE_QUERY(0x00800000)	이 플래그는 호출 스레드와 연결된 사용자를 캡처하도록 파일 시스템에 지시합니다. 반환된 핸들을 사용하여 FltQueryVolumeInformation 또는 ZwQueryVolumeInformationFile에 대한 후속 호출은 호출자가 사용할 수 있는 여유 공간을 계산하기 위해 당시 호출 사용자가 아닌 캡처된 사용자를 가정합니다. 이는 다음 FsInformationClass 값에 적용됩니다. FileFsSizeInformation, FileFsFullSizeInformation 및 FileFsFullSizeInformationEx.

[in, optional] EaBuffer

파일에 적용할 EA(확장 특성) 정보가 포함된 FILE_FULL_EA_INFORMATION 형식의 호출자 제공 변수에 대한 포인터입니다. 디바이스 및 중간 드라이버의 경우 이 매개 변수는 NULL이어야 합니다.

[in] EaLength

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

[in] CreateFileType

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

[in, optional] InternalParameters

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

[in] Options

만들기 요청을 생성하는 동안 사용할 옵션을 지정합니다. 다음 비트 플래그 값 중 0개 이상을 사용할 수 있습니다.

옵션 플래그	의미
IO_FORCE_ACCESS_CHECK	I/O 관리자는 파일의 보안 설명자에 대해 만들기 요청을 검사 합니다. 자세한 내용은 설명 부분을 참조하세요.
IO_IGNORE_SHARE_ACCESS_CHECK	I/O 관리자는 파일 개체를 만든 후 공유 액세스 검사를 수행해서는 안 됩니다. 그러나 파일 시스템은 여전히 이러한 검사를 수행할 수 있습니다.
IO_STOP_ON_SYMLINK	파일을 열거나 만드는 동안 접합, 기호 링크 또는 전역 재분석 지점이 발견되면 I/O 관리자는 STATUS_STOPPED_ON_SYMLINK 반환합니다. 또한 REPARSE_DATA_BUFFER 구조체는 IoStatusBlock-Information>에 반환됩니다. 호출자는 REPARSE_DATA_BUFFER 구조를 해제합니다.
IO_OPEN_TARGET_DIRECTORY	파일의 부모 디렉터리를 엽니다.

[in, optional] DriverContext

이전에 IoInitializeDriverCreateContext 루틴에 의해 초기화된 IO_DRIVER_CREATE_CONTEXT 구조체에 대한 선택적 포인터입니다. IO_DRIVER_CREATE_CONTEXT 구조체를 사용하여 IoCreateFileEx 및 FltCreateFileEx2 루틴 에 추가 매개 변수를 전달할 수 있습니다. 자세한 내용은 다음 설명 섹션을 참조하세요.

반환 값

IoCreateFileEx 는 STATUS_SUCCESS 반환하거나 다음 중 하나와 같은 적절한 NTSTATUS 값을 반환합니다.

반환 코드	설명
STATUS_INVALID_DEVICE_OBJECT_PARAMETER	DriverContext 매개 변수가 NULL이 아니고 지정된 디바이스 개체가 파일 또는 디렉터리 이름에 지정된 볼륨의 파일 시스템 드라이버 스택에 연결되지 않은 경우 IoCreateFileEx는 이 상태 값을 반환합니다. 이 디바이스 개체는 IO_DRIVER_CREATE_CONTEXT 구조체의 DeviceObjectHint 멤버에 의해 지정됩니다. 자세한 내용은 IO_DRIVER_CREATE_CONTEXT 참조하세요.
STATUS_MOUNT_POINT_NOT_RESOLVED	DriverContext 매개 변수가 NULL이 아니고 파일 또는 디렉터리 이름에 지정된 디바이스 개체가 연결된 볼륨 이외의 볼륨으로 확인되는 탑재 지점이 포함되어 있으면 IoCreateFileEx는 이 상태 값을 반환합니다. 이 디바이스 개체는 IO_DRIVER_CREATE_CONTEXT 구조체의 DeviceObjectHint 멤버에 의해 지정됩니다. 자세한 내용은 IO_DRIVER_CREATE_CONTEXT 참조하세요.
STATUS_OBJECT_PATH_SYNTAX_BAD	IoCreateFileEx는 ObjectAttributes 매개 변수에 RootDirectory 멤버가 없지만 OBJECT_ATTRIBUTES 구조의 ObjectName 멤버가 빈 문자열이거나 OBJECT_NAME_PATH_SEPARATOR 문자를 포함하지 않은 경우 이 상태 값을 반환합니다. 개체 경로에 대한 잘못된 구문을 나타냅니다.
STATUS_STOPPED_ON_SYMLINK	IoCreateFileEx는 Options 매개 변수 플래그 IO_STOP_ON_SYMLINK 설정되고 파일을 열거나 만드는 동안 기호 링크가 있는 경우 이 상태 값을 반환합니다.

IoCreateFileEx 루틴에서 오류 상태 반환하는 경우 호출자는 IoStatusBlock 매개 변수를 확인하여 오류의 원인에 대한 추가 정보를 찾을 수 있습니다.

IoCreateFileEx는 STATUS_FILE_LOCK_CONFLICT 반환 값 또는 IoStatusBlock 매개 변수가 가리키는 IO_STATUS_BLOCK 구조체의 Status 멤버로 반환할 수 있습니다. NTFS 로그 파일이 가득 차 있고 IoCreateFileEx 가 이 상황을 처리하려고 하는 동안 오류가 발생하는 경우에만 발생합니다.

설명

IoCreateFileEx 루틴은 IoCreateFile 루틴 및 IoCreateFileSpecifyDeviceObjectHint 루틴과 비슷하지만 IoCreateFileEx 루틴의 DriverContext 매개 변수를 통해 추가 만들기 매개 변수(ECP), 디바이스 개체 힌트 및 트랜잭션 정보에 대한 액세스를 비롯한 추가 기능을 제공합니다. 이러한 구조 기반 매개 변수에 대한 자세한 내용은 IO_DRIVER_CREATE_CONTEXT 참조하세요.

파일 시스템 필터 드라이버는 IoCreateFileEx 를 호출하여 지정된 디바이스 개체, 아래에 연결된 필터 및 파일 시스템에만 만들기 요청을 보냅니다. 드라이버 스택에서 지정된 디바이스 개체 위에 연결된 필터는 만들기 요청을 받지 않습니다. 그러나 IO_DRIVER_CREATE_CONTEXT 구조체의 DeviceObjectHint 멤버( DriverContext 매개 변수를 통해 전달됨)가 NULL인 경우 요청은 스택의 맨 위로 이동하고 모든 필터 및 파일 시스템에서 수신됩니다.

I/O 요청이 드라이버 스택의 맨 위로 이동하지 않는 경우, 즉 DriverContext 매개 변수가 NULL 이 아니고 유효한 디바이스 개체가 IO_DRIVER_CREATE_CONTEXT 구조체의 DeviceObjectHint 멤버에 의해 지정된 경우 다음 제한이 적용됩니다.

IoCreateFileEx 루틴에 전달된 파일 이름 경로에 탑재 지점이 포함된 경우 탑재 지점은 파일 또는 디렉터리가 있는 동일한 볼륨으로 resolve 합니다.

IoCreateFileEx에서 가져온 핸들은 후속 호출에서 파일 또는 파일 개체의 상태 또는 특성 내에서 데이터를 조작하는 데 사용할 수 있습니다. IoCreateFileEx에서 가져온 모든 핸들은 결국 ZwClose를 호출하여 해제해야 합니다.

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

입력 ObjectAttributes 매개 변수의 ObjectName 멤버에 제공된 정규화된 경로 이름입니다.
입력 ObjectAttributes 매개 변수의 RootDirectory 멤버에 있는 핸들을 기준으로 하는 경로 이름입니다. (이 핸들은 디렉터리 파일을 나타낼 수 있습니다.)

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

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

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

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

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

Options 매개 변수에 IO_IGNORE_SHARE_ACCESS_CHECK 지정되면 I/O 관리자는 ShareAccess 매개 변수를 무시합니다. 그러나 파일 시스템은 여전히 액세스 검사를 수행할 수 있습니다. 따라서 IO_IGNORE_SHARE_ACCESS_CHECK 플래그를 사용하는 경우에도 ShareAccess 매개 변수에 대해 원하는 공유 모드를 지정해야 합니다.

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

FILE_OVERWRITE_IF 및 FILE_SUPERSEDE 처리 값은 비슷합니다. IoCreateFileEx가 기존 파일과 이러한 처리 값 중 하나를 사용하여 호출되면 파일이 대체됩니다.

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

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

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

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING 플래그는 파일 시스템이 호출자를 대신하여 중간 버퍼링을 수행하지 못하도록 합니다. 이 값을 지정하면 호출자의 매개 변수에 특정 제한이 Zw로 지정됩니다. 다음 을 포함한 파일 루틴:

ZwReadFile 또는 ZwWriteFile에 전달된 선택적 ByteOffset은 섹터 크기의 정수(정수 배수)여야 합니다.
ZwReadFile 또는 ZwWriteFile에 전달된 길이는 섹터 크기의 정수여야 합니다. 길이가 정확히 섹터 크기인 버퍼에 읽기 작업을 지정하면 전송 중에 파일의 끝에 도달한 경우 해당 버퍼로 전송되는 상당한 바이트 수가 줄어들 수 있습니다.
버퍼는 기본 디바이스의 맞춤 요구 사항에 따라 정렬되어야 합니다. 이 정보는 IoCreateFileEx 를 호출하여 물리적 디바이스를 나타내는 파일 개체에 대한 핸들을 가져온 다음, 해당 핸들을 사용하여 ZwQueryInformationFile 을 호출하여 가져올 수 있습니다. 시스템 FILE_XXX_ALIGNMENT 값 목록은 DEVICE_OBJECT 참조하세요.
FileInformationClass 매개 변수가 FilePositionInformation으로 설정된 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 플래그를 지정하지 않고IoCreateFileEx에서 재분석 지점이 있는 파일을 열려고 하면 파일에 대해 일반적인 재분석 지점 처리가 수행됩니다. 반면에 FILE_OPEN_REPARSE_POINT 플래그를 지정하면 정상적인 재분석 처리가 수행 되지 않고IoCreateFileEx 에서 재분석 지점 파일을 직접 열려고 시도합니다. 두 경우 모두 열려 있는 작업이 성공하면 IoCreateFileEx 는 STATUS_SUCCESS 반환합니다. 그렇지 않으면 루틴이 NTSTATUS 오류 코드를 반환합니다. IoCreateFileEx 는 STATUS_REPARSE 반환하지 않습니다.

CreateOptions FILE_OPEN_REQUIRING_OPLOCK 플래그는 파일을 열고 타사에서 파일을 열고 공유 위반을 가져올 수 있는 oplock을 요청하는 시점 사이의 시간을 제거합니다. 애플리케이션은 IoCreateFileEx 에서 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은 이 만들기 작업으로 인해 손상되지 않습니다.

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

FILE_OPEN_REQUIRING_OPLOCK 플래그는 Windows 7, Windows Server 2008 R2 이상 Windows 운영 체제에서 사용할 수 있습니다. 이 플래그를 구현하는 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를 수행합니다.

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

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

IoCreateFileEx 를 사용하여 볼륨에 대한 핸들을 가져올 수 있습니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	ntddk.h(Ntddk.h, Ntifs.h, FltKernel.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL