다음을 통해 공유


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 구조체 및 요청된 쓰기 작업에 대한 정보를 가리키는 포인터입니다. 정보 멤버는 파일에 실제로 기록된 바이트 수를 받습니다.

[in] Buffer

파일에 쓸 데이터를 포함하는 호출자가 할당한 버퍼에 대한 포인터입니다.

[in] Length

Buffer가 가리키는 버퍼의 크기(바이트) 입니다.

[in, optional] ByteOffset

쓰기 작업을 시작하기 위해 파일의 시작 바이트 오프셋을 지정하는 변수에 대한 포인터입니다. LengthByteOffset이 현재 파일 끝 표시를 지나 쓰기 작업을 지정하는 경우 NtWriteFile은 자동으로 파일을 확장하고 파일 끝 표시를 업데이트합니다. 이러한 이전 및 새 파일 끝 표시 사이에 명시적으로 기록되지 않은 바이트는 0으로 정의됩니다.

NtCreateFile에 대한 호출이 DesiredAccess 플래그만 FILE_APPEND_DATA 설정하면 ByteOffset은 무시됩니다. 지정된 버퍼의 데이터( 길이 바이트)는 현재 파일 끝에서부터 기록됩니다.

NtCreateFile에 대한 호출이 FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT CreateOptions 플래그 중 하나를 설정하는 경우 I/O 관리자는 현재 파일 위치를 유지합니다. 이 경우 NtWriteFile 의 호출자는 명시적 ByteOffset 값 대신 현재 파일 위치 오프셋을 사용할 수 있도록 지정할 수 있습니다. 이 사양은 다음 방법 중 하나를 사용하여 만들 수 있습니다.

  • * HighPart 멤버가 -1로 설정되고 LowPart 멤버가 시스템 정의 값으로 설정된 LARGE_INTEGER 값에 대한 포인터를 FILE_USE_FILE_POINTER_POSITION.
  • 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 설정하는 경우 LengthByteOffset 매개 변수는 섹터 크기의 정수여야 합니다. 자세한 내용은 NtCreateFile을 참조하세요.

NtWriteFileByteOffset, 현재 파일 위치 또는 파일 끝 표시에서 파일에 대한 쓰기 작업을 시작합니다. 버퍼에서 Length 바이트를 작성하면 쓰기 작업이 종료됩니다. 필요한 경우 파일의 길이를 확장하고 파일 끝 표시를 다시 설정합니다.

호출자가 DesiredAccess SYNCHRONIZE 플래그가 설정된 파일을 연 경우 호출자는 이 루틴이 지정된 FileHandle 을 신호 상태로 설정할 때까지 기다릴 수 있습니다.

드라이버는 시스템 프로세스의 컨텍스트에서 다음 세 가지 경우에 NtWriteFile 을 호출해야 합니다.

  • 드라이버는 NtWriteFile에 전달하는 파일 핸들을 만듭니다.
  • NtWriteFile 은 드라이버에서 만든 이벤트를 통해 I/O 완성을 드라이버에 알릴 수 있습니다.
  • NtWriteFile 은 드라이버가 NtWriteFile에 전달하는 APC 콜백 루틴을 통해 I/O 완성을 드라이버에 알릴 수 있습니다.

파일 및 이벤트 핸들은 핸들이 만들어지는 프로세스 컨텍스트에서만 유효합니다. 따라서 보안 허점을 방지하기 위해 드라이버는 드라이버가 있는 프로세스 컨텍스트 대신 시스템 프로세스의 컨텍스트에서 NtWriteFile 에 전달하는 파일 또는 이벤트 핸들을 만들어야 합니다.

마찬가지로 APC는 I/O 요청을 실행하는 스레드의 컨텍스트에서 항상 발생하므로 APC를 통해 I/O 완료를 드라이버에 알릴 경우 시스템 프로세스의 컨텍스트에서 NtWriteFile 을 호출해야 합니다. 드라이버가 시스템 프로세스 이외의 프로세스 컨텍스트에서 NtWriteFile 을 호출하는 경우 APC가 무기한 지연되거나 원래 스레드가 경고 대기 상태로 들어가지 않을 수 있으므로 전혀 실행되지 않을 수 있습니다.

파일 작업에 대한 자세한 내용은 드라이버에서 파일 사용을 참조하세요.

NtWriteFile의 호출자는 IRQL = PASSIVE_LEVEL 및 특수 커널 APC를 사용하도록 설정된 상태에서 실행되어야 합니다.

이 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwWriteFile" 대신 "NtWriteFile" 이름을 사용해야 합니다.

커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxxZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.

요구 사항

요구 사항
지원되는 최소 클라이언트 Windows 2000
대상 플랫폼 유니버설
헤더 ntifs.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리 NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL(설명 섹션 참조)
DDI 규정 준수 규칙 HwStorPortProhibitedDDIs, PowerIrpDDis

추가 정보

KeInitializeEvent

NtCreateFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile