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

FreeBSD Manual 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_anno: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,	Error-
		 Info}
		 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.
		  Left justification is	not supported. It also tries to	detect
		  lists	 of  printable	characters  and	 to  output  these  as
		  strings. The Unicode translation modifier is used for	deter-
		  mining 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.8				 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+11.0-RELEASE+and+Ports>

home | help