◄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.
                                    -♦-