Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revision | |||
| en:docs:fapi:dosread [2021/08/20 07:06] – prokushev | en:docs:fapi:dosread [2021/09/18 14:43] (current) – prokushev | ||
|---|---|---|---|
| Line 5: | Line 5: | ||
| This call reads the specified number of bytes from a file, pipe, or device to a buffer location. | This call reads the specified number of bytes from a file, pipe, or device to a buffer location. | ||
| - | ==Syntax== | + | ===== Syntax |
| - | | + | <code c> |
| + | DosRead (FileHandle, | ||
| + | </ | ||
| - | ==Parameters== | + | ===== Parameters ===== |
| - | ;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. | + | |
| + | | ||
| + | |||
| + | ===== Return Code ===== | ||
| + | |||
| + | rc ([[USHORT]]) - return | ||
| - | ==Return Code== | ||
| - | rc (USHORT) - return | ||
| Return code descriptions are: | Return code descriptions are: | ||
| - | * 0 NO_ERROR | ||
| - | * 5 ERROR_ACCESS_DENIED | ||
| - | * 6 ERROR_INVALID_HANDLE | ||
| - | * 26 | ||
| - | * 33 | ||
| - | * 109 ERROR_BROKEN_PIPE | ||
| - | * 234 ERROR_MORE_DATA | ||
| - | ==Remarks== | + | * 0 NO_ERROR |
| + | * 5 ERROR_ACCESS_DENIED | ||
| + | * 6 ERROR_INVALID_HANDLE | ||
| + | * 26 | ||
| + | * 33 | ||
| + | * 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. | 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. | ||
| Line 32: | Line 39: | ||
| The file pointer is moved to the desired position by reading, writing, or issuing DosChgFilePtr. | The file pointer is moved to the desired position by reading, writing, or issuing DosChgFilePtr. | ||
| - | ===Family API Considerations=== | + | ==== 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: | 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: | ||
| - | * 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. | + | |
| - | * 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, | + | * 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, |
| For example, suppose DosRead is called with a buffer of length 10 from a handle opened to CON: | 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. | + | * 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 ==== | ||
| - | ===Named Pipe Considerations=== | ||
| A named pipe is read as one of the following: | A named pipe is read as one of the following: | ||
| - | * A byte pipe in byte read mode. | + | |
| - | * A message pipe in message read mode. | + | * A message pipe in message read mode. |
| - | * A message pipe in byte read mode. | + | * 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 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. | ||
| Line 59: | Line 68: | ||
| Non-blocking mode allows a return with BytesRead = 0 only when no data is available at the time of the read. | Non-blocking mode allows a return with BytesRead = 0 only when no data is available at the time of the read. | ||
| - | ==Example Code== | + | ===== Bindings ===== |
| - | === C Binding=== | + | |
| - | <PRE> | + | ==== C Binding ==== |
| + | |||
| + | <code c> | ||
| #define INCL_DOSFILEMGR | #define INCL_DOSFILEMGR | ||
| Line 72: | Line 83: | ||
| USHORT | USHORT | ||
| - | </PRE> | + | </code> |
| + | |||
| + | ==== MASM Binding ==== | ||
| - | ===MASM Binding=== | + | <code asm> |
| - | <PRE> | + | |
| EXTRN DosRead:FAR | EXTRN DosRead:FAR | ||
| INCL_DOSFILEMGR | INCL_DOSFILEMGR | ||
| Line 86: | Line 98: | ||
| Returns WORD | Returns WORD | ||
| - | </PRE> | + | </code> |
| - | ====== Note ====== | + | ===== Note ===== |
| Text based on [[http:// | Text based on [[http:// | ||