32.11. $characterRead

$characterRead is the text file counterpart to $storageUnitRead, which works only on data files.

$characterRead reads up to numCharacters characters into memory at memCharadr. $characterRead does not filter out null or carriage return characters; i.e., it acts as if the file had been opened with the keepNul bit set. If end-of-file occurs before numCharacters characters have been read, fewer than numCharacters are read; the number actually read is returned. The effect is undefined if at least numCharacters characters' worth of scratch memory is not allocated at memCharadr. If the file is opened for PDF I/O, the characters by default are translated from the PDF to the host character set.

The only valid ctrlBits bit is $noTranslate. If it is set and f is open for PDF I/O, no character translation from PDF to the host character set is done.

$characterRead may be called for an unbuffered file (a file opened with the $unbuffered bit set); see Section 43.5.