1.1 The Erlang I/O-protocol
Ericsson AB. All Rights Reserved.: STDLIB | 3
• Encoding is either 'latin1' or 'unicode', meaning that the characters are (in case of binaries) encoded as either
UTF-8 or iso-latin-1 (pure bytes). A well behaved io_server should also return error if list elements contain
integers > 255 when the Encoding is set to latin1. Note that this does not in any way tell how characters should
be put on the actual device or how the io_server should handle them. Different io_servers may handle the
characters however they want, this simply tells the io_server which format the data is expected to have. In the
Module/Function/argument case, the Encoding tells which format the designated function produces. Note that
byte-oriented data is simplest sent using latin1 Encoding
• Characters are the data to be put on the device. If encoding is latin1, this is an iolist(). If encoding is unicode,
this is an Erlang standard mixed unicode list (one integer in a list per character, characters in binaries
represented as UTF-8).
• Module, Function, Args denotes a function which will be called to produce the data (like io_lib:format), Args
is a list of arguments to the function. The function should produce data in the given Encoding. The io_server
should call the function as apply(Mod, Func, Args) and will put the returned data on the device as if it was sent
in a {put_chars, Encoding, Characters} request. If the function returns anything else than a binary or list or
throws an exception, an error should be sent back to the client.
The server replies to the client with an io_reply where the Reply element is one of:
ok
{error, Error}
• Error describes the error to the client, which may do whatever it wants with it. The Erlang io-module typically
returns it as is.
For backward compatibility the following Requests should also be handled by an io_server (these messages should
not be present after R15B of OTP):
{put_chars, Characters}
{put_chars, Module, Function, Args}
These should behave as {put_chars, latin1, Characters} and {put_chars, latin1, Module, Function, Args} respectively.
1.1.3 Input Requests
To read characters from a device, the following Requests exist:
{get_until, Encoding, Prompt, Module, Function, ExtraArgs}
• Encoding denotes how data is to be sent back to the client and what data is sent to the function denoted by
Module/Function/Arity. If the function supplied returns data as a list, the data is converted to this encoding. If
however the function supplied returns data in some other format, no conversion can be done and it's up to the
client supplied function to return data in a proper way. If Encoding is latin1, lists of integers 0..255 or binaries
containing plain bytes are sent back to the client when possible, if Encoding is unicode, lists with integers in the
whole unicode range or binaries encoded in UTF-8 are sent to the client. The user supplied function will always
see lists of integers, never binaries, but the list may contain numbers > 255 if the Encoding is 'unicode'.
• Prompt is a list of characters (not mixed, no binaries) or an atom() to be output as a prompt for input on the
device. The Prompt is often ignored by the io_server and a Prompt set to '' should always be ignored (and result
in nothing being written to the device).
• Module, Function, ExtraArgs denotes a function and arguments to determine when enough data is written. The
function should take two additional arguments, the last state, and a list of characters. The function should return
one of:
{done, Result, RestChars}
{more, Continuation}
The Result can be any Erlang term, but if it is a list(), the io_server may convert it to a binary() of appropriate
format before returning it to the client, if the server is set in binary mode (see below).
