WriteFileGather 함수(fileapi.h)

아티클
01/10/2024

버퍼 배열에서 데이터를 검색하고 데이터를 파일에 씁니다.

함수는 OVERLAPPED 구조체로 지정된 위치에서 파일에 데이터를 쓰기 시작합니다. WriteFileGather 함수는 비동기적으로 작동합니다.

구문

BOOL WriteFileGather(
  [in]      HANDLE                  hFile,
  [in]      FILE_SEGMENT_ELEMENT [] aSegmentArray,
  [in]      DWORD                   nNumberOfBytesToWrite,
            LPDWORD                 lpReserved,
  [in, out] LPOVERLAPPED            lpOverlapped
);

매개 변수

[in] hFile

파일에 대한 핸들입니다. 파일 핸들은 GENERIC_WRITE 액세스 권한 및 FILE_FLAG_OVERLAPPED 및 FILE_FLAG_NO_BUFFERING 플래그를 사용하여 만들어야 합니다. 자세한 내용은 파일 보안 및 액세스 권한을 참조하세요.

[in] aSegmentArray

데이터를 포함하는 FILE_SEGMENT_ELEMENT 구조 버퍼 배열에 대한 포인터입니다. 이 공용 구조체에 대한 설명은 비고를 참조하세요.

각 요소는 데이터의 한 페이지를 나타냅니다.

참고

시스템 페이지의 크기를 확인하려면 GetSystemInfo 함수를 사용합니다.

배열에는 nNumberOfBytesToWrite 데이터 바이트를 나타내는 데 충분한 요소가 포함되어야 합니다. 예를 들어 쓸 40KB가 있고 페이지 크기가 4KB인 경우 배열에는 10개 요소가 있어야 합니다.

각 버퍼는 시스템 메모리 페이지의 크기 이상이어야 하며 시스템 메모리 페이지 크기 경계에 맞춰야 합니다. 시스템은 각 버퍼에서 하나의 시스템 메모리 데이터 페이지를 씁니다.

함수는 버퍼에서 데이터를 순차적으로 수집합니다. 예를 들어 nNumberOfBytesToWrite 바이트가 작성될 때까지 첫 번째 버퍼, 두 번째 버퍼 등에서 파일에 데이터를 씁니다.

이 함수의 비동기 작업으로 인해 이 매개 변수가 항상 비동기 쓰기의 수명 동안 유효한 메모리를 참조하도록 주의해야 합니다. instance 경우 일반적인 프로그래밍 오류는 로컬 스택 스토리지를 사용한 다음 실행이 scope 부족하도록 허용하는 것입니다.

[in] nNumberOfBytesToWrite

쓸 총 바이트 수입니다. aSegmentArray의 각 요소에는 이 합계의 한 페이지 청크가 포함됩니다. FILE_FLAG_NO_BUFFERING 파일을 열어야 하므로 바이트 수는 파일이 있는 파일 시스템의 섹터 크기의 배수여야 합니다.

nNumberOfBytesToWrite가 0이면 함수는 null 쓰기 작업을 수행합니다. null 쓰기 작업의 동작은 기본 파일 시스템에 따라 달라집니다. nNumberOfBytesToWrite가 0이 아니고 쓰기 위치 데이터의 오프셋 및 길이가 파일의 현재 끝을 벗어나면 WriteFileGather 함수는 파일을 확장합니다.

lpReserved

이 매개 변수는 나중에 사용하도록 예약되어 있으며 NULL이어야 합니다.

[in, out] lpOverlapped

OVERLAPPED 데이터 구조에 대한 포인터입니다.

WriteFileGather 함수에는 유효한 OVERLAPPED 구조체가 필요합니다. lpOverlapped 매개 변수는 NULL일 수 없습니다.

WriteFileGather 함수는 OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버에 의해 지정된 위치에서 파일에 데이터를 쓰기 시작합니다.

WriteFileGather 함수는 쓰기 작업이 완료되기 전에 반환할 수 있습니다. 이 시나리오에서 WriteFileGather 함수는 값 0을 반환하고 GetLastError 함수는 ERROR_IO_PENDING 값을 반환합니다. WriteFileGather 함수의 이 비동기 작업을 사용하면 쓰기 작업이 완료되는 동안 호출 프로세스를 계속할 수 있습니다.

GetOverlappedResult, HasOverlappedIoCompleted 또는 GetQueuedCompletionStatus 함수를 호출하여 쓰기 작업의 완료에 대한 정보를 가져올 수 있습니다. 자세한 내용은 동기 및 비동기 I/O를 참조하세요.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError 함수를 호출합니다.

쓰기 작업이 완료되기 전에 함수가 반환되면 함수는 0을 반환하고 GetLastError 함수는 ERROR_IO_PENDING 반환합니다.

설명

이 함수는 Itanium 기반 시스템의 WOW64에서 32비트 애플리케이션에 대해 지원되지 않습니다.

FILE_SEGMENT_ELEMENT 구조체는 다음과 같이 정의됩니다.

typedef union _FILE_SEGMENT_ELEMENT {
    PVOID64   Buffer;
    ULONGLONG Alignment;
}FILE_SEGMENT_ELEMENT, *PFILE_SEGMENT_ELEMENT;

버퍼 멤버에 포인터를 할당하면 코드가 32비트로 컴파일되는 경우 값이 로그 확장됩니다. 이렇게 하면 4기가바이트 튜닝으로 구성되거나 64비트 Windows의 WOW64에서 실행되는 시스템에서 실행되는 큰 주소 인식 애플리케이션이 중단됩니다. 따라서 버퍼에 포인터를 할당할 때 PtrToPtr64 매크로를 사용합니다.

hFile에서 지정한 파일의 일부가 다른 프로세스에 의해 잠겨 있고 쓰기 작업이 잠긴 부분과 겹치면 WriteFileGather 함수가 실패합니다.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	Yes

거래된 작업

파일 핸들에 바인딩된 트랜잭션이 있는 경우 작업이 트랜잭션됩니다.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll