DosWrite

Bindings:  C, MASM 

This call transfers the specified number of bytes from a buffer to the 
specified file, synchronously with respect to the requesting process's 
execution. 

 DosWrite    (FileHandle, BufferArea, BufferLength, BytesWritten) 
 

 FileHandle (HFILE) - input 
    File handle from DosOpen. 

 BufferArea (PVOID) - input 
    Address of the output buffer. 

 BufferLength (USHORT) - input 
    Number of bytes to write. 

 BytesWritten (PUSHORT) - output 
    Address of the number of bytes written. 

 rc (USHORT) - return 
    Return code descriptions are: 

    0         NO_ERROR 
    5         ERROR_ACCESS_DENIED 
    6         ERROR_INVALID_HANDLE 
    26        ERROR_NOT_DOS_DISK 
    33        ERROR_LOCK_VIOLATION 
    109       ERROR_BROKEN_PIPE 
 
 Remarks 

 On output, BytesWritten is the number of bytes actually written.  If 
 BytesWritten is different from BufferLength, this usually indicates 
 insufficient disk space. 

 A BufferLength value of 0 is not considered an error.  No data transfer 
 occurs.  There is no effect on the file or the file pointer. 

 Buffers that are multiples of the hardware's base physical unit for data 
 written to the file on these base boundaries, are written directly to the 
 device.  (The base physical unit is defined as the smallest block that 
 can be physically written to the device.)  Other buffer sizes force some 
 I/O to go through an internal system buffer and greatly reduce the 
 efficiency of I/O operation. 

 The file pointer is moved by read and write operations. It can be moved 
 to a desired position by calling DosChgFilePtr. 

 If the file is read-only, the write to the file is not performed. 

 
 Family API Considerations 

 Some options operate differently in the DOS mode than in OS/2 mode. 
  Therefore, the following restriction applies to DosWrite when coding for 
 the DOS mode. 

 o Only single-byte DosWrite requests can be made to the COM device, 
   because the COM device driver for the DOS environment does not support 
   multiple-byte I/O. 
 

 
 Named Pipe Considerations 

 DosWrite is also used to write bytes or messages to a named pipe. 

 Each write to a message pipe writes a message whose size is the length of 
 the write; DosWrite automatically encodes message lengths in the pipe, so 
 applications need not encode this information in the buffer being 
 written. 

 Writes in blocking mode always write all requested bytes before 
 returning. In non-blocking mode, if the message size is bigger than the 
 buffer size, the write blocks. If the message size is smaller than the 
 pipe but not enough space is left in the pipe, the write returns 
 immediately with a value of zero, indicating no bytes were written. 

 In the case of a byte pipe, if the number of bytes to be written exceeds 
 the space available in the pipe, DosWrite writes as many bytes as it can 
 and returns with the number of bytes actually written. 

 An attempt to write to a pipe whose other end has been closed returns 
 ERROR_BROKEN_PIPE.