# Method Stdio.Fd()->read_oob()

Method read_oob

  ``string` read_oob()`
  ``string` read_oob(`int` `len`)`
  ``string` read_oob(`int` `len`, `bool` `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() only returns as many bytes of out-of-band data as are currently available.

  If something goes wrong and `not_all` is set, zero is 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() fails and returns zero, however.

  If everything went fine, a call to errno() directly afterwards returns zero. That includes an end due to remote close.

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

Note

  Out-of-band data was not supported in Pike 0.5 and earlier, and not in 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 is 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() returns 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()