This module provides an interface to standard Erlang I/O servers.
The output functions all return
All functions in this module have an optional
parameter
For a description of the I/O protocols, see section
As from Erlang/OTP R13A, data supplied to function
If an I/O device is set in binary mode, functions
To work with binaries in ISO Latin-1 encoding, use the
For conversion functions between character encodings, see the
An I/O device, either
What the I/O server sends when there is no data.
Retrieves the number of columns of the
Writes the items in
1> io:fwrite("Hello world!~n", []). Hello world! ok
The general format of a control sequence is
Character
Available control sequences:
Character
The argument is a number that is interpreted as an ASCII code. The precision is the number of times the character is printed and defaults to the field width, which in turn defaults to 1. Example:
1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]). | aaaaa|bbbbb |ccccc| ok
If the Unicode translation modifier (
2> io:fwrite("~tc~n",[1024]). \x{400} ok 3> io:fwrite("~c~n",[1024]). ^@ ok
The argument is a float that is written as
The argument is a float that is written as
The argument is a float that is written as
Prints the argument with the string syntax. The
argument is, if no Unicode translation modifier is present, an
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 > 255 is considered an error if the Unicode translation modifier is not specified:
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]]]}, ...
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.
Atom characters > 255 are escaped unless the
Unicode translation modifier (
Writes the data with standard syntax in the same way as
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.
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
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
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 are output with the string syntax if the Unicode translation modifier is specified:
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
Writes data in the same way as
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 is reached, it cannot
be read in the resultant output. Also, the
Writes data in the same way as
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
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
Like
The prefix can be a possibly deep list of characters or an atom. Example:
1> io:fwrite("~X~n", [31,"10#"]). 10#31 ok 2> io:fwrite("~.16X~n", [-31,"0x"]). -0x1F ok
Like
1> io:fwrite("~.10#~n", [31]). 10#31 ok 2> io:fwrite("~.16#~n", [-31]). -16#1F ok
Like
Like
Like
Writes a new line.
Ignores the next term.
The function returns:
The formatting succeeded.
If an error occurs, there is no output. 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
Reads characters from the standard input
(
Whitespace characters (Space, Tab, and Newline) that cause input to be read to the next non-whitespace character.
Ordinary characters that must match the next input character.
Control sequences, which have the general format
Character
Unless otherwise specified, leading whitespace is ignored for all control sequences. An input field cannot be more than one line wide.
Available control sequences:
A single
A decimal integer is expected.
An unsigned integer in base 2-36 is expected. The field width parameter is used to specify base. Leading whitespace characters are not skipped.
An optional sign character is expected. A sign
character
An integer in base 2-36 with Erlang-style base
prefix (for example,
A floating point number is expected. It must follow the Erlang floating point number syntax.
A string of non-whitespace characters is read. If a field width has been specified, this number of characters are read and all trailing whitespace characters are stripped. An Erlang string (list of characters) is returned.
If Unicode translation is in effect (
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]]}
Similar to
The Unicode translation modifier is not allowed (atoms
cannot contain characters beyond the
The number of characters equal to the field width are
read (default is 1) and returned as an Erlang string.
However, leading and trailing whitespace characters
are not omitted as they are with
The Unicode translation modifier works as with
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]]}
Returns the number of characters that have been scanned up to that point, including whitespace characters.
The function returns:
The read was successful and
End of file was encountered.
The reading failed and
The read operation failed and parameter
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 "]}
Reads
The function returns:
The input characters. If the I/O device supports Unicode,
the data can represent codepoints > 255 (the
End of file was encountered.
Other (rare) error condition, such as
Reads a line from the standard input (
The function returns:
The characters in the line terminated by a line feed (or end of
file). If the I/O device supports Unicode,
the data can represent codepoints > 255 (the
End of file was encountered.
Other (rare) error condition, such as
Requests all available options and their current values for a specific I/O device, for 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,
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.
Writes new line to the standard output
(
Reads data from the standard input
(
The function returns:
The parsing was successful.
End of file was encountered by the tokenizer.
End of file was encountered by the I/O server.
An error occurred while tokenizing or parsing.
Other (rare) error condition, such as
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}
Reads data from the standard input (
The function returns:
The parsing was successful.
End of file was encountered by the tokenizer.
End of file was encountered by the I/O server.
An error occurred while tokenizing or parsing.
Other (rare) error condition, such as
Returns 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
The only valid values for
By default, Erlang is started so that only the
The simplest way to use the setting is to call
In a future release, this function may return more values and
ranges. To avoid compatibility problems, it is recommended to use
function
Writes the characters of
Reads a term
The function returns:
The parsing was successful.
End of file was encountered.
The parsing failed.
Other (rare) error condition, such as
Reads a term
The function returns:
The parsing was successful.
End of file was encountered.
The parsing failed.
Other (rare) error condition, such as
Retrieves the number of rows of
Reads data from the standard input (
The function returns:
The tokenization succeeded.
End of file was encountered by the tokenizer.
End of file was encountered by the I/O server.
An error occurred while tokenizing.
Other (rare) error condition, such as
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}
Reads data from the standard input (
The return values are the same as for
Set options for the standard I/O device
(
Possible options and values vary depending on the
I/O device. For a list of supported options and their current values
on a specific I/O device, use function
The options and values supported by the OTP I/O devices are as follows:
If set in binary mode (
By default, all I/O devices in OTP are set in
This option is supported by the standard shell
(
Denotes if the terminal is to echo input. Only supported for
the standard shell I/O server (
Provides 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
The function is called with the current line, up to
the cursor, as a reversed string. It is to return a
three-tuple:
Trivial example (beep on anything except empty line, which
is expanded to
fun("") -> {yes, "quit", []};
(_) -> {no, "", ["quit"]} end
This option is only supported by the standard shell
(
Specifies how characters are input or output from or to the I/O device, implying that, for example, 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 I/O device is to handle Unicode characters to the "physical" device.
The standard shell is set for
The I/O device used when Erlang is started with the "-oldshell"
or "-noshell" flags is by default set to
Files can also be set in
For disk files, the encoding can be set to various UTF variants. This has the effect that data is expected to be read as the specified encoding from the file, and the data is written in the specified encoding to the disk file.
The extended encodings are only supported on disk files
(opened by function
Writes term
All Erlang processes have a default standard I/O device. This
device is used when no
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
In certain situations, especially when the standard output is
redirected, access to an I/O server specific for error messages can be
convenient. The I/O device
$ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\ 'init:stop().' > /dev/null Error: error 11
The
{ErrorLocation, Module, ErrorDescriptor}
A string that describes the error is obtained with the following call:
Module:format_error(ErrorDescriptor)