
  -spec read(IoDevice, Number) -> {ok, Data} | eof | {error, Reason}
                when
                    IoDevice :: io_device() | atom(),
                    Number :: non_neg_integer(),
                    Data :: string() | binary(),
                    Reason ::
                        posix() |
                        badarg | terminated |
                        {no_translation, unicode, latin1}.

  Reads Number bytes/characters from the file referenced by 
  IoDevice. The functions read/2, pread/3, and read_line/1
  are the only ways to read from a file opened in raw mode
  (although they work for normally opened files, too).

  For files where encoding is set to something else than latin1,
  one character can be represented by more than one byte on the
  file. The parameter Number always denotes the number of 
  characters read from the file, while the position in the file can
  be moved much more than this number when reading a Unicode file.

  Also, if encoding is set to something else than latin1, the 
  read/3 call fails if the data contains characters larger than
  255, which is why module io(3) is to be preferred when reading
  such a file.

  The function returns:

  {ok, Data}:
    If the file was opened in binary mode, the read bytes are
    returned in a binary, otherwise in a list. The list or binary
    is shorter than the number of bytes requested if end of file
    was reached.

  eof:
    Returned if Number>0 and end of file was reached before
    anything at all could be read.

  {error, Reason}:
    An error occurred.

  Typical error reasons:

  ebadf:
    The file is not opened for reading.

  {no_translation, unicode, latin1}:
    The file is opened with another encoding than latin1 and
    the data in the file cannot be translated to the byte-oriented
    data that this function returns.
