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

Method read

  ``string` read()`
  ``string` read(`int` `len`)`
  ``string` read(`int` `len`, `bool` `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() does not try its best to read as many bytes as you have asked for, but merely returns as much as the system read function returns. This is 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() only blocks if there's no data at all 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() fails and returns zero, however.

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

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

  If any file descriptors have been sent by the other side of the stream, receive_fd() will be called once for every sent file descriptor.

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(), receive_fd(), send_fd()