Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
io(3)                      Erlang Module Definition                      io(3)

NAME
       io - Standard I/O Server Interface Functions

DESCRIPTION
       This module provides an interface to standard Erlang I/O servers. The
       output functions all return ok if they are successful, or exit if they
       are not.

       In the following description, all functions have an optional parameter
       IoDevice. If included, it must be the pid of a process which handles
       the IO protocols. Normally, it is the IoDevice returned by file:open/2.

       For a description of the IO protocols refer to the STDLIB User's Guide.

   Warning:
       As of R13A, data supplied to the put_chars function should be in the
       unicode:chardata() format. This means that programs supplying binaries
       to this function need to convert them to UTF-8 before trying to output
       the data on an IO device.

       If an IO device is set in binary mode, the functions get_chars and
       get_line may return binaries instead of lists. The binaries will, as of
       R13A, be encoded in UTF-8.

       To work with binaries in ISO-latin-1 encoding, use the file module
       instead.

       For conversion functions between character encodings, see the unicode
       module.

DATA TYPES

       device() = atom() | pid()

              An IO device. Either standard_io, standard_error, a registered
              name, or a pid handling IO protocols (returned from
              file:open/2).

       opt_pair() = {binary, boolean()}
                  | {echo, boolean()}
                  | {expand_fun, expand_fun()}
                  | {encoding, encoding()}

       expand_fun() =
           fun((term()) -> {yes | no, string(), [string(), ...]})

       encoding() = latin1
                  | unicode
                  | utf8
                  | utf16
                  | utf32
                  | {utf16, big | little}
                  | {utf32, big | little}

       setopt() = binary | list | opt_pair()

       format() = atom() | string() | binary()

       location() = erl_scan:location()

       prompt() = atom() | unicode:chardata()

       server_no_data() = {error, ErrorDescription :: term()} | eof

              What the I/O-server sends when there is no data.

EXPORTS

       columns() -> {ok, integer() >= 1} | {error, enotsup}

       columns(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}

              Types:

                 IoDevice = device()

              Retrieves the number of columns of the IoDevice (i.e. the width
              of a terminal). The function only succeeds for terminal devices,
              for all other IO devices the function returns {error, enotsup}

       put_chars(CharData) -> ok

       put_chars(IoDevice, CharData) -> ok

              Types:

                 IoDevice = device()
                 CharData = unicode:chardata()

              Writes the characters of CharData to the I/O server (IoDevice).

       nl() -> ok

       nl(IoDevice) -> ok

              Types:

                 IoDevice = device()

              Writes new line to the standard output (IoDevice).

       get_chars(Prompt, Count) -> Data | server_no_data()

       get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 Count = integer() >= 0
                 Data = string() | unicode:unicode_binary()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads Count characters from standard input (IoDevice), prompting
              it with Prompt. It returns:

                Data:
                  The input characters. If the IO device supports Unicode, the
                  data may represent codepoints larger than 255 (the latin1
                  range). If the I/O server is set to deliver binaries, they
                  will be encoded in UTF-8 (regardless of if the IO device
                  actually supports Unicode or not).

                eof:
                  End of file was encountered.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

       get_line(Prompt) -> Data | server_no_data()

       get_line(IoDevice, Prompt) -> Data | server_no_data()

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 Data = string() | unicode:unicode_binary()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads a line from the standard input (IoDevice), prompting it
              with Prompt. It returns:

                Data:
                  The characters in the line terminated by a LF (or end of
                  file). If the IO device supports Unicode, the data may
                  represent codepoints larger than 255 (the latin1 range). If
                  the I/O server is set to deliver binaries, they will be
                  encoded in UTF-8 (regardless of if the IO device actually
                  supports Unicode or not).

                eof:
                  End of file was encountered.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

       getopts() -> [opt_pair()] | {error, Reason}

       getopts(IoDevice) -> [opt_pair()] | {error, Reason}

              Types:

                 IoDevice = device()
                 Reason = term()

              This function requests all available options and their current
              values for a specific IO device. Example:

              1> {ok,F} = file:open("/dev/null",[read]).
              {ok,<0.42.0>}
              2> io:getopts(F).
              [{binary,false},{encoding,latin1}]

              Here the file I/O-server returns all available options for a
              file, which are the expected ones, encoding and binary. The
              standard shell however has some more options:

              3> io:getopts().
              [{expand_fun,#Fun<group.0.120017273>},
               {echo,true},
               {binary,false},
               {encoding,unicode}]

              This example is, as can be seen, run in an environment where the
              terminal supports Unicode input and output.

       printable_range() -> unicode | latin1

              Return the user requested range of printable Unicode characters.

              The user can request a range of characters that are to be
              considered printable in heuristic detection of strings by the
              shell and by the formatting functions. This is done by supplying
              +pc _range_ when starting Erlang.

              Currently the only valid values for _range_ are latin1 and
              unicode. latin1 means that only code points below 256 (with the
              exception of control characters etc) will be considered
              printable. unicode means that all printable characters in all
              unicode character ranges are considered printable by the io
              functions.

              By default, Erlang is started so that only the latin1 range of
              characters will indicate that a list of integers is a string.

              The simplest way to utilize the setting is to call
              io_lib:printable_list/1, which will use the return value of this
              function to decide if a list is a string of printable characters
              or not.

          Note:
              In the future, this function may return more values and ranges.
              It is recommended to use the io_lib:printable_list/1 function to
              avoid compatibility problems.

       setopts(Opts) -> ok | {error, Reason}

       setopts(IoDevice, Opts) -> ok | {error, Reason}

              Types:

                 IoDevice = device()
                 Opts = [setopt()]
                 Reason = term()

              Set options for the standard IO device (IoDevice).

              Possible options and values vary depending on the actual IO
              device. For a list of supported options and their current values
              on a specific IO device, use the getopts/1 function.

              The options and values supported by the current OTP IO devices
              are:

                binary, list or {binary, boolean()}:
                  If set in binary mode (binary or {binary, true}), the I/O
                  server sends binary data (encoded in UTF-8) as answers to
                  the get_line, get_chars and, if possible, get_until requests
                  (see the I/O protocol description in STDLIB User's Guide for
                  details). The immediate effect is that get_chars/2,3 and
                  get_line/1,2 return UTF-8 binaries instead of lists of chars
                  for the affected IO device.

                  By default, all IO devices in OTP are set in list mode, but
                  the I/O functions can handle any of these modes and so
                  should other, user written, modules behaving as clients to
                  I/O-servers.

                  This option is supported by the standard shell (group.erl),
                  the 'oldshell' (user.erl) and the file I/O servers.

                {echo, boolean()}:
                  Denotes if the terminal should echo input. Only supported
                  for the standard shell I/O-server (group.erl)

                {expand_fun, expand_fun()}:
                  Provide a function for tab-completion (expansion) like the
                  Erlang shell. This function is called when the user presses
                  the TAB key. The expansion is active when calling line-
                  reading functions such as get_line/1,2.

                  The function is called with the current line, upto the
                  cursor, as a reversed string. It should return a three-
                  tuple: {yes|no, string(), [string(), ...]}. The first
                  element gives a beep if no, otherwise the expansion is
                  silent, the second is a string that will be entered at the
                  cursor position, and the third is a list of possible
                  expansions. If this list is non-empty, the list will be
                  printed and the current input line will be written once
                  again.

                  Trivial example (beep on anything except empty line, which
                  is expanded to "quit"):

                 fun("") -> {yes, "quit", []};
                    (_) -> {no, "", ["quit"]} end

                  This option is supported by the standard shell only
                  (group.erl).

                {encoding, latin1 | unicode}:
                  Specifies how characters are input or output from or to the
                  actual IO device, implying that i.e. a terminal is set to
                  handle Unicode input and output or a file is set to handle
                  UTF-8 data encoding.

                  The option does not affect how data is returned from the I/O
                  functions or how it is sent in the I/O-protocol, it only
                  affects how the IO device is to handle Unicode characters
                  towards the "physical" device.

                  The standard shell will be set for either Unicode or latin1
                  encoding when the system is started. The actual encoding is
                  set with the help of the LANG or LC_CTYPE environment
                  variables on Unix-like system or by other means on other
                  systems. The bottom line is that the user can input Unicode
                  characters and the IO device will be in {encoding, unicode}
                  mode if the IO device supports it. The mode can be changed,
                  if the assumption of the runtime system is wrong, by setting
                  this option.

                  The IO device used when Erlang is started with the
                  "-oldshell" or "-noshell" flags is by default set to latin1
                  encoding, meaning that any characters beyond codepoint 255
                  will be escaped and that input is expected to be plain 8-bit
                  ISO-latin-1. If the encoding is changed to Unicode, input
                  and output from the standard file descriptors will be in
                  UTF-8 (regardless of operating system).

                  Files can also be set in {encoding, unicode}, meaning that
                  data is written and read as UTF-8. More encodings are
                  possible for files, see below.

                  {encoding, unicode | latin1} is supported by both the
                  standard shell (group.erl including werl on Windows(R)), the
                  'oldshell' (user.erl) and the file I/O servers.

                {encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little}
                | {utf32,big} | {utf32,little}}:
                  For disk files, the encoding can be set to various UTF
                  variants. This will have the effect that data is expected to
                  be read as the specified encoding from the file and the data
                  will be written in the specified encoding to the disk file.

                  {encoding, utf8} will have the same effect as {encoding,
                  unicode} on files.

                  The extended encodings are only supported on disk files
                  (opened by the file:open/2 function)

       write(Term) -> ok

       write(IoDevice, Term) -> ok

              Types:

                 IoDevice = device()
                 Term = term()

              Writes the term Term to the standard output (IoDevice).

       read(Prompt) -> Result

       read(IoDevice, Prompt) -> Result

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 Result = {ok, Term :: term()}
                        | server_no_data()
                        | {error, ErrorInfo}
                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads a term Term from the standard input (IoDevice), prompting
              it with Prompt. It returns:

                {ok, Term}:
                  The parsing was successful.

                eof:
                  End of file was encountered.

                {error, ErrorInfo}:
                  The parsing failed.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

       read(IoDevice, Prompt, StartLocation) -> Result

       read(IoDevice, Prompt, StartLocation, Options) -> Result

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 StartLocation = location()
                 Options = erl_scan:options()
                 Result = {ok, Term :: term(), EndLocation :: location()}
                        | {eof, EndLocation :: location()}
                        | server_no_data()
                        | {error, ErrorInfo, ErrorLocation :: location()}
                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads a term Term from IoDevice, prompting it with Prompt.
              Reading starts at location StartLocation. The argument Options
              is passed on as the Options argument of the erl_scan:tokens/4
              function. It returns:

                {ok, Term, EndLocation}:
                  The parsing was successful.

                {eof, EndLocation}:
                  End of file was encountered.

                {error, ErrorInfo, ErrorLocation}:
                  The parsing failed.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

       fwrite(Format) -> ok

       fwrite(Format, Data) -> ok

       fwrite(IoDevice, Format, Data) -> ok

       format(Format) -> ok

       format(Format, Data) -> ok

       format(IoDevice, Format, Data) -> ok

              Types:

                 IoDevice = device()
                 Format = format()
                 Data = [term()]

              Writes the items in Data ([]) on the standard output (IoDevice)
              in accordance with Format. Format contains plain characters
              which are copied to the output device, and control sequences for
              formatting, see below. If Format is an atom or a binary, it is
              first converted to a list with the aid of atom_to_list/1 or
              binary_to_list/1.

              1> io:fwrite("Hello world!~n", []).
              Hello world!
              ok

              The general format of a control sequence is ~F.P.PadModC. The
              character C determines the type of control sequence to be used,
              F and P are optional numeric arguments. If F, P, or Pad is *,
              the next argument in Data is used as the numeric value of F or
              P.

              F is the field width of the printed argument. A negative value
              means that the argument will be left justified within the field,
              otherwise it will be right justified. If no field width is
              specified, the required print width will be used. If the field
              width specified is too small, then the whole field will be
              filled with * characters.

              P is the precision of the printed argument. A default value is
              used if no precision is specified. The interpretation of
              precision depends on the control sequences. Unless otherwise
              specified, the argument within is used to determine print width.

              Pad is the padding character. This is the character used to pad
              the printed representation of the argument so that it conforms
              to the specified field width and precision. Only one padding
              character can be specified and, whenever applicable, it is used
              for both the field width and precision. The default padding
              character is ' ' (space).

              Mod is the control sequence modifier. It is either a single
              character (currently only t, for Unicode translation, and l, for
              stopping p and P from detecting printable characters, are
              supported) that changes the interpretation of Data.

              The following control sequences are available:

                ~:
                  The character ~ is written.

                c:
                  The argument is a number that will be interpreted as an
                  ASCII code. The precision is the number of times the
                  character is printed and it defaults to the field width,
                  which in turn defaults to 1. The following example
                  illustrates:

                1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
                |     aaaaa|bbbbb     |ccccc|
                ok

                  If the Unicode translation modifier (t) is in effect, the
                  integer argument can be any number representing a valid
                  Unicode codepoint, otherwise it should be an integer less
                  than or equal to 255, otherwise it is masked with 16#FF:

                2> io:fwrite("~tc~n",[1024]).
                \x{400}
                ok
                3> io:fwrite("~c~n",[1024]).
                ^@
                ok

                f:
                  The argument is a float which is written as [-]ddd.ddd,
                  where the precision is the number of digits after the
                  decimal point. The default precision is 6 and it cannot be
                  less than 1.

                e:
                  The argument is a float which is written as [-]d.ddde+-ddd,
                  where the precision is the number of digits written. The
                  default precision is 6 and it cannot be less than 2.

                g:
                  The argument is a float which is written as f, if it is >=
                  0.1 and < 10000.0. Otherwise, it is written in the e format.
                  The precision is the number of significant digits. It
                  defaults to 6 and should not be less than 2. If the absolute
                  value of the float does not allow it to be written in the f
                  format with the desired number of significant digits, it is
                  also written in the e format.

                s:
                  Prints the argument with the string syntax. The argument is,
                  if no Unicode translation modifier is present, an iolist(),
                  a binary(), or an atom(). If the Unicode translation
                  modifier (t) is in effect, the argument is
                  unicode:chardata(), meaning that binaries are in UTF-8. The
                  characters are printed without quotes. The string is first
                  truncated by the given precision and then padded and
                  justified to the given field width. The default precision is
                  the field width.

                  This format can be used for printing any object and
                  truncating the output so it fits a specified field:

                1> io:fwrite("|~10w|~n", [{hey, hey, hey}]).
                |**********|
                ok
                2> io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).
                |{hey,hey,h|
                3> io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).
                |{hey,hey  |
                ok

                  A list with integers larger than 255 is considered an error
                  if the Unicode translation modifier is not given:

                4> io:fwrite("~ts~n",[[1024]]).
                \x{400}
                ok
                5> io:fwrite("~s~n",[[1024]]).
                ** exception exit: {badarg,[{io,format,[<0.26.0>,"~s~n",[[1024]]]},
                   ...

                w:
                  Writes data with the standard syntax. This is used to output
                  Erlang terms. Atoms are printed within quotes if they
                  contain embedded non-printable characters, and floats are
                  printed accurately as the shortest, correctly rounded
                  string.

                p:
                  Writes the data with standard syntax in the same way as ~w,
                  but breaks terms whose printed representation is longer than
                  one line into many lines and indents each line sensibly. It
                  also tries to detect lists of printable characters and to
                  output these as strings. The Unicode translation modifier is
                  used for determining what characters are printable. For
                  example:

                1> T = [{attributes,[[{id,age,1.50000},{mode,explicit},
                {typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},
                {typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].
                2> io:fwrite("~w~n", [T]).
                [{attributes,[[{id,age,1.5},{mode,explicit},{typename,
                [73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena
                me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode
                ,implicit}]
                ok
                3> io:fwrite("~62p~n", [T]).
                [{attributes,[[{id,age,1.5},
                               {mode,explicit},
                               {typename,"INTEGER"}],
                              [{id,cho},{mode,explicit},{typename,'Cho'}]]},
                 {typename,'Person'},
                 {tag,{'PRIVATE',3}},
                 {mode,implicit}]
                ok

                  The field width specifies the maximum line length. It
                  defaults to 80. The precision specifies the initial
                  indentation of the term. It defaults to the number of
                  characters printed on this line in the same call to
                  io:fwrite or io:format. For example, using T above:

                4> io:fwrite("Here T = ~62p~n", [T]).
                Here T = [{attributes,[[{id,age,1.5},
                                        {mode,explicit},
                                        {typename,"INTEGER"}],
                                       [{id,cho},
                                        {mode,explicit},
                                        {typename,'Cho'}]]},
                          {typename,'Person'},
                          {tag,{'PRIVATE',3}},
                          {mode,implicit}]
                ok

                  When the modifier l is given no detection of printable
                  character lists will take place. For example:

                5> S = [{a,"a"}, {b, "b"}].
                6> io:fwrite("~15p~n", [S]).
                [{a,"a"},
                 {b,"b"}]
                ok
                7> io:fwrite("~15lp~n", [S]).
                [{a,[97]},
                 {b,[98]}]
                ok

                  Binaries that look like UTF-8 encoded strings will be output
                  with the string syntax if the Unicode translation modifier
                  is given:

                9> io:fwrite("~p~n",[[1024]]).
                [1024]
                10> io:fwrite("~tp~n",[[1024]]).
                "\x{400}"
                11> io:fwrite("~tp~n", [<<128,128>>]).
                <<128,128>>
                12> io:fwrite("~tp~n", [<<208,128>>]).
                <<"\x{400}"/utf8>>
                ok

                W:
                  Writes data in the same way as ~w, but takes an extra
                  argument which is the maximum depth to which terms are
                  printed. Anything below this depth is replaced with .... For
                  example, using T above:

                8> io:fwrite("~W~n", [T,9]).
                [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
                [{id,cho},{mode,...},{...}]]},{typename,'Person'},
                {tag,{'PRIVATE',3}},{mode,implicit}]
                ok

                  If the maximum depth has been reached, then it is impossible
                  to read in the resultant output. Also, the ,... form in a
                  tuple denotes that there are more elements in the tuple but
                  these are below the print depth.

                P:
                  Writes data in the same way as ~p, but takes an extra
                  argument which is the maximum depth to which terms are
                  printed. Anything below this depth is replaced with .... For
                  example:

                9> io:fwrite("~62P~n", [T,9]).
                [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
                              [{id,cho},{mode,...},{...}]]},
                 {typename,'Person'},
                 {tag,{'PRIVATE',3}},
                 {mode,implicit}]
                ok

                B:
                  Writes an integer in base 2..36, the default base is 10. A
                  leading dash is printed for negative integers.

                  The precision field selects base. For example:

                1> io:fwrite("~.16B~n", [31]).
                1F
                ok
                2> io:fwrite("~.2B~n", [-19]).
                -10011
                ok
                3> io:fwrite("~.36B~n", [5*36+35]).
                5Z
                ok

                X:
                  Like B, but takes an extra argument that is a prefix to
                  insert before the number, but after the leading dash, if
                  any.

                  The prefix can be a possibly deep list of characters or an
                  atom.

                1> io:fwrite("~X~n", [31,"10#"]).
                10#31
                ok
                2> io:fwrite("~.16X~n", [-31,"0x"]).
                -0x1F
                ok

                #:
                  Like B, but prints the number with an Erlang style
                  #-separated base prefix.

                1> io:fwrite("~.10#~n", [31]).
                10#31
                ok
                2> io:fwrite("~.16#~n", [-31]).
                -16#1F
                ok

                b:
                  Like B, but prints lowercase letters.

                x:
                  Like X, but prints lowercase letters.

                +:
                  Like #, but prints lowercase letters.

                n:
                  Writes a new line.

                i:
                  Ignores the next term.

              Returns:

                ok:
                  The formatting succeeded.

              If an error occurs, there is no output. For example:

              1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
              abc def 'abc def'  {foo,1} A
              ok
              2> io:fwrite("~s", [65]).
              ** exception exit: {badarg,[{io,format,[<0.22.0>,"~s","A"]},
                                          {erl_eval,do_apply,5},
                                          {shell,exprs,6},
                                          {shell,eval_exprs,6},
                                          {shell,eval_loop,3}]}
                   in function  io:o_request/2

              In this example, an attempt was made to output the single
              character 65 with the aid of the string formatting directive
              "~s".

       fread(Prompt, Format) -> Result

       fread(IoDevice, Prompt, Format) -> Result

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 Format = format()
                 Result = {ok, Terms :: [term()]}
                        | {error, {fread, FreadError :: io_lib:fread_error()}}
                        | server_no_data()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads characters from the standard input (IoDevice), prompting
              it with Prompt. Interprets the characters in accordance with
              Format. Format contains control sequences which directs the
              interpretation of the input.

              Format may contain:

                * White space characters (SPACE, TAB and NEWLINE) which cause
                  input to be read to the next non-white space character.

                * Ordinary characters which must match the next input
                  character.

                * Control sequences, which have the general format ~*FMC. The
                  character * is an optional return suppression character. It
                  provides a method to specify a field which is to be omitted.
                  F is the field width of the input field, M is an optional
                  translation modifier (of which t is the only currently
                  supported, meaning Unicode translation) and C determines the
                  type of control sequence.

                  Unless otherwise specified, leading white-space is ignored
                  for all control sequences. An input field cannot be more
                  than one line wide. The following control sequences are
                  available:

                  ~:
                    A single ~ is expected in the input.

                  d:
                    A decimal integer is expected.

                  u:
                    An unsigned integer in base 2..36 is expected. The field
                    width parameter is used to specify base. Leading white-
                    space characters are not skipped.

                  -:
                    An optional sign character is expected. A sign character -
                    gives the return value -1. Sign character + or none gives
                    1. The field width parameter is ignored. Leading white-
                    space characters are not skipped.

                  #:
                    An integer in base 2..36 with Erlang-style base prefix
                    (for example "16#ffff") is expected.

                  f:
                    A floating point number is expected. It must follow the
                    Erlang floating point number syntax.

                  s:
                    A string of non-white-space characters is read. If a field
                    width has been specified, this number of characters are
                    read and all trailing white-space characters are stripped.
                    An Erlang string (list of characters) is returned.

                    If Unicode translation is in effect (~ts), characters
                    larger than 255 are accepted, otherwise not. With the
                    translation modifier, the list returned may as a
                    consequence also contain integers larger than 255:

                  1> io:fread("Prompt> ","~s").
                  Prompt> <Characters beyond latin1 range not printable in this medium>
                  {error,{fread,string}}
                  2> io:fread("Prompt> ","~ts").
                  Prompt> <Characters beyond latin1 range not printable in this medium>
                  {ok,[[1091,1085,1080,1094,1086,1076,1077]]}

                  a:
                    Similar to s, but the resulting string is converted into
                    an atom.

                    The Unicode translation modifier is not allowed (atoms can
                    not contain characters beyond the latin1 range).

                  c:
                    The number of characters equal to the field width are read
                    (default is 1) and returned as an Erlang string. However,
                    leading and trailing white-space characters are not
                    omitted as they are with s. All characters are returned.

                    The Unicode translation modifier works as with s:

                  1> io:fread("Prompt> ","~c").
                  Prompt> <Character beyond latin1 range not printable in this medium>
                  {error,{fread,string}}
                  2> io:fread("Prompt> ","~tc").
                  Prompt> <Character beyond latin1 range not printable in this medium>
                  {ok,[[1091]]}

                  l:
                    Returns the number of characters which have been scanned
                    up to that point, including white-space characters.

                  It returns:

                  {ok, Terms}:
                    The read was successful and Terms is the list of
                    successfully matched and read items.

                  eof:
                    End of file was encountered.

                  {error, FreadError}:
                    The reading failed and FreadError gives a hint about the
                    error.

                  {error, ErrorDescription}:
                    The read operation failed and the parameter
                    ErrorDescription gives a hint about the error.

              Examples:

              20> io:fread('enter>', "~f~f~f").
              enter>1.9 35.5e3 15.0
              {ok,[1.9,3.55e4,15.0]}
              21> io:fread('enter>', "~10f~d").
              enter>     5.67899
              {ok,[5.678,99]}
              22> io:fread('enter>', ":~10s:~10c:").
              enter>:   alan   :   joe    :
              {ok, ["alan", "   joe    "]}

       rows() -> {ok, integer() >= 1} | {error, enotsup}

       rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}

              Types:

                 IoDevice = device()

              Retrieves the number of rows of the IoDevice (i.e. the height of
              a terminal). The function only succeeds for terminal devices,
              for all other IO devices the function returns {error, enotsup}

       scan_erl_exprs(Prompt) -> Result

       scan_erl_exprs(Device, Prompt) -> Result

       scan_erl_exprs(Device, Prompt, StartLocation) -> Result

       scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result

              Types:

                 Device = device()
                 Prompt = prompt()
                 StartLocation = location()
                 Options = erl_scan:options()
                 Result = erl_scan:tokens_result() | server_no_data()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads data from the standard input (IoDevice), prompting it with
              Prompt. Reading starts at location StartLocation (1). The
              argument Options is passed on as the Options argument of the
              erl_scan:tokens/4 function. The data is tokenized as if it were
              a sequence of Erlang expressions until a final dot (.) is
              reached. This token is also returned. It returns:

                {ok, Tokens, EndLocation}:
                  The tokenization succeeded.

                {eof, EndLocation}:
                  End of file was encountered by the tokenizer.

                eof:
                  End of file was encountered by the I/O-server.

                {error, ErrorInfo, ErrorLocation}:
                  An error occurred while tokenizing.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

              Example:

              23> io:scan_erl_exprs('enter>').
              enter>abc(), "hey".
              {ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
              24> io:scan_erl_exprs('enter>').
              enter>1.0er.
              {error,{1,erl_scan,{illegal,float}},2}

       scan_erl_form(Prompt) -> Result

       scan_erl_form(IoDevice, Prompt) -> Result

       scan_erl_form(IoDevice, Prompt, StartLocation) -> Result

       scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 StartLocation = location()
                 Options = erl_scan:options()
                 Result = erl_scan:tokens_result() | server_no_data()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads data from the standard input (IoDevice), prompting it with
              Prompt. Starts reading at location StartLocation (1). The
              argument Options is passed on as the Options argument of the
              erl_scan:tokens/4 function. The data is tokenized as if it were
              an Erlang form - one of the valid Erlang expressions in an
              Erlang source file - until a final dot (.) is reached. This last
              token is also returned. The return values are the same as for
              scan_erl_exprs/1,2,3 above.

       parse_erl_exprs(Prompt) -> Result

       parse_erl_exprs(IoDevice, Prompt) -> Result

       parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result

       parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
                          Result

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 StartLocation = location()
                 Options = erl_scan:options()
                 Result = parse_ret()
                 parse_ret() = {ok,
                                ExprList :: erl_parse:abstract_expr(),
                                EndLocation :: location()}
                             | {eof, EndLocation :: location()}
                             | {error,
                                ErrorInfo :: erl_scan:error_info()
                                           | erl_parse:error_info(),
                                ErrorLocation :: location()}
                             | server_no_data()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads data from the standard input (IoDevice), prompting it with
              Prompt. Starts reading at location StartLocation (1). The
              argument Options is passed on as the Options argument of the
              erl_scan:tokens/4 function. The data is tokenized and parsed as
              if it were a sequence of Erlang expressions until a final dot
              (.) is reached. It returns:

                {ok, ExprList, EndLocation}:
                  The parsing was successful.

                {eof, EndLocation}:
                  End of file was encountered by the tokenizer.

                eof:
                  End of file was encountered by the I/O-server.

                {error, ErrorInfo, ErrorLocation}:
                  An error occurred while tokenizing or parsing.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

              Example:

              25> io:parse_erl_exprs('enter>').
              enter>abc(), "hey".
              {ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
              26> io:parse_erl_exprs ('enter>').
              enter>abc("hey".
              {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}

       parse_erl_form(Prompt) -> Result

       parse_erl_form(IoDevice, Prompt) -> Result

       parse_erl_form(IoDevice, Prompt, StartLocation) -> Result

       parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result

              Types:

                 IoDevice = device()
                 Prompt = prompt()
                 StartLocation = location()
                 Options = erl_scan:options()
                 Result = parse_form_ret()
                 parse_form_ret() = {ok,
                                     AbsForm :: erl_parse:abstract_form(),
                                     EndLocation :: location()}
                                  | {eof, EndLocation :: location()}
                                  | {error,
                                     ErrorInfo :: erl_scan:error_info()
                                                | erl_parse:error_info(),
                                     ErrorLocation :: location()}
                                  | server_no_data()
                 server_no_data() = {error, ErrorDescription :: term()} | eof

              Reads data from the standard input (IoDevice), prompting it with
              Prompt. Starts reading at location StartLocation (1). The
              argument Options is passed on as the Options argument of the
              erl_scan:tokens/4 function. The data is tokenized and parsed as
              if it were an Erlang form - one of the valid Erlang expressions
              in an Erlang source file - until a final dot (.) is reached. It
              returns:

                {ok, AbsForm, EndLocation}:
                  The parsing was successful.

                {eof, EndLocation}:
                  End of file was encountered by the tokenizer.

                eof:
                  End of file was encountered by the I/O-server.

                {error, ErrorInfo, ErrorLocation}:
                  An error occurred while tokenizing or parsing.

                {error, ErrorDescription}:
                  Other (rare) error condition, for instance {error, estale}
                  if reading from an NFS file system.

STANDARD INPUT/OUTPUT
       All Erlang processes have a default standard IO device. This device is
       used when no IoDevice argument is specified in the above function
       calls. However, it is sometimes desirable to use an explicit IoDevice
       argument which refers to the default IO device. This is the case with
       functions that can access either a file or the default IO device. The
       atom standard_io has this special meaning. The following example
       illustrates this:

       27> io:read('enter>').
       enter>foo.
       {ok,foo}
       28> io:read(standard_io, 'enter>').
       enter>bar.
       {ok,bar}

       There is always a process registered under the name of user. This can
       be used for sending output to the user.

STANDARD ERROR
       In certain situations, especially when the standard output is
       redirected, access to an I/O-server specific for error messages might
       be convenient. The IO device standard_error can be used to direct
       output to whatever the current operating system considers a suitable IO
       device for error output. Example on a Unix-like operating system:

       $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
       'init:stop().' > /dev/null
       Error: error 11

ERROR INFORMATION
       The ErrorInfo mentioned above is the standard ErrorInfo structure which
       is returned from all IO modules. It has the format:

       {ErrorLocation, Module, ErrorDescriptor}

       A string which describes the error is obtained with the following call:

       Module:format_error(ErrorDescriptor)

Ericsson AB                       stdlib 2.4                             io(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | STANDARD INPUT/OUTPUT | STANDARD ERROR | ERROR INFORMATION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=io&manpath=FreeBSD+10.3-RELEASE+and+Ports>

home | help