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

Method Stdio.File()->read_oob()


Method read_oob

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

Description

Attempts to read len bytes of out-of-band data from the stream, and returns it as a string. Less than len bytes can be returned if:

  • the stream has been closed from the other end, or

  • nonblocking mode is used, or

  • not_all is set, or

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

If not_all is nonzero, read_oob() will only return as many bytes of out-of-band data as are currently 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_oob() 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 remote close.

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

Note

Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.

Note

It is not guaranteed that all out-of-band data sent from the other end will be received. Most streams only allow for a single byte of out-of-band data at a time.

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() , write_oob()