NtWriteFile 함수(ntifs.h)
ZwWriteFile 루틴은 열려 있는 파일에 데이터를 씁니다.
통사론
__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
매개 변수
[in] FileHandle
파일 개체에 대한 핸들입니다. 이 핸들은 NtCreateFile 또는 NtOpenFile성공적으로 호출하여 생성됩니다.
[in, optional] Event
필요에 따라 쓰기 작업이 완료된 후 신호 상태로 설정할 이벤트 개체에 대한 핸들입니다. 디바이스 및 중간 드라이버는 이 매개 변수를 NULL로 설정해야 합니다.
[in, optional] ApcRoutine
이 매개 변수는 예약되어 있습니다. 디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
[in, optional] ApcContext
이 매개 변수는 예약되어 있습니다. 디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
[out] IoStatusBlock
요청된 쓰기 작업에 대한 최종 완료 상태 및 정보를 수신하는 IO_STATUS_BLOCK 구조체에 대한 포인터입니다. Information 멤버는 파일에 실제로 기록된 바이트 수를 받습니다.
[in] Buffer
파일에 쓸 데이터를 포함하는 호출자 할당 버퍼에 대한 포인터입니다.
[in] Length
Buffer가리키는 버퍼의 크기(바이트)입니다.
[in, optional] ByteOffset
쓰기 작업을 시작하기 위해 파일의 시작 바이트 오프셋을 지정하는 변수에 대한 포인터입니다. Length 및 ByteOffset이 현재 파일 끝 표시를 지나 쓰기 작업을 지정할 있는 경우 NtWriteFile 자동으로 파일을 확장하고 파일 끝 표시를 업데이트합니다. 이러한 이전 및 새 파일 끝 표시 사이에 명시적으로 기록되지 않은 바이트는 0으로 정의됩니다.
NtCreateFile 호출이 DesiredAccess 플래그 FILE_APPEND_DATA만 설정할 경우 ByteOffset 무시됩니다. 지정된 버퍼Length 바이트의 데이터는 파일의 현재 끝에서부터 작성됩니다.
NtCreateFile 호출이 CreateOptions 플래그, FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT 중 하나를 설정할 있는 경우 I/O 관리자는 현재 파일 위치를 유지 관리합니다. 이 경우 NtWriteFile 호출자는 명시적 ByteOffset 값 대신 현재 파일 위치 오프셋을 사용하도록 지정할 수 있습니다. 이 사양은 다음 방법 중 하나를 사용하여 만들 수 있습니다.
- *HighPart 멤버가 -1 설정되고 LowPart 멤버가 시스템 정의 값 FILE_USE_FILE_POINTER_POSITION 설정된 LARGE_INTEGER 값에 대한 포인터를 지정합니다.
- ByteOffset대한 NULL 포인터를 전달합니다.
NtWriteFile I/O 관리자가 유지 관리하는 현재 파일 위치를 사용하는 경우 쓰기 작업을 완료할 때 쓴 바이트 수를 추가하여 현재 파일 위치를 업데이트합니다.
I/O 관리자가 현재 파일 위치를 유지 관리하는 경우에도 호출자는 명시적 ByteOffset 값을 NtWriteFile전달하여 이 위치를 다시 설정할 수 있습니다. 이렇게 하면 현재 파일 위치가 해당 ByteOffset값으로 자동으로 변경되고 쓰기 작업이 수행된 다음 실제로 작성된 바이트 수에 따라 위치가 업데이트됩니다. 이 기술은 호출자에게 원자성 검색 및 쓰기 서비스를 제공합니다.
HighPart -1 설정되고 LowPart FILE_WRITE_TO_END_OF_FILE 설정된 LARGE_INTEGER 값에 대한 포인터를 ByteOffset에 대해 지정하여 파일의 현재 끝에서 쓰기 작업을 시작할 수도 있습니다. 이는 I/O 관리자가 현재 파일 위치를 유지 관리하는지 여부에 관계없이 작동합니다.
[in, optional] Key
디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
반환 값
NtWriteFile 성공에 대한 STATUS_SUCCESS 반환하거나 실패시 적절한 NTSTATUS 오류 코드를 반환합니다.
발언
NtWriteFile 호출자는 DesiredAccess 매개 변수에 설정된 FILE_WRITE_DATA, FILE_APPEND_DATA 또는 GENERIC_WRITE 플래그를 사용하여 NtCreateFile 호출했어야 합니다. 파일에 대한 FILE_APPEND_DATA 액세스만 있으면 호출자가 현재 파일 끝 표시를 제외하고 파일의 아무 곳이나 쓸 수 없지만 파일에 대한 FILE_WRITE_DATA 액세스가 있으면 호출자가 파일의 끝부분에 쓰거나 그 너머로 쓰는 것을 배제할 수 없습니다.
NtCreateFile에 대한 이전 호출에서 CreateOptions 플래그 FILE_NO_INTERMEDIATE_BUFFERING 설정할 경우 Length 및 ByteOffset 매개 변수를 NtWriteFile 섹터 크기의 정수여야 합니다. 자세한 내용은 NtCreateFile참조하세요.
NtWriteFileByteOffset, 현재 파일 위치 또는 파일 끝 표시에서 파일에 대한 쓰기 작업을 시작합니다. BufferLength 바이트를 작성하면 쓰기 작업이 종료됩니다. 필요한 경우 파일 길이를 확장하고 파일 끝 표시를 다시 설정합니다.
호출자가 DesiredAccess SYNCHRONIZE 플래그 집합으로 파일을 연 경우 호출자는 이 루틴이 지정된 FileHandle 신호 상태로 설정할 때까지 기다릴 수 있습니다.
드라이버는 시스템 프로세스의 컨텍스트에서 NtWriteFile 호출해야 합니다.
- 드라이버는 NtWriteFile전달하는 파일 핸들을 만듭니다.
- NtWriteFile 드라이버에서 만든 이벤트를 통해 I/O 완성을 드라이버에 알릴 수 있습니다.
- NtWriteFile 드라이버가 NtWriteFile전달하는 APC 콜백 루틴을 통해 드라이버에 I/O 완성을 알릴 수 있습니다.
파일 및 이벤트 핸들은 핸들이 만들어지는 프로세스 컨텍스트에서만 유효합니다. 따라서 보안 허점을 방지하기 위해 드라이버는 드라이버가 있는 프로세스 컨텍스트 대신 시스템 프로세스의 컨텍스트에서 NtWriteFile 전달하는 파일 또는 이벤트 핸들을 만들어야 합니다.
마찬가지로 APC를 통해 I/O 완료를 드라이버에 알릴 경우 시스템 프로세스의 컨텍스트에서 NtWriteFile 호출해야 합니다. APC는 I/O 요청을 실행하는 스레드의 컨텍스트에서 항상 발생하기 때문입니다. 드라이버가 시스템 프로세스 이외의 프로세스 컨텍스트에서 NtWriteFile 호출하는 경우 APC가 무기한 지연되거나 원래 스레드가 경고 대기 상태로 전환되지 않을 수 있으므로 전혀 발생하지 않을 수 있습니다.
파일 작업에 대한 자세한 내용은 드라이버 파일 사용참조하세요.
NtWriteFile 호출자는 IRQL = PASSIVE_LEVEL 및 사용하도록 설정된 특수 커널 APC가 있는실행되어야 합니다.
이 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwWriteFile" 대신 "NtWriteFile" 이름을 사용해야 합니다.
커널 모드 드라이버의 호출의 경우 NtXxx 및 ZwXxx 버전의 Windows Native System Services 루틴은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. NtXxxZwXxx 루틴 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴 Nt 및 Zw 버전 사용참조하세요.
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 |
| 대상 플랫폼 | 보편적 |
| 헤더 | ntifs.h(Wdm.h, Ntddk.h, Ntifs.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL(설명 섹션 참조) |
| DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs, PowerIrpDDis |