Extracted from Pike v7.6 release 61 at 2005-12-30.
pike.ida.liu.se
[Top]
Stdio
Stdio.File

Method Stdio.File()->read()


Method read

string read()
string read(int len)
string read(int len, int(0..1) not_all)

Description

Read data from a file or a stream.

Attempts to read len bytes from the file, and return it as a string. Less than len bytes can be returned if:

  • end-of-file is encountered for a normal file, or

  • it's a stream that has been closed from the other end, or

  • it's a stream in nonblocking mode, or

  • it's a stream and not_all is set, or

  • not_all isn't set and an error occurred (see below).

If not_all is nonzero, read() will not try its best to read as many bytes as you have asked for, but will merely return as much as the system read function will return. This mainly useful with stream devices which can return exactly one row or packet at a time. If not_all is used in blocking mode, read() will only block if there's no data at all available.

If something goes wrong and not_all is set, zero will be returned. If something goes wrong and not_all is zero or left out, then either zero or a string shorter than len is returned. If the problem persists then a later call to read() will fail and return zero, however.

If everything went fine, a call to errno() directly afterwards will return zero. That includes an end due to end-of-file or remote close.

If no arguments are given, read() will read to the end of the file or stream.

Note

It's not necessary to set not_all to avoid blocking reading when nonblocking mode is used.

Note

When at the end of a file or stream, repeated calls to read() will return the empty string since it's not considered an error. The empty string is never returned in other cases, unless nonblocking mode is used or len is zero.

See also

read_oob() , write()