WriteFileGather

The WriteFileGather function gathers data from a set of buffers and writes the data to a file.

The function starts writing data to the file at a position specified by an OVERLAPPED structure. It operates asynchronously.

BOOL WriteFileGather(
  HANDLE hFile,                          // handle to file
  FILE_SEGMENT_ELEMENT aSegmentArray[ ], // array of buffer pointers
  DWORD nNumberOfBytesToWrite,           // number of bytes to write
  LPDWORD lpReserved,                    // reserved; must be NULL
  LPOVERLAPPED lpOverlapped              // overlapped buffer
);

Parameters

hFile

[in] Handle to the file to write to.

This file handle must have been created using GENERIC_WRITE to specify write access to the file, FILE_FLAG_OVERLAPPED to specify asynchronous I/O, and FILE_FLAG_NO_BUFFERING to specify non-cached I/O.

aSegmentArray

[out] Pointer to an array of FILE_SEGMENT_ELEMENT pointers to buffers. The function gathers the data it writes to the file from this set of buffers.

Each buffer must be at least the size of a system memory page and must be aligned on a system memory page size boundary. The system will write one system memory page of data from each buffer that a FILE_SEGMENT_ELEMENT pointer points to.

The function gathers the data from the buffers in a sequential manner: it writes data to the file from the first buffer, then from the second buffer, then from the next, until there is no more data to write.

The final element of the array must be a 64-bit NULL pointer.

Note  The array must contain one member for each system memory page-sized chunk of the total number of bytes to write to the file, plus one member for the final NULL pointer. For example, if the number of bytes to read is 40K, and the system page size is 4K, then this array must have 10 members for data, plus one member for the final NULL member, for a total of 11 members.

nNumberOfBytesToWrite

[in] Specifies the total number of bytes to write; each element of aSegmentArray contains a 1-page chunk of this total. Because the file must be opened with FILE_FLAG_NO_BUFFERING, the number of bytes to write must be a multiple of the sector size of the file system on which the file resides.

If nNumberOfBytesToWrite is zero, the function performs a null write operation. A null write operation does not write any bytes to the file, but it does cause the file's time stamp to change.

Note that this behavior differs from file writing functions on the MS-DOS platform, where a write count of zero bytes truncates a file. If nNumberOfBytesToWrite is zero, WriteFileGather does not truncate or extend the file. To truncate or extend a file, use the SetEndOfFile function. However, if nNumberOfBytesToWrite is not zero and the offset and length of the write place data beyond the current end of the file, WriteFileGather will extend the file.

lpReserved

This parameter is reserved for future use. You must set it to NULL.

lpOverlapped

[in] Pointer to an OVERLAPPED data structure.

The WriteFileGather function requires a valid OVERLAPPED structure. The lpOverlapped parameter cannot be NULL.

The WriteFileGather function starts writing data to the file at a position specified by the Offset and OffsetHigh members of the OVERLAPPED structure.

The WriteFileGather function may return before the write operation has completed. In that case, the WriteFileGather function returns the value zero, and the GetLastError function returns the value ERROR_IO_PENDING. This asynchronous operation of WriteFileGather lets the calling process continue while the write operation completes. You can call the GetOverlappedResult, HasOverlappedIoCompleted, or GetQueuedCompletionStatus function to obtain information about the completion of the write operation.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call the GetLastError function.

If the function returns before the write operation has completed, the function returns zero, and GetLastError returns ERROR_IO_PENDING.

Remarks

If part of the file specified by hFile is locked by another process, and the write operation overlaps the locked portion, the WriteFileGather function fails.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP2 or later.
  Windows 95/98: Unsupported.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

File I/O Overview, File I/O Functions, CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, HasOverlappedIoCompleted, OVERLAPPED, ReadFile, ReadFileEx, ReadFileScatter