1io(3)                      Erlang Module Definition                      io(3)
2
3
4

NAME

6       io - Standard I/O server interface functions.
7

DESCRIPTION

9       This  module  provides an interface to standard Erlang I/O servers. The
10       output functions all return ok if they are successful, or exit if  they
11       are not.
12
13       All  functions  in  this module have an optional parameter IoDevice. If
14       included, it must be the pid of a process that handles the  I/O  proto‐
15       cols. Normally, it is the IoDevice returned by file:open/2.
16
17       For a description of the I/O protocols, see section The Erlang I/O Pro‐
18       tocol in the User's Guide.
19
20   Warning:
21       As from Erlang/OTP R13A, data supplied to function put_chars/2 is to be
22       in  the  unicode:chardata()  format. This means that programs supplying
23       binaries to this function must convert them to UTF-8 before  trying  to
24       output the data on an I/O device.
25
26       If  an  I/O  device  is set in binary mode, functions get_chars/2,3 and
27       get_line/1,2 can return binaries instead of lists. The binaries are, as
28       from Erlang/OTP R13A, encoded in UTF-8.
29
30       To  work  with  binaries  in  ISO Latin-1 encoding, use the file module
31       instead.
32
33       For conversion functions between character encodings, see  the  unicode
34       module.
35
36

DATA TYPES

38       device() = atom() | pid()
39
40              An  I/O device, either standard_io, standard_error, a registered
41              name,  or  a  pid  handling   I/O   protocols   (returned   from
42              file:open/2).
43
44       opt_pair() =
45           {binary, boolean()} |
46           {echo, boolean()} |
47           {expand_fun, expand_fun()} |
48           {encoding, encoding()}
49
50       expand_fun() =
51           fun((term()) -> {yes | no, string(), [string(), ...]})
52
53       encoding() =
54           latin1 | unicode | utf8 | utf16 | utf32 |
55           {utf16, big | little} |
56           {utf32, big | little}
57
58       setopt() = binary | list | opt_pair()
59
60       format() = atom() | string() | binary()
61
62       location() = erl_anno:location()
63
64       prompt() = atom() | unicode:chardata()
65
66       server_no_data() = {error, ErrorDescription :: term()} | eof
67
68              What the I/O server sends when there is no data.
69

EXPORTS

71       columns() -> {ok, integer() >= 1} | {error, enotsup}
72
73       columns(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
74
75              Types:
76
77                 IoDevice = device()
78
79              Retrieves  the  number  of columns of the IoDevice (that is, the
80              width of a terminal). The function succeeds for terminal devices
81              and returns {error, enotsup} for all other I/O devices.
82
83       format(Format) -> ok
84
85       format(Format, Data) -> ok
86
87       format(IoDevice, Format, Data) -> ok
88
89       fwrite(Format) -> ok
90
91       fwrite(Format, Data) -> ok
92
93       fwrite(IoDevice, Format, Data) -> ok
94
95              Types:
96
97                 IoDevice = device()
98                 Format = format()
99                 Data = [term()]
100
101              Writes  the items in Data ([]) on the standard output (IoDevice)
102              in accordance with Format. Format contains plain characters that
103              are  copied to the output device, and control sequences for for‐
104              matting, see below. If Format is an atom  or  a  binary,  it  is
105              first  converted  to  a  list  with the aid of atom_to_list/1 or
106              binary_to_list/1. Example:
107
108              1> io:fwrite("Hello world!~n", []).
109              Hello world!
110              ok
111
112              The general format of a control sequence is ~F.P.PadModC.
113
114              The character C determines the type of control  sequence  to  be
115              used.  It  is the only required field. All of F, P, Pad, and Mod
116              are optional. For example, to use  a  #  for  Pad  but  use  the
117              default values for F and P, you can write ~..#C.
118
119                * F  is  the  field  width of the printed argument. A negative
120                  value means that the argument is left-justified  within  the
121                  field, otherwise right-justified. If no field width is spec‐
122                  ified, the required print width is used. If the field  width
123                  specified  is  too  small,  the whole field is filled with *
124                  characters.
125
126                * P is the precision of the printed argument. A default  value
127                  is  used if no precision is specified. The interpretation of
128                  precision depends on the control sequences. Unless otherwise
129                  specified, argument within is used to determine print width.
130
131                * Pad  is the padding character. This is the character used to
132                  pad the printed representation of the argument  so  that  it
133                  conforms  to  the  specified field width and precision. Only
134                  one padding character can be specified and, whenever  appli‐
135                  cable,  it  is  used for both the field width and precision.
136                  The default padding character is ' ' (space).
137
138                * Mod is the control sequence modifier. This is  one  or  more
139                  characters  that change the interpretation of Data. The cur‐
140                  rent modifiers are t, for Unicode translation,  and  l,  for
141                  stopping p and P from detecting printable characters.
142
143              If  F,  P, or Pad is a * character, the next argument in Data is
144              used as the value. For example:
145
146              1> io:fwrite("~*.*.0f~n",[9, 5, 3.14159265]).
147              003.14159
148              ok
149
150              To use a literal * character as Pad, it must  be  passed  as  an
151              argument:
152
153              2> io:fwrite("~*.*.*f~n",[9, 5, $*, 3.14159265]).
154              **3.14159
155              ok
156
157              Available control sequences:
158
159                ~:
160                  Character ~ is written.
161
162                c:
163                  The  argument  is  a  number that is interpreted as an ASCII
164                  code. The precision is the number of times the character  is
165                  printed  and  defaults  to  the  field  width, which in turn
166                  defaults to 1. Example:
167
168                1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
169                |     aaaaa|bbbbb     |ccccc|
170                ok
171
172                  If the Unicode translation modifier (t) is  in  effect,  the
173                  integer argument can be any number representing a valid Uni‐
174                  code codepoint, otherwise it is to be an integer  less  than
175                  or equal to 255, otherwise it is masked with 16#FF:
176
177                2> io:fwrite("~tc~n",[1024]).
178                \x{400}
179                ok
180                3> io:fwrite("~c~n",[1024]).
181                ^@
182                ok
183
184                f:
185                  The argument is a float that is written as [-]ddd.ddd, where
186                  the precision is the number  of  digits  after  the  decimal
187                  point. The default precision is 6 and it cannot be < 1.
188
189                e:
190                  The  argument  is a float that is written as [-]d.ddde+-ddd,
191                  where the precision is the number  of  digits  written.  The
192                  default precision is 6 and it cannot be < 2.
193
194                g:
195                  The  argument  is  a float that is written as f, if it is >=
196                  0.1 and < 10000.0. Otherwise, it is written in the e format.
197                  The  precision  is  the  number  of  significant  digits. It
198                  defaults to 6 and is not to be < 2. If the absolute value of
199                  the  float  does  not allow it to be written in the f format
200                  with the desired number of significant digits,  it  is  also
201                  written in the e format.
202
203                s:
204                  Prints the argument with the string syntax. The argument is,
205                  if no Unicode translation modifier is present, an  iolist(),
206                  a  binary(),  or an atom(). If the Unicode translation modi‐
207                  fier (t) is in effect, the argument  is  unicode:chardata(),
208                  meaning  that  binaries  are  in  UTF-8.  The characters are
209                  printed without quotes. The string is first truncated by the
210                  specified  precision  and  then  padded and justified to the
211                  specified field width. The default precision  is  the  field
212                  width.
213
214                  This format can be used for printing any object and truncat‐
215                  ing the output so it fits a specified field:
216
217                1> io:fwrite("|~10w|~n", [{hey, hey, hey}]).
218                |**********|
219                ok
220                2> io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).
221                |{hey,hey,h|
222                3> io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).
223                |{hey,hey  |
224                ok
225
226                  A list with integers > 255 is considered  an  error  if  the
227                  Unicode translation modifier is not specified:
228
229                4> io:fwrite("~ts~n",[[1024]]).
230                \x{400}
231                ok
232                5> io:fwrite("~s~n",[[1024]]).
233                ** exception error: bad argument
234                     in function  io:format/3
235                        called as io:format(<0.53.0>,"~s~n",[[1024]])
236
237                w:
238                  Writes data with the standard syntax. This is used to output
239                  Erlang terms. Atoms are printed within quotes if  they  con‐
240                  tain  embedded  non-printable  characters. Atom characters >
241                  255 are escaped unless the Unicode translation modifier  (t)
242                  is used. Floats are printed accurately as the shortest, cor‐
243                  rectly rounded string.
244
245                p:
246                  Writes the data with standard syntax in the same way as  ~w,
247                  but breaks terms whose printed representation is longer than
248                  one line into many lines and  indents  each  line  sensibly.
249                  Left-justification is not supported. It also tries to detect
250                  flat lists of  printable  characters  and  output  these  as
251                  strings. For example:
252
253                1> T = [{attributes,[[{id,age,1.50000},{mode,explicit},
254                {typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},
255                {typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].
256                2> io:fwrite("~w~n", [T]).
257                [{attributes,[[{id,age,1.5},{mode,explicit},{typename,
258                [73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena
259                me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode
260                ,implicit}]
261                ok
262                3> io:fwrite("~62p~n", [T]).
263                [{attributes,[[{id,age,1.5},
264                               {mode,explicit},
265                               {typename,"INTEGER"}],
266                              [{id,cho},{mode,explicit},{typename,'Cho'}]]},
267                 {typename,'Person'},
268                 {tag,{'PRIVATE',3}},
269                 {mode,implicit}]
270                ok
271
272                  The  field  width  specifies  the  maximum  line  length. It
273                  defaults to 80. The precision specifies the initial indenta‐
274                  tion  of  the  term. It defaults to the number of characters
275                  printed on this line in the same call  to  write/1  or  for‐
276                  mat/1,2,3. For example, using T above:
277
278                4> io:fwrite("Here T = ~62p~n", [T]).
279                Here T = [{attributes,[[{id,age,1.5},
280                                        {mode,explicit},
281                                        {typename,"INTEGER"}],
282                                       [{id,cho},
283                                        {mode,explicit},
284                                        {typename,'Cho'}]]},
285                          {typename,'Person'},
286                          {tag,{'PRIVATE',3}},
287                          {mode,implicit}]
288                ok
289
290                  As  from  Erlang/OTP  21.0,  a field width of value 0 can be
291                  used for specifying that a line is  infinitely  long,  which
292                  means that no line breaks are inserted. For example:
293
294                5> io:fwrite("~0p~n", [lists:seq(1, 30)]).
295                [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30]
296                ok
297
298                  When  the modifier l is specified, no detection of printable
299                  character lists takes place, for example:
300
301                6> S = [{a,"a"}, {b, "b"}], io:fwrite("~15p~n", [S]).
302                [{a,"a"},
303                 {b,"b"}]
304                ok
305                7> io:fwrite("~15lp~n", [S]).
306                [{a,[97]},
307                 {b,[98]}]
308                ok
309
310                  The Unicode translation modifier t specifies  how  to  treat
311                  characters  outside  the  Latin-1  range  of  codepoints, in
312                  atoms, strings, and binaries. For example, printing an  atom
313                  containing a character > 255:
314
315                8> io:fwrite("~p~n",[list_to_atom([1024])]).
316                ok
317                9> io:fwrite("~tp~n",[list_to_atom([1024])]).
318                ok
319
320                  By  default,  Erlang only detects lists of characters in the
321                  Latin-1 range as strings, but the +pc unicode  flag  can  be
322                  used to change this (see printable_range/0 for details). For
323                  example:
324
325                10> io:fwrite("~p~n",[[214]]).
326                "Ö"
327                ok
328                11> io:fwrite("~p~n",[[1024]]).
329                [1024]
330                ok
331                12> io:fwrite("~tp~n",[[1024]]).
332                [1024]
333                ok
334
335
336                  but if Erlang was started with +pc unicode:
337
338                13> io:fwrite("~p~n",[[1024]]).
339                [1024]
340                ok
341                14> io:fwrite("~tp~n",[[1024]]).
342                "Ѐ"
343                ok
344
345                  Similarly, binaries that look like UTF-8 encoded strings are
346                  output  with  the  binary string syntax if the t modifier is
347                  specified:
348
349                15> io:fwrite("~p~n", [<<208,128>>]).
350                <<208,128>>
351                ok
352                16> io:fwrite("~tp~n", [<<208,128>>]).
353                <<"Ѐ"/utf8>>
354                ok
355                17> io:fwrite("~tp~n", [<<128,128>>]).
356                <<128,128>>
357                ok
358
359                W:
360                  Writes data in the same way as ~w, but takes an extra  argu‐
361                  ment  that  is the maximum depth to which terms are printed.
362                  Anything below this depth is replaced with .... For example,
363                  using T above:
364
365                8> io:fwrite("~W~n", [T,9]).
366                [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
367                [{id,cho},{mode,...},{...}]]},{typename,'Person'},
368                {tag,{'PRIVATE',3}},{mode,implicit}]
369                ok
370
371                  If  the  maximum  depth is reached, it cannot be read in the
372                  resultant output. Also, the ,... form  in  a  tuple  denotes
373                  that  there  are  more  elements  in the tuple but these are
374                  below the print depth.
375
376                P:
377                  Writes data in the same way as ~p, but takes an extra  argu‐
378                  ment  that  is the maximum depth to which terms are printed.
379                  Anything below this depth is replaced with ..., for example:
380
381                9> io:fwrite("~62P~n", [T,9]).
382                [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
383                              [{id,cho},{mode,...},{...}]]},
384                 {typename,'Person'},
385                 {tag,{'PRIVATE',3}},
386                 {mode,implicit}]
387                ok
388
389                B:
390                  Writes an integer in base 2-36, the default base  is  10.  A
391                  leading dash is printed for negative integers.
392
393                  The precision field selects base, for example:
394
395                1> io:fwrite("~.16B~n", [31]).
396                1F
397                ok
398                2> io:fwrite("~.2B~n", [-19]).
399                -10011
400                ok
401                3> io:fwrite("~.36B~n", [5*36+35]).
402                5Z
403                ok
404
405                X:
406                  Like  B,  but  takes  an  extra argument that is a prefix to
407                  insert before the number, but after  the  leading  dash,  if
408                  any.
409
410                  The  prefix  can be a possibly deep list of characters or an
411                  atom. Example:
412
413                1> io:fwrite("~X~n", [31,"10#"]).
414                10#31
415                ok
416                2> io:fwrite("~.16X~n", [-31,"0x"]).
417                -0x1F
418                ok
419
420                #:
421                  Like B, but prints the number with an Erlang  style  #-sepa‐
422                  rated base prefix. Example:
423
424                1> io:fwrite("~.10#~n", [31]).
425                10#31
426                ok
427                2> io:fwrite("~.16#~n", [-31]).
428                -16#1F
429                ok
430
431                b:
432                  Like B, but prints lowercase letters.
433
434                x:
435                  Like X, but prints lowercase letters.
436
437                +:
438                  Like #, but prints lowercase letters.
439
440                n:
441                  Writes a new line.
442
443                i:
444                  Ignores the next term.
445
446              The function returns:
447
448                ok:
449                  The formatting succeeded.
450
451              If an error occurs, there is no output. Example:
452
453              1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
454              abc def 'abc def'  {foo,1} A
455              ok
456              2> io:fwrite("~s", [65]).
457              ** exception error: bad argument
458                   in function  io:format/3
459                      called as io:format(<0.53.0>,"~s","A")
460
461              In  this example, an attempt was made to output the single char‐
462              acter 65 with the aid of the string formatting directive "~s".
463
464       fread(Prompt, Format) -> Result
465
466       fread(IoDevice, Prompt, Format) -> Result
467
468              Types:
469
470                 IoDevice = device()
471                 Prompt = prompt()
472                 Format = format()
473                 Result =
474                     {ok, Terms :: [term()]} |
475                     {error, {fread, FreadError :: io_lib:fread_error()}} |
476                     server_no_data()
477                 server_no_data() = {error, ErrorDescription :: term()} | eof
478
479              Reads characters from the standard input  (IoDevice),  prompting
480              it  with  Prompt.  Interprets  the characters in accordance with
481              Format. Format  contains  control  sequences  that  directs  the
482              interpretation of the input.
483
484              Format can contain the following:
485
486                * Whitespace  characters  (Space, Tab, and Newline) that cause
487                  input to be read to the next non-whitespace character.
488
489                * Ordinary characters that must match the next  input  charac‐
490                  ter.
491
492                * Control  sequences,  which  have  the  general format ~*FMC,
493                  where:
494
495                  * Character * is an optional return  suppression  character.
496                    It  provides  a  method  to  specify a field that is to be
497                    omitted.
498
499                  * F is the field width of the input field.
500
501                  * M is an optional translation modifier (of which t  is  the
502                    only supported, meaning Unicode translation).
503
504                  * C determines the type of control sequence.
505
506                  Unless  otherwise  specified,  leading whitespace is ignored
507                  for all control sequences. An input  field  cannot  be  more
508                  than one line wide.
509
510                  Available control sequences:
511
512                  ~:
513                    A single ~ is expected in the input.
514
515                  d:
516                    A decimal integer is expected.
517
518                  u:
519                    An  unsigned  integer  in base 2-36 is expected. The field
520                    width parameter is used to specify  base.  Leading  white‐
521                    space characters are not skipped.
522
523                  -:
524                    An optional sign character is expected. A sign character -
525                    gives return value -1. Sign character + or none  gives  1.
526                    The  field  width parameter is ignored. Leading whitespace
527                    characters are not skipped.
528
529                  #:
530                    An integer in base 2-36 with Erlang-style base prefix (for
531                    example, "16#ffff") is expected.
532
533                  f:
534                    A  floating  point  number is expected. It must follow the
535                    Erlang floating point number syntax.
536
537                  s:
538                    A string of non-whitespace characters is read. If a  field
539                    width  has  been  specified, this number of characters are
540                    read and all trailing whitespace characters are  stripped.
541                    An Erlang string (list of characters) is returned.
542
543                    If  Unicode  translation  is in effect (~ts), characters >
544                    255 are accepted, otherwise not. With the translation mod‐
545                    ifier, the returned list can as a consequence also contain
546                    integers > 255:
547
548                  1> io:fread("Prompt> ","~s").
549                  Prompt> <Characters beyond latin1 range not printable in this medium>
550                  {error,{fread,string}}
551                  2> io:fread("Prompt> ","~ts").
552                  Prompt> <Characters beyond latin1 range not printable in this medium>
553                  {ok,[[1091,1085,1080,1094,1086,1076,1077]]}
554
555                  a:
556                    Similar to s, but the resulting string is  converted  into
557                    an atom.
558
559                  c:
560                    The number of characters equal to the field width are read
561                    (default is 1) and returned as an Erlang string.  However,
562                    leading and trailing whitespace characters are not omitted
563                    as they are with s. All characters are returned.
564
565                    The Unicode translation modifier works as with s:
566
567                  1> io:fread("Prompt> ","~c").
568                  Prompt> <Character beyond latin1 range not printable in this medium>
569                  {error,{fread,string}}
570                  2> io:fread("Prompt> ","~tc").
571                  Prompt> <Character beyond latin1 range not printable in this medium>
572                  {ok,[[1091]]}
573
574                  l:
575                    Returns the number of characters that have been scanned up
576                    to that point, including whitespace characters.
577
578                  The function returns:
579
580                  {ok, Terms}:
581                    The  read was successful and Terms is the list of success‐
582                    fully matched and read items.
583
584                  eof:
585                    End of file was encountered.
586
587                  {error, FreadError}:
588                    The reading failed and FreadError gives a hint  about  the
589                    error.
590
591                  {error, ErrorDescription}:
592                    The  read  operation failed and parameter ErrorDescription
593                    gives a hint about the error.
594
595              Examples:
596
597              20> io:fread('enter>', "~f~f~f").
598              enter>1.9 35.5e3 15.0
599              {ok,[1.9,3.55e4,15.0]}
600              21> io:fread('enter>', "~10f~d").
601              enter>     5.67899
602              {ok,[5.678,99]}
603              22> io:fread('enter>', ":~10s:~10c:").
604              enter>:   alan   :   joe    :
605              {ok, ["alan", "   joe    "]}
606
607       get_chars(Prompt, Count) -> Data | server_no_data()
608
609       get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
610
611              Types:
612
613                 IoDevice = device()
614                 Prompt = prompt()
615                 Count = integer() >= 0
616                 Data = string() | unicode:unicode_binary()
617                 server_no_data() = {error, ErrorDescription :: term()} | eof
618
619              Reads Count characters from standard input (IoDevice), prompting
620              it with Prompt.
621
622              The function returns:
623
624                Data:
625                  The  input  characters.  If the I/O device supports Unicode,
626                  the data can represent codepoints > 255 (the latin1  range).
627                  If  the  I/O  server  is  set  to deliver binaries, they are
628                  encoded in UTF-8 (regardless of whether the I/O device  sup‐
629                  ports Unicode).
630
631                eof:
632                  End of file was encountered.
633
634                {error, ErrorDescription}:
635                  Other  (rare)  error  condition,  such as {error, estale} if
636                  reading from an NFS file system.
637
638       get_line(Prompt) -> Data | server_no_data()
639
640       get_line(IoDevice, Prompt) -> Data | server_no_data()
641
642              Types:
643
644                 IoDevice = device()
645                 Prompt = prompt()
646                 Data = string() | unicode:unicode_binary()
647                 server_no_data() = {error, ErrorDescription :: term()} | eof
648
649              Reads a line from the standard input  (IoDevice),  prompting  it
650              with Prompt.
651
652              The function returns:
653
654                Data:
655                  The characters in the line terminated by a line feed (or end
656                  of file). If the I/O device supports Unicode, the  data  can
657                  represent  codepoints  >  255 (the latin1 range). If the I/O
658                  server is set to deliver binaries, they are encoded in UTF-8
659                  (regardless of if the I/O device supports Unicode).
660
661                eof:
662                  End of file was encountered.
663
664                {error, ErrorDescription}:
665                  Other  (rare)  error  condition,  such as {error, estale} if
666                  reading from an NFS file system.
667
668       getopts() -> [opt_pair()] | {error, Reason}
669
670       getopts(IoDevice) -> [opt_pair()] | {error, Reason}
671
672              Types:
673
674                 IoDevice = device()
675                 Reason = term()
676
677              Requests all available options and their current  values  for  a
678              specific I/O device, for example:
679
680              1> {ok,F} = file:open("/dev/null",[read]).
681              {ok,<0.42.0>}
682              2> io:getopts(F).
683              [{binary,false},{encoding,latin1}]
684
685              Here  the  file  I/O  server returns all available options for a
686              file, which are the expected ones, encoding and binary. However,
687              the standard shell has some more options:
688
689              3> io:getopts().
690              [{expand_fun,#Fun<group.0.120017273>},
691               {echo,true},
692               {binary,false},
693               {encoding,unicode}]
694
695              This example is, as can be seen, run in an environment where the
696              terminal supports Unicode input and output.
697
698       nl() -> ok
699
700       nl(IoDevice) -> ok
701
702              Types:
703
704                 IoDevice = device()
705
706              Writes new line to the standard output (IoDevice).
707
708       parse_erl_exprs(Prompt) -> Result
709
710       parse_erl_exprs(IoDevice, Prompt) -> Result
711
712       parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
713
714       parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
715                          Result
716
717              Types:
718
719                 IoDevice = device()
720                 Prompt = prompt()
721                 StartLocation = location()
722                 Options = erl_scan:options()
723                 Result = parse_ret()
724                 parse_ret() =
725                     {ok,
726                      ExprList :: [erl_parse:abstract_expr()],
727                      EndLocation :: location()} |
728                     {eof, EndLocation :: location()} |
729                     {error,
730                      ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
731                      ErrorLocation :: location()} |
732                     server_no_data()
733                 server_no_data() = {error, ErrorDescription :: term()} | eof
734
735              Reads data from the standard input (IoDevice), prompting it with
736              Prompt.  Starts  reading at location StartLocation (1). Argument
737              Options  is  passed  on  as   argument   Options   of   function
738              erl_scan:tokens/4. The data is tokenized and parsed as if it was
739              a sequence of Erlang  expressions  until  a  final  dot  (.)  is
740              reached.
741
742              The function returns:
743
744                {ok, ExprList, EndLocation}:
745                  The parsing was successful.
746
747                {eof, EndLocation}:
748                  End of file was encountered by the tokenizer.
749
750                eof:
751                  End of file was encountered by the I/O server.
752
753                {error, ErrorInfo, ErrorLocation}:
754                  An error occurred while tokenizing or parsing.
755
756                {error, ErrorDescription}:
757                  Other  (rare)  error  condition,  such as {error, estale} if
758                  reading from an NFS file system.
759
760              Example:
761
762              25> io:parse_erl_exprs('enter>').
763              enter>abc(), "hey".
764              {ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
765              26> io:parse_erl_exprs ('enter>').
766              enter>abc("hey".
767              {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
768
769       parse_erl_form(Prompt) -> Result
770
771       parse_erl_form(IoDevice, Prompt) -> Result
772
773       parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
774
775       parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
776
777              Types:
778
779                 IoDevice = device()
780                 Prompt = prompt()
781                 StartLocation = location()
782                 Options = erl_scan:options()
783                 Result = parse_form_ret()
784                 parse_form_ret() =
785                     {ok,
786                      AbsForm :: erl_parse:abstract_form(),
787                      EndLocation :: location()} |
788                     {eof, EndLocation :: location()} |
789                     {error,
790                      ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
791                      ErrorLocation :: location()} |
792                     server_no_data()
793                 server_no_data() = {error, ErrorDescription :: term()} | eof
794
795              Reads data from the standard input (IoDevice), prompting it with
796              Prompt.  Starts  reading at location StartLocation (1). Argument
797              Options  is  passed  on  as   argument   Options   of   function
798              erl_scan:tokens/4. The data is tokenized and parsed as if it was
799              an Erlang form (one of the valid Erlang expressions in an Erlang
800              source file) until a final dot (.) is reached.
801
802              The function returns:
803
804                {ok, AbsForm, EndLocation}:
805                  The parsing was successful.
806
807                {eof, EndLocation}:
808                  End of file was encountered by the tokenizer.
809
810                eof:
811                  End of file was encountered by the I/O server.
812
813                {error, ErrorInfo, ErrorLocation}:
814                  An error occurred while tokenizing or parsing.
815
816                {error, ErrorDescription}:
817                  Other  (rare)  error  condition,  such as {error, estale} if
818                  reading from an NFS file system.
819
820       printable_range() -> unicode | latin1
821
822              Returns the user-requested range of  printable  Unicode  charac‐
823              ters.
824
825              The  user  can request a range of characters that are to be con‐
826              sidered printable in heuristic detection of strings by the shell
827              and  by  the formatting functions. This is done by supplying +pc
828              <range> when starting Erlang.
829
830              The only valid values for <range> are latin1 and unicode. latin1
831              means  that  only  code points < 256 (except control characters,
832              and so on) are considered  printable.  unicode  means  that  all
833              printable characters in all Unicode character ranges are consid‐
834              ered printable by the I/O functions.
835
836              By default, Erlang is started so that only the latin1  range  of
837              characters indicate that a list of integers is a string.
838
839              The  simplest  way  to  use the setting is to call io_lib:print‐
840              able_list/1, which uses the return value  of  this  function  to
841              decide if a list is a string of printable characters.
842
843          Note:
844              In  a  future  release, this function may return more values and
845              ranges. To avoid compatibility problems, it  is  recommended  to
846              use function io_lib:printable_list/1.
847
848
849       put_chars(CharData) -> ok
850
851       put_chars(IoDevice, CharData) -> ok
852
853              Types:
854
855                 IoDevice = device()
856                 CharData = unicode:chardata()
857
858              Writes the characters of CharData to the I/O server (IoDevice).
859
860       read(Prompt) -> Result
861
862       read(IoDevice, Prompt) -> Result
863
864              Types:
865
866                 IoDevice = device()
867                 Prompt = prompt()
868                 Result =
869                     {ok,  Term :: term()} | server_no_data() | {error, Error‐
870                 Info}
871                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
872                 server_no_data() = {error, ErrorDescription :: term()} | eof
873
874              Reads a term Term from the standard input (IoDevice),  prompting
875              it with Prompt.
876
877              The function returns:
878
879                {ok, Term}:
880                  The parsing was successful.
881
882                eof:
883                  End of file was encountered.
884
885                {error, ErrorInfo}:
886                  The parsing failed.
887
888                {error, ErrorDescription}:
889                  Other  (rare)  error  condition,  such as {error, estale} if
890                  reading from an NFS file system.
891
892       read(IoDevice, Prompt, StartLocation) -> Result
893
894       read(IoDevice, Prompt, StartLocation, Options) -> Result
895
896              Types:
897
898                 IoDevice = device()
899                 Prompt = prompt()
900                 StartLocation = location()
901                 Options = erl_scan:options()
902                 Result =
903                     {ok, Term :: term(), EndLocation :: location()} |
904                     {eof, EndLocation :: location()} |
905                     server_no_data() |
906                     {error, ErrorInfo, ErrorLocation :: location()}
907                 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
908                 server_no_data() = {error, ErrorDescription :: term()} | eof
909
910              Reads a term Term from IoDevice, prompting it with Prompt. Read‐
911              ing starts at location StartLocation. Argument Options is passed
912              on as argument Options of function erl_scan:tokens/4.
913
914              The function returns:
915
916                {ok, Term, EndLocation}:
917                  The parsing was successful.
918
919                {eof, EndLocation}:
920                  End of file was encountered.
921
922                {error, ErrorInfo, ErrorLocation}:
923                  The parsing failed.
924
925                {error, ErrorDescription}:
926                  Other (rare) error condition, such  as  {error,  estale}  if
927                  reading from an NFS file system.
928
929       rows() -> {ok, integer() >= 1} | {error, enotsup}
930
931       rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
932
933              Types:
934
935                 IoDevice = device()
936
937              Retrieves the number of rows of IoDevice (that is, the height of
938              a terminal). The function only succeeds  for  terminal  devices,
939              for all other I/O devices the function returns {error, enotsup}.
940
941       scan_erl_exprs(Prompt) -> Result
942
943       scan_erl_exprs(Device, Prompt) -> Result
944
945       scan_erl_exprs(Device, Prompt, StartLocation) -> Result
946
947       scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
948
949              Types:
950
951                 Device = device()
952                 Prompt = prompt()
953                 StartLocation = location()
954                 Options = erl_scan:options()
955                 Result = erl_scan:tokens_result() | server_no_data()
956                 server_no_data() = {error, ErrorDescription :: term()} | eof
957
958              Reads data from the standard input (IoDevice), prompting it with
959              Prompt. Reading starts at location StartLocation  (1).  Argument
960              Options   is   passed   on   as  argument  Options  of  function
961              erl_scan:tokens/4. The  data  is  tokenized  as  if  it  were  a
962              sequence of Erlang expressions until a final dot (.) is reached.
963              This token is also returned.
964
965              The function returns:
966
967                {ok, Tokens, EndLocation}:
968                  The tokenization succeeded.
969
970                {eof, EndLocation}:
971                  End of file was encountered by the tokenizer.
972
973                eof:
974                  End of file was encountered by the I/O server.
975
976                {error, ErrorInfo, ErrorLocation}:
977                  An error occurred while tokenizing.
978
979                {error, ErrorDescription}:
980                  Other (rare) error condition, such  as  {error,  estale}  if
981                  reading from an NFS file system.
982
983              Example:
984
985              23> io:scan_erl_exprs('enter>').
986              enter>abc(), "hey".
987              {ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
988              24> io:scan_erl_exprs('enter>').
989              enter>1.0er.
990              {error,{1,erl_scan,{illegal,float}},2}
991
992       scan_erl_form(Prompt) -> Result
993
994       scan_erl_form(IoDevice, Prompt) -> Result
995
996       scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
997
998       scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
999
1000              Types:
1001
1002                 IoDevice = device()
1003                 Prompt = prompt()
1004                 StartLocation = location()
1005                 Options = erl_scan:options()
1006                 Result = erl_scan:tokens_result() | server_no_data()
1007                 server_no_data() = {error, ErrorDescription :: term()} | eof
1008
1009              Reads data from the standard input (IoDevice), prompting it with
1010              Prompt. Starts reading at location StartLocation  (1).  Argument
1011              Options   is   passed   on   as  argument  Options  of  function
1012              erl_scan:tokens/4. The data is tokenized as if it was an  Erlang
1013              form  (one  of  the valid Erlang expressions in an Erlang source
1014              file) until a final dot (.) is reached. This last token is  also
1015              returned.
1016
1017              The return values are the same as for scan_erl_exprs/1,2,3,4.
1018
1019       setopts(Opts) -> ok | {error, Reason}
1020
1021       setopts(IoDevice, Opts) -> ok | {error, Reason}
1022
1023              Types:
1024
1025                 IoDevice = device()
1026                 Opts = [setopt()]
1027                 Reason = term()
1028
1029              Set options for the standard I/O device (IoDevice).
1030
1031              Possible  options  and  values vary depending on the I/O device.
1032              For a list of supported options and their current  values  on  a
1033              specific I/O device, use function getopts/1.
1034
1035              The  options  and values supported by the OTP I/O devices are as
1036              follows:
1037
1038                binary, list, or {binary, boolean()}:
1039                  If set in binary mode (binary or {binary,  true}),  the  I/O
1040                  server  sends  binary  data (encoded in UTF-8) as answers to
1041                  the  get_line,  get_chars,  and,  if   possible,   get_until
1042                  requests  (for details, see section The Erlang I/O Protocol)
1043                  in  the  User's  Guide).  The  immediate  effect   is   that
1044                  get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead
1045                  of lists of characters for the affected I/O device.
1046
1047                  By default, all I/O devices in OTP are  set  in  list  mode.
1048                  However, the I/O functions can handle any of these modes and
1049                  so should other, user-written, modules behaving  as  clients
1050                  to I/O servers.
1051
1052                  This  option is supported by the standard shell (group.erl),
1053                  the 'oldshell' (user.erl), and the file I/O servers.
1054
1055                {echo, boolean()}:
1056                  Denotes if the terminal is to echo input. Only supported for
1057                  the standard shell I/O server (group.erl)
1058
1059                {expand_fun, expand_fun()}:
1060                  Provides  a function for tab-completion (expansion) like the
1061                  Erlang shell. This function is called when the user  presses
1062                  the Tab key. The expansion is active when calling line-read‐
1063                  ing functions, such as get_line/1,2.
1064
1065                  The function is called with the current line, up to the cur‐
1066                  sor,  as  a  reversed string. It is to return a three-tuple:
1067                  {yes|no, string(), [string(), ...]}. The first element gives
1068                  a  beep if no, otherwise the expansion is silent; the second
1069                  is a string that will be entered at the cursor position; the
1070                  third  is a list of possible expansions. If this list is not
1071                  empty, it is printed and the current input line  is  written
1072                  once again.
1073
1074                  Trivial  example  (beep on anything except empty line, which
1075                  is expanded to "quit"):
1076
1077                fun("") -> {yes, "quit", []};
1078                   (_) -> {no, "", ["quit"]} end
1079
1080                  This  option  is  only  supported  by  the  standard   shell
1081                  (group.erl).
1082
1083                {encoding, latin1 | unicode}:
1084                  Specifies  how characters are input or output from or to the
1085                  I/O device, implying that, for example, a terminal is set to
1086                  handle  Unicode  input and output or a file is set to handle
1087                  UTF-8 data encoding.
1088
1089                  The option does not affect how data is returned from the I/O
1090                  functions  or  how  it  is sent in the I/O protocol, it only
1091                  affects how the I/O device is to handle  Unicode  characters
1092                  to the "physical" device.
1093
1094                  The  standard  shell  is  set for unicode or latin1 encoding
1095                  when the system is started. The encoding  is  set  with  the
1096                  help  of the LANG or LC_CTYPE environment variables on Unix-
1097                  like system or by other means on other systems. So, the user
1098                  can  input  Unicode  characters  and  the  I/O  device is in
1099                  {encoding, unicode} mode if the I/O device supports it.  The
1100                  mode can be changed, if the assumption of the runtime system
1101                  is wrong, by setting this option.
1102
1103                  The I/O device used when Erlang is started with  the  "-old‐
1104                  shell"  or  "-noshell"  flags  is  by  default set to latin1
1105                  encoding, meaning that any characters >  codepoint  255  are
1106                  escaped  and  that  input  is expected to be plain 8-bit ISO
1107                  Latin-1. If the encoding is changed to  Unicode,  input  and
1108                  output  from  the  standard  file  descriptors  are in UTF-8
1109                  (regardless of operating system).
1110
1111                  Files can also be set in {encoding, unicode},  meaning  that
1112                  data is written and read as UTF-8. More encodings are possi‐
1113                  ble for files, see below.
1114
1115                  {encoding, unicode | latin1} is supported by both the  stan‐
1116                  dard  shell (group.erl including werl on Windows), the 'old‐
1117                  shell' (user.erl), and the file I/O servers.
1118
1119                {encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little}
1120                | {utf32,big} | {utf32,little}}:
1121                  For disk files, the encoding can be set to various UTF vari‐
1122                  ants. This has the effect that data is expected to  be  read
1123                  as  the  specified  encoding  from the file, and the data is
1124                  written in the specified encoding to the disk file.
1125
1126                  {encoding, utf8} has the same effect as {encoding,  unicode}
1127                  on files.
1128
1129                  The  extended  encodings  are  only  supported on disk files
1130                  (opened by function file:open/2).
1131
1132       write(Term) -> ok
1133
1134       write(IoDevice, Term) -> ok
1135
1136              Types:
1137
1138                 IoDevice = device()
1139                 Term = term()
1140
1141              Writes term Term to the standard output (IoDevice).
1142

STANDARD INPUT/OUTPUT

1144       All Erlang processes have a default standard I/O device. This device is
1145       used  when  no  IoDevice argument is specified in the function calls in
1146       this module. However, it is sometimes  desirable  to  use  an  explicit
1147       IoDevice  argument  that  refers to the default I/O device. This is the
1148       case with functions that can access either a file or  the  default  I/O
1149       device.  The  atom  standard_io has this special meaning. The following
1150       example illustrates this:
1151
1152       27> io:read('enter>').
1153       enter>foo.
1154       {ok,foo}
1155       28> io:read(standard_io, 'enter>').
1156       enter>bar.
1157       {ok,bar}
1158
1159       There is always a process registered under the name of user.  This  can
1160       be used for sending output to the user.
1161

STANDARD ERROR

1163       In  certain  situations,  especially  when the standard output is redi‐
1164       rected, access to an I/O server specific for error messages can be con‐
1165       venient.  The I/O device standard_error can be used to direct output to
1166       whatever the current operating system considers a suitable  I/O  device
1167       for error output. Example on a Unix-like operating system:
1168
1169       $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
1170       'init:stop().' > /dev/null
1171       Error: error 11
1172

ERROR INFORMATION

1174       The ErrorInfo mentioned in this module is the standard ErrorInfo struc‐
1175       ture that is returned from all I/O modules. It has the  following  for‐
1176       mat:
1177
1178       {ErrorLocation, Module, ErrorDescriptor}
1179
1180       A string that describes the error is obtained with the following call:
1181
1182       Module:format_error(ErrorDescriptor)
1183
1184
1185
1186Ericsson AB                      stdlib 3.12.1                           io(3)
Impressum