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

FreeBSD Manual Pages

  
 
  

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  in-
       stead.

       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 ac-
		  tually 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 ex-
	      ception of control characters etc) will be considered printable.
	      unicode means that all printable characters in all unicode char-
	      acter 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 de-
	      vice. 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 af-
		  fects	how the	IO device is to	handle Unicode characters  to-
		  wards	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  en-
		  coding,  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 bi-
	      nary_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 de-
		  fault	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 de-
		  faults 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 ex-
		  ample:

		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  de-
		  faults  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  in-
		  sert 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  in-
	      terpretation 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  Er-
	      lang  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+12.0-RELEASE+and+Ports>

home | help