WriteFile
The WriteFile
function writes data to a file and is designed for both synchronous and
asynchronous operation. The function starts writing data to the file at the
position indicated by the file pointer. After the write operation has been
completed, the file pointer is adjusted by the number of bytes actually
written, except when the file is opened with FILE_FLAG_OVERLAPPED. If the file
handle was created for overlapped input and output (I/O), the application must
adjust the position of the file pointer after the write operation is finished.
BOOL WriteFile(
|
HANDLE hFile, |
// handle to file
to write to |
|
LPCVOID lpBuffer, |
// pointer to data
to write to file |
|
DWORD nNumberOfBytesToWrite, |
// number of bytes
to write |
|
LPDWORD lpNumberOfBytesWritten, |
// pointer to
number of bytes written |
|
LPOVERLAPPED lpOverlapped |
// pointer to
structure needed for overlapped I/O |
|
); |
|
Parameters
hFile
Identifies
the file to be written to. The file handle must have been created with
GENERIC_WRITE access to the file.
Windows
NT
For
asynchronous write operations, hFile can be any handle opened with the
FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned by the socket or accept functions.
Windows
95
For
asynchronous write operations, hFile can be a communications resource,
mailslot, or named pipe handle opened with the FILE_FLAG_OVERLAPPED flag by CreateFile,
or a socket handle returned by the socket or accept functions.
Windows 95 does not support asynchronous write operations on disk files.
lpBuffer
Points to the
buffer containing the data to be written to the file.
nNumberOfBytesToWrite
Specifies the
number of bytes to write to the file.
Unlike the
MS-DOS operating system, Windows NT interprets a value of zero as specifying a
null write operation. A null write operation does not write any bytes but does
cause the time stamp to change.
Named pipe write operations across a network are limited to 65535
bytes.
lpNumberOfBytesWritten
Points to the
number of bytes written by this function call. WriteFile sets this value
to zero before doing any work or error checking.
If lpOverlapped
is NULL, lpNumberOfBytesWritten cannot be NULL.
If lpOverlapped
is not NULL, lpNumberOfBytesWritten can be NULL. If this is an
overlapped write operation, you can get the number of bytes written by calling GetOverlappedResult. If hFile is
associated with an I/O completion port, you can get the number of bytes written
by calling GetQueuedCompletionStatus.
lpOverlapped
Points to an OVERLAPPED structure. This structure
is required if hFile was opened with FILE_FLAG_OVERLAPPED.
If hFile was opened with FILE_FLAG_OVERLAPPED, the lpOverlapped
parameter must not be NULL. It must point to a valid OVERLAPPED
structure. If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped
is NULL, the function can incorrectly report that the write operation is
complete.
If hFile was opened with FILE_FLAG_OVERLAPPED and lpOverlapped
is not NULL, the write operation starts at the offset specified in the OVERLAPPED
structure and WriteFile may return before the write operation has been
completed. In this case, WriteFile returns FALSE and the GetLastError
function returns ERROR_IO_PENDING. This allows the calling process to continue
processing while the write operation is being completed. The event specified in
the OVERLAPPED structure is set to the signaled state upon completion of
the write operation.
If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped
is NULL, the write operation starts at the current file position and WriteFile
does not return until the operation has been completed.
If hFile was not opened with FILE_FLAG_OVERLAPPED and lpOverlapped
is not NULL, the write operation starts at the offset specified in the OVERLAPPED
structure and WriteFile does not return until the write operation has
been completed.
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 GetLastError.
Remarks
If part of
the file is locked by another process and the write operation overlaps the
locked portion, this function fails.
Applications
must not read from nor write to the output buffer that a write operation is
using until the write operation completes. Premature access of the output
buffer may lead to corruption of the data written from that buffer.
Characters
can be written to the screen buffer using WriteFile with a handle to
console output. The exact behavior of the function is determined by the console
mode. The data is written to the current cursor position. The cursor position
is updated after the write operation.
Unlike the
MS-DOS operating system, Windows NT interprets zero bytes to write as
specifying a null write operation and WriteFile does not truncate or
extend the file. To truncate or extend a file, use the SetEndOfFile
function.
When writing
to a nonblocking, byte-mode pipe handle with insufficient buffer space, WriteFile
returns TRUE with *lpNumberOfBytesWritten < nNumberOfBytesToWrite.
When an
application uses the WriteFile function to write to a pipe, the write
operation may not finish if the pipe buffer is full. The write operation is
completed when a read operation (using the ReadFile function) makes more
buffer space available.
If the
anonymous read pipe handle has been closed and WriteFile attempts to
write using the corresponding anonymous write pipe handle, the function returns
FALSE and GetLastError
returns ERROR_BROKEN_PIPE.
The WriteFile
function may fail with ERROR_INVALID_USER_BUFFER or ERROR_NOT_ENOUGH_MEMORY
whenever there are too many outstanding asynchronous I/O requests.
To cancel all
pending asynchronous I/O operations, use the CancelIO function. This function
only cancels operations issued by the calling thread for the specified file
handle. I/O operations that are canceled complete with the error
ERROR_OPERATION_ABORTED.
If hFile
is a handle to a named pipe, the Offset and OffsetHigh members of
the OVERLAPPED structure pointed to by lpOverlapped must be zero,
or the function will fail.
See Also