DosRead

Bindings:  C, MASM 

This call reads the specified number of bytes from a file, pipe, or device 
to a buffer location. 

 DosRead    (FileHandle, BufferArea, BufferLength, BytesRead) 
 

 FileHandle (HFILE) - input 
    File handle obtained from DosOpen. 

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

 BufferLength (USHORT) - input 
    Length, in bytes, to be read. 

 BytesRead (PUSHORT) - output 
    Address of the number of bytes read. 

 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 
    234       ERROR_MORE_DATA 
 
 Remarks 

 The requested number of bytes may not be read.  If the value returned in 
 BytesRead is zero, the process has tried to read from the end of the 
 file. 

 A BufferLength value of zero is not considered an error.  In the case 
 where BufferLength is zero, the system treats the request as a null 
 operation. 

 The file pointer is moved to the desired position by reading, writing, or 
 issuing DosChgFilePtr. 

 
 Family API Considerations 

 Some options operate differently in the DOS mode than in the OS/2 mode. 
  Therefore, the following restrictions apply to DosRead when coding for 
 the DOS mode: 

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

 o When DosRead is called with a handle that is open to CON, the read goes 
   directly through KbdStringIn using the buffer and length that are 
   provided to DosRead.  This causes a DOS mode DosRead to behave 
   differently than an OS/2 mode DosRead. Because an OS/2 mode DosRead 
   buffers the call to KbdStringIn, this allows the user to enter many 
   more characters. 

   For example, suppose DosRead is called with a buffer of length 10 from 
   a handle opened to CON: 

    - In OS/2 mode, the user is allowed to enter a large number of 
      characters before KbdStringIn begins beeping (indicating the buffer 
      is full). After carriage return is pressed, KbdStringIn returns to 
      DosRead. DosRead returns the first 10 characters to the caller and 
      the remaining characters on subsequent calls to DosRead from CON. 

    - In DOS mode, the user is allowed to enter only eight characters (DOS 
      mode DosRead reserves two characters for CR and LF) before 
      KbdStringIn begins beeping. DosRead returns the eight characters 
      entered, followed by CR and LF to the calling program. 
 

 
 Named Pipe Considerations 

 A named pipe is read as one of the following: 

 o A byte pipe in byte read mode 
 o A message pipe in message read mode 
 o A message pipe in byte read mode. 
 

 A byte pipe must be in byte read mode to be read; an error is returned if 
 it is in message read mode. All currently available data, up to the size 
 requested, is returned. 

 A message pipe can be read in either message read mode or byte read mode. 
 When the message pipe is in message read mode, a read that is larger than 
 the next available message returns only that message.  BytesRead is set 
 to indicate the size of the message returned. 

 A read that is smaller than the next available message returns with the 
 number of bytes requested and an ERROR_MORE_DATA return code. When 
 resuming the reading of a message after ERROR_MORE_DATA is returned, a 
 read always blocks until the next piece (or the rest) of the message can 
 be transferred. DosPeekNmPipe may be used to determine how many bytes are 
 left in the message. 

 A message pipe in byte read mode is read as if it were a byte stream, 
 skipping over message headers.  This is like reading a byte pipe in byte 
 read mode. 

 When blocking mode is set for a named pipe, a read blocks until data is 
 available.  In this case, the read never returns with BytesRead =  0 
 except at EOF.  In message read mode, messages are always read in their 
 entirety, except in the case where the message is bigger than the size of 
 the read. 

 Non-blocking mode allows a return with BytesRead = 0 only when no data is 
 available at the time of the read.