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 rep-
		  resent 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 con-
	      sidered 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  uni-
	      code.  latin1  means  that  only code points below 256 (with the
	      exception	of control characters etc) will	be  considered	print-
	      able. 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:print-
	      able_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-read-
		  ing functions	such as	get_line/1,2.

		  The function is called with the current line,	upto the  cur-
		  sor,	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 vari-
		  ables	on Unix-like system or by other	means  on  other  sys-
		  tems.	 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	"-old-
		  shell" 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	possi-
		  ble for files, see below.

		  {encoding,  unicode |	latin1}	is supported by	both the stan-
		  dard 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 vari-
		  ants.	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. Read-
	      ing starts at location StartLocation. The	 argument  Options  is
	      passed on	as the Options argument	of the erl_scan:tokens/4 func-
	      tion. 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 spec-
	      ified, 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	preci-
	      sion  depends  on	the control sequences. Unless otherwise	speci-
	      fied, 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 sup-
	      ported) 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 charac-
		  ter 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 Uni-
		  code	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 deci-
		  mal 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 modi-
		  fier (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 truncat-
		  ing 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 con-
		  tain	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 indenta-
		  tion 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 char-
		  acter	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 argu-
		  ment 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 argu-
		  ment 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  #-sepa-
		  rated	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 char-
	      acter 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 charac-
		  ter.

		* 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  sup-
		  ported,  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	conse-
		    quence 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	 omit-
		    ted	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  success-
		    fully 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	 ErrorDescrip-
		    tion 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	 argu-
	      ment  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	 argu-
	      ment  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 argu-
	      ment 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 argu-
	      ment 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	illus-
       trates 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	 redi-
       rected,	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