FsRtlCopyRead 함수(ntifs.h)

아티클
09/27/2023

FsRtlCopyRead 루틴은 캐시된 파일에서 사용자 버퍼로 데이터를 복사합니다.

구문

BOOLEAN FsRtlCopyRead(
  [in]  PFILE_OBJECT     FileObject,
  [in]  PLARGE_INTEGER   FileOffset,
  [in]  ULONG            Length,
  [in]  BOOLEAN          Wait,
  [in]  ULONG            LockKey,
  [out] PVOID            Buffer,
  [out] PIO_STATUS_BLOCK IoStatus,
  [in]  PDEVICE_OBJECT   DeviceObject
);

매개 변수

[in] FileObject

데이터를 읽을 캐시된 파일의 파일 개체에 대한 포인터입니다.

[in] FileOffset

캐시된 파일 내에서 바이트 오프셋 시작

[in] Length

읽을 데이터의 길이(바이트)입니다.

[in] Wait

모든 데이터가 복사될 때까지 호출자를 대기 상태로 전환할 수 있으면 TRUE로 설정하고, 그렇지 않으면 FALSE로 설정합니다.

[in] LockKey

잠글 바이트 범위와 연결된 값입니다. 잠금할 범위가 비클러스터적 잠금으로 이미 잠겨 있는 다른 범위와 겹치거나 읽을 범위가 이미 비정상으로 잠긴 다른 범위의 하위 범위인 경우 이 매개 변수의 값은 해당 비클러스터형 잠금의 키여야 합니다. 잠금은 호출 스레드의 부모 프로세스에 의해 유지되어야 합니다. 그렇지 않으면 이 매개 변수는 영향을 주지 않습니다.

[out] Buffer

데이터를 복사할 버퍼에 대한 포인터입니다.

[out] IoStatus

최종 완성 상태 수신하는 호출자가 할당한 구조체 및 작업에 대한 정보를 가리키는 포인터입니다. 데이터가 성공적으로 복사되면 IoStatus.Status 에 STATUS_SUCCESS 포함됩니다. 모든 데이터가 성공적으로 복사되지 않은 경우 IoStatus.Information 에는 복사된 실제 바이트 수가 포함됩니다.

[in] DeviceObject

파일 데이터를 보유하는 디바이스의 디바이스 개체입니다.

반환 값

복사 요청이 완료되면 FsRtlCopyRead 가 TRUE를 반환하고, 그렇지 않으면 FALSE를 반환합니다. TRUE의 반환 값이 반드시 복사 작업이 성공했음을 의미하지는 않습니다.

FsRtlCopyRead가 FALSE를 반환하거나 IoStatus의 내용에 복사 작업이 실패했음을 나타내는 경우 호출자는 FsRtlCopyRead를 호출하는 대신 읽기 IRP를 할당해야 합니다.

설명

파일 시스템별 빠른 I/O 읽기 루틴을 구현하는 대신 파일 캐싱을 지원하는 파일 시스템 개발자는 빠른 I/O 읽기 요청을 처리하기 위한 파일 시스템의 진입점으로 FsRtlCopyRead 를 사용하는 것을 고려해야 합니다. 이렇게 하려면 파일 시스템의 DriverEntry 루틴이 파일 시스템 드라이버 개체의 FAST_IO_DISPATCH 구조에서 FastIoRead 진입점을 FsRtlCopyRead 로 설정해야 합니다. 또한 파일 시스템은 다음을 수행해야 합니다.

빠른 I/O를 수행할 수 있는 각 파일에 대해 파일 시스템은 FSRTL_COMMON_FCB_HEADER 구조를 할당하고 초기화해야 합니다.

대부분의 파일 시스템에서는 FCB(파일 제어 블록)에 FSRTL_COMMON_FCB_HEADER 구조체를 포함하거나 열려 있는 파일의 상태를 유지하는 데 사용되는 유사한 구조체를 포함하여 이 작업을 수행합니다.

FSRTL_COMMON_FCB_HEADER 구조에 대한 스토리지는 일반적으로 페이징 풀에서 할당됩니다.
빠른 I/O를 수행할 수 있는 각 파일에 대해 파일 시스템은 파일의 모든 파일 개체를 FSRTL_COMMON_FCB_HEADER 구조체에 연결해야 합니다. 이 작업은 각 파일 개체의 FsContext 멤버가 이 구조체(또는 FSRTL_COMMON_FCB_HEADER 구조체를 포함하는 FCB 또는 기타 구조체)를 가리키도록 설정하여 수행됩니다.
파일을 캐싱할 때 파일 시스템은 파일의 FSRTL_COMMON_FCB_HEADER 구조체의 IsFastIoPossible 멤버를 적절한 값으로 설정해야 합니다. 이 값은 파일이 캐시된 상태로 유지되는 동안 필요에 따라 업데이트해야 합니다.

특히 파일 시스템은 캐시된 파일에 대한 배타적 바이트 범위 잠금이 있는 즉시 FSRTL_COMMON_FCB_HEADER 구조체의 IsFastIoPossible 멤버를 FastIoIsQuestionable 로 설정해야 합니다.

Wait가 TRUE이면 FsRtlCopyRead가 복사 요청을 완료하고 TRUE를 반환하도록 보장됩니다. 캐시된 파일의 필수 페이지가 이미 메모리에 상주하는 경우 데이터가 즉시 복사되고 차단이 발생하지 않습니다. 필요한 페이지가 상주하지 않으면 모든 필수 페이지가 상주하고 데이터를 복사할 수 있을 때까지 호출자가 대기 상태로 전환됩니다.

Wait가 FALSE인 경우 FsRtlCopyRead는 차단을 거부하고 파일의 기본 리소스를 가져올 수 없거나 캐시된 파일의 필요한 페이지가 메모리에 아직 상주하지 않은 경우 FALSE를 반환합니다.

파일 시스템의 FastIoCheckIfPossible 루틴은 FileOffset 및 Length 로 정의된 바이트 범위에 호출자가 적절한 LockKey 값을 전달하지 않는 단독으로 잠긴 바이트 범위가 포함되지 않도록 합니다. 파일 시스템에서 FsRtlXxxLockYyy 지원 루틴을 사용하여 바이트 범위 잠금을 관리하는 경우 FsRtlCopyRead를 호출하기 전에 FastIoCheckIfPossible 루틴에서 FsRtlFastCheckLockForRead를 호출하여 이 작업을 수행할 수 있습니다.

파일을 캐시하려면 CcInitializeCacheMap 루틴을 사용합니다.

요구 사항

요구 사항	값
대상 플랫폼	유니버설
헤더	ntifs.h(Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	PowerIrpDDis(wdm)

추가 정보

CcInitializeCacheMap

FsRtlCopyWrite

FsRtlFastCheckLockForRead

FsRtlCopyRead 함수(ntifs.h)

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

피드백

추가 리소스