| BOOL WriteFile(hFile, lpBuffer, nNumberOfBytesToWrite, lpNumberOfBytesWritten, lpOverlapped) | |||||
| HANDLE hFile; | /* file to write | */ | |||
| CONST VOID *lpBuffer; | /* addr of data to write to file | */ | |||
| DWORD nNumberOfBytesToWrite; | /* bytes to write | */ | |||
| LPDWORD lpNumberOfBytesWritten; | /* points to number of bytes written | */ | |||
| LPOVERLAPPED lpOverlapped; | /* structure needed for overlapped i/o | */ | |||
The WriteFile function writes data to a file. The function starts writing data to the file at the position indicated by the file pointer. After the write completes, 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 I/O, the application must adjust the position of the file pointer after the write.
hFile
Identifies the file that is to be written. The file handle must have been created with GENERIC_WRITE access to the file.
lpBuffer
Points to the buffer that contains the data to be written to the file.
nNumberOfBytesToWrite
Specifies the number of bytes to write to the file. Unlike MS-DOS, a value of zero is interpreted a null write.
lpNumberOfBytesWritten
Specifies the number of bytes written by this call. WriteFile sets this value to zero before doing any work or error checking.
lpOverlapped
Points to an OVERLAPPED structure. This structure is required if hFile was opened with FILE_FLAG_OVERLAPPED.
If hFile was created with FILE_FLAG_OVERLAPPED and lpOverlapped is NULL, the current position of the file pointer is unknown, WriteFile returns FALSE, and GetLastError returns ERROR_INVALID_PARAMETER.
If hFile was not created 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 completes.
If hFile was created 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 completes. In this case, WriteFile returns FALSE and the GetLastError function returns ERROR_IO_PENDING. This allows the caller to continue processing while the write operation completes. The event specified in the OVERLAPPED structure is set to the signalled state upon completion of the write operation.
If hFile was not created 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 completes.
The OVERLAPPED structure has the following form:
typedef struct _OVERLAPPED { /* o */
DWORD Internal;
DWORD InternalHigh;
DWORD Offset;
DWORD OffsetHigh;
HANDLE hEvent;
} OVERLAPPED;
typedef OVERLAPPED *LPOVERLAPPED;
The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.
This function will fail if part of the file is locked by another process and the write overlaps the locked portion.
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 will be written to the current position (cursor position). The cursor position will be updated after the write.
Unlike MS-DOS, if nNumberOfBytesToWrite is zero, WriteFile does not truncate or extend the file. Use the SetEndOfFile function to truncate or extend a file.
When writing to a non-blocking, byte-mode pipe handle with insufficient buffer space, WriteFile will return TRUE with *lpNumberOfBytesWritten < nNumberOfBytesToWrite.
When an application uses the WriteFile function to write to a pipe, the write operation may not complete if the pipe buffer is full. The write operation will complete when a read operation (using the ReadFile function) makes more buffer space available.
CreateFile, GetOverlappedResult, ReadFile, SetEndOfFile, WriteFileEx