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 a IoDevice returned by file:open/2. If no IoDe‐
16       vice is given, standard_io is used.
17
18       For a description of the I/O protocols, see section The Erlang I/O Pro‐
19       tocol in the User's Guide.
20
21   Warning:
22       As from Erlang/OTP R13A, data supplied to function put_chars/2 is to be
23       in the unicode:chardata() format. This means  that  programs  supplying
24       binaries  to  this function must convert them to UTF-8 before trying to
25       output the data on an I/O device.
26
27       If an I/O device is set in binary  mode,  functions  get_chars/2,3  and
28       get_line/1,2 can return binaries instead of lists. The binaries are, as
29       from Erlang/OTP R13A, encoded in UTF-8.
30
31       To work with binaries in ISO Latin-1 encoding, use the file module  in‐
32       stead.
33
34       For  conversion  functions between character encodings, see the unicode
35       module.
36
37

DATA TYPES

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

EXPORTS

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

STANDARD INPUT/OUTPUT

1147       All Erlang processes have a default standard I/O device. This device is
1148       used when no IoDevice argument is specified in the  function  calls  in
1149       this  module.  However,  it  is  sometimes desirable to use an explicit
1150       IoDevice argument that refers to the default I/O device.  This  is  the
1151       case  with  functions  that can access either a file or the default I/O
1152       device. The atom standard_io has this special  meaning.  The  following
1153       example illustrates this:
1154
1155       27> io:read('enter>').
1156       enter>foo.
1157       {ok,foo}
1158       28> io:read(standard_io, 'enter>').
1159       enter>bar.
1160       {ok,bar}
1161
1162       standard_io  is  an  alias  for   group_leader/0, so in order to change
1163       where the default input/output requests are sent  you  can  change  the
1164       group  leader  for  the  current  process  using  group_leader(NewGrou‐
1165       pLeader, self()).
1166
1167       There is always a process registered under the name of user.  This  can
1168       be used for sending output to the user.
1169

STANDARD ERROR

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

ERROR INFORMATION

1182       The ErrorInfo mentioned in this module is the standard ErrorInfo struc‐
1183       ture that is returned from all I/O modules. It has the  following  for‐
1184       mat:
1185
1186       {ErrorLocation, Module, ErrorDescriptor}
1187
1188       A string that describes the error is obtained with the following call:
1189
1190       Module:format_error(ErrorDescriptor)
1191
1192
1193
1194Ericsson AB                       stdlib 4.2                             io(3)
Impressum