please dont rip this site Prev Next

WriteFileGather info  Overview  Group

[New for Windows NT 4.0 Service Pack 2.]

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

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

The WriteFileGather function operates asynchronously.

BOOL WriteFileGather(

    HANDLE hFile,

// handle to a file to write data to

    FILE_SEGMENT_ELEMENT aSegmentArray [],

// pointer to an array of buffer pointers

    DWORD nNumberOfBytesToWrite,

// number of bytes to write

    LPDWORD lpReserved,

// reserved; must be NULL

    LPOVERLAPPED lpOverlapped

// pointer to an asynchronous I/O data structure



An open 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.

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 should be the size of a system memory page. Each buffer should be aligned on a system memory page size boundary.

A FILE_SEGMENT_ELEMENT pointer is a 64-bit value. The WriteFileGather function uses all 64 bits. Since the operating systems do not currently support 64-bit memory addressing, you must explicitly zero the upper 32 bits of each FILE_SEGMENT_ELEMENT pointer.

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 should be a NULL pointer.

Specifies the number of bytes to write to the file.
Windows NT
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. WriteFileGather does not truncate or extend the file. To truncate or extend a file on the Windows NT platform, use the SetEndOfFile function..

This parameter is reserved for future use. You must set it to NULL.
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.


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

See Also

CreateFile, GetOverlappedResult, GetQueuedCompletionStatus, HasOverlappedIoCompleted, OVERLAPPED, ReadFile, ReadFileEx, ReadFileScatter


file: /Techref/os/win/api/win32/func/src/f92_23.htm, 6KB, , updated: 2000/4/7 12:19, local time: 2022/5/25 15:34,

 ©2022 These pages are served without commercial sponsorship. (No popup ads, etc...).Bandwidth abuse increases hosting cost forcing sponsorship or shutdown. This server aggressively defends against automated copying for any reason including offline viewing, duplication, etc... Please respect this requirement and DO NOT RIP THIS SITE. Questions?
Please DO link to this page! Digg it! / MAKE!

<A HREF=""> WriteFileGather</A>

After you find an appropriate page, you are invited to your to this massmind site! (posts will be visible only to you before review) Just type a nice message (short messages are blocked as spam) in the box and press the Post button. (HTML welcomed, but not the <A tag: Instead, use the link box to link to another page. A tutorial is available Members can login to post directly, become page editors, and be credited for their posts.

Link? Put it here: 
if you want a response, please enter your email address: 
Attn spammers: All posts are reviewed before being made visible to anyone other than the poster.
Did you find what you needed?

  PICList 2022 contributors:
o List host: MIT, Site host, Top posters @20220525
* Page Editors: James Newton, David Cary, and YOU!
* Roman Black of Black Robotics donates from sales of Linistep stepper controller kits.
* Ashley Roll of Digital Nemesis donates from sales of RCL-1 RS232 to TTL converters.
* Monthly Subscribers: Gregg Rew. on-going support is MOST appreciated!
* Contributors: Richard Seriani, Sr.

Welcome to!