Important Notice
The pages on this site contain documentation for very old MS-DOS software,
purely for historical purposes.
If you're looking for up-to-date documentation, particularly for programming,
you should not rely on the information found here, as it will be woefully
out of date.
read
◄Summary► ◄Example► ◄Up► ◄Contents► ◄Index► ◄Back►
────────────────────────────────────────────────────────────────────────────
The read function attempts to read <count> bytes into <buffer>
from the file associated with <handle>. The read operation begins
at the current position of the file pointer (if any) associated
with the given file. After the read operation, the file pointer
points to the next unread character.
Return Value
The read function returns the number of bytes actually read, which
may be less than <count> if there are fewer than <count> bytes
left in the file or if the file was opened in text mode (see
below). The return value 0 indicates an attempt to read at
end-of-file. The return value -1 indicates an error, and errno is
set to EBADF.
If you are reading more than 32K (the maximum size for type int)
from a file, the return value should be of type unsigned. However,
the maximum number of bytes that can be read from a file is 65,534
at a time, since 65,535 (or 0xFFFF) is -1 and therefore cannot be
distinguished from an error return.
If the file was opened in text mode, the return value may not
correspond to the number of bytes actually read. When text mode is
in effect, each carriage-return──line-feed pair is replaced with a
single line-feed character. Only the single line-feed character is
counted in the return value. The replacement does not affect the
file pointer.
Note that when files are opened in text mode under DOS and OS/2,
a CTRL+Z character is treated as an end-of-file indicator. When
CTRL+Z is encountered, the read terminates, and the next read
returns zero bytes. The lseek function clears the end-of-file
indicator.
-♦-