1io(3) Erlang Module Definition io(3)
2
6 io - Standard I/O server interface functions.
7
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 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 For a description of the I/O protocols, see section The Erlang I/O Pro‐
18 tocol in the User's Guide.
19 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 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 To work with binaries in ISO Latin-1 encoding, use the file module
31 instead.
32 For conversion functions between character encodings, see the unicode
34 module.
35
38 device() = atom() | pid()
39 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 opt_pair() =
45 {binary, boolean()} |
46 {echo, boolean()} |
47 {expand_fun, expand_fun()} |
48 {encoding, encoding()}
49 expand_fun() =
51 fun((term()) -> {yes | no, string(), [string(), ...]})
52 encoding() =
54 latin1 | unicode | utf8 | utf16 | utf32 |
55 {utf16, big | little} |
56 {utf32, big | little}
57 setopt() = binary | list | opt_pair()
59 format() = atom() | string() | binary()
61 location() = erl_anno:location()
63 prompt() = atom() | unicode:chardata()
65 server_no_data() = {error, ErrorDescription :: term()} | eof
67 What the I/O server sends when there is no data.
69
71 columns() -> {ok, integer() >= 1} | {error, enotsup}
72 columns(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
74 Types:
76 IoDevice = device()
78 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 format(Format) -> ok
84 format(Format, Data) -> ok
86 format(IoDevice, Format, Data) -> ok
88 fwrite(Format) -> ok
90 fwrite(Format, Data) -> ok
92 fwrite(IoDevice, Format, Data) -> ok
94 Types:
96 IoDevice = device()
98 Format = format()
99 Data = [term()]
100 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 1> io:fwrite("Hello world!~n", []).
109 Hello world!
110 ok
111 The general format of a control sequence is ~F.P.PadModC.
113 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 * 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 * 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 * 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 * 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 If F, P, or Pad is a * character, the next argument in Data is
144 used as the value. For example:
145 1> io:fwrite("~*.*.0f~n",[9, 5, 3.14159265]).
147 003.14159
148 ok
149 To use a literal * character as Pad, it must be passed as an
151 argument:
152 2> io:fwrite("~*.*.*f~n",[9, 5, $*, 3.14159265]).
154 **3.14159
155 ok
156 Available control sequences:
158 ~:
160 Character ~ is written.
161 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 1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
169 | aaaaa|bbbbb |ccccc|
170 ok
171 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 2> io:fwrite("~tc~n",[1024]).
178 \x{400}
179 ok
180 3> io:fwrite("~c~n",[1024]).
181 ^@
182 ok
183 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 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 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 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 This format can be used for printing any object and truncat‐
215 ing the output so it fits a specified field:
216 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 A list with integers > 255 is considered an error if the
227 Unicode translation modifier is not specified:
228 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 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 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 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 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 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 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 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 When the modifier l is specified, no detection of printable
299 character lists takes place, for example:
300 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 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 8> io:fwrite("~p~n",[list_to_atom([1024])]).
316 ok
317 9> io:fwrite("~tp~n",[list_to_atom([1024])]).
318 ok
319 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 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 but if Erlang was started with +pc unicode:
337 13> io:fwrite("~p~n",[[1024]]).
339 [1024]
340 ok
341 14> io:fwrite("~tp~n",[[1024]]).
342 "Ѐ"
343 ok
344 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 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 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 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 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 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 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 B:
390 Writes an integer in base 2-36, the default base is 10. A
391 leading dash is printed for negative integers.
392 The precision field selects base, for example:
394 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 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 The prefix can be a possibly deep list of characters or an
411 atom. Example:
412 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 #:
421 Like B, but prints the number with an Erlang style #-sepa‐
422 rated base prefix. Example:
423 1> io:fwrite("~.10#~n", [31]).
425 10#31
426 ok
427 2> io:fwrite("~.16#~n", [-31]).
428 -16#1F
429 ok
430 b:
432 Like B, but prints lowercase letters.
433 x:
435 Like X, but prints lowercase letters.
436 +:
438 Like #, but prints lowercase letters.
439 n:
441 Writes a new line.
442 i:
444 Ignores the next term.
445 The function returns:
447 ok:
449 The formatting succeeded.
450 If an error occurs, there is no output. Example:
452 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 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 fread(Prompt, Format) -> Result
465 fread(IoDevice, Prompt, Format) -> Result
467 Types:
469 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 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 Format can contain the following:
485 * Whitespace characters (Space, Tab, and Newline) that cause
487 input to be read to the next non-whitespace character.
488 * Ordinary characters that must match the next input charac‐
490 ter.
491 * Control sequences, which have the general format ~*FMC,
493 where:
494 * Character * is an optional return suppression character.
496 It provides a method to specify a field that is to be
497 omitted.
498 * F is the field width of the input field.
500 * M is an optional translation modifier (of which t is the
502 only supported, meaning Unicode translation).
503 * C determines the type of control sequence.
505 Unless otherwise specified, leading whitespace is ignored
507 for all control sequences. An input field cannot be more
508 than one line wide.
509 Available control sequences:
511 ~:
513 A single ~ is expected in the input.
514 d:
516 A decimal integer is expected.
517 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 -:
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 #:
530 An integer in base 2-36 with Erlang-style base prefix (for
531 example, "16#ffff") is expected.
532 f:
534 A floating point number is expected. It must follow the
535 Erlang floating point number syntax.
536 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 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 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 a:
556 Similar to s, but the resulting string is converted into
557 an atom.
558 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 The Unicode translation modifier works as with s:
566 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 l:
575 Returns the number of characters that have been scanned up
576 to that point, including whitespace characters.
577 The function returns:
579 {ok, Terms}:
581 The read was successful and Terms is the list of success‐
582 fully matched and read items.
583 eof:
585 End of file was encountered.
586 {error, FreadError}:
588 The reading failed and FreadError gives a hint about the
589 error.
590 {error, ErrorDescription}:
592 The read operation failed and parameter ErrorDescription
593 gives a hint about the error.
594 Examples:
596 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 get_chars(Prompt, Count) -> Data | server_no_data()
608 get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
610 Types:
612 IoDevice = device()
614 Prompt = prompt()
615 Count = integer() >= 0
616 Data = string() | unicode:unicode_binary()
617 server_no_data() = {error, ErrorDescription :: term()} | eof
618 Reads Count characters from standard input (IoDevice), prompting
620 it with Prompt.
621 The function returns:
623 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 eof:
632 End of file was encountered.
633 {error, ErrorDescription}:
635 Other (rare) error condition, such as {error, estale} if
636 reading from an NFS file system.
637 get_line(Prompt) -> Data | server_no_data()
639 get_line(IoDevice, Prompt) -> Data | server_no_data()
641 Types:
643 IoDevice = device()
645 Prompt = prompt()
646 Data = string() | unicode:unicode_binary()
647 server_no_data() = {error, ErrorDescription :: term()} | eof
648 Reads a line from the standard input (IoDevice), prompting it
650 with Prompt.
651 The function returns:
653 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 eof:
662 End of file was encountered.
663 {error, ErrorDescription}:
665 Other (rare) error condition, such as {error, estale} if
666 reading from an NFS file system.
667 getopts() -> [opt_pair()] | {error, Reason}
669 getopts(IoDevice) -> [opt_pair()] | {error, Reason}
671 Types:
673 IoDevice = device()
675 Reason = term()
676 Requests all available options and their current values for a
678 specific I/O device, for example:
679 1> {ok,F} = file:open("/dev/null",[read]).
681 {ok,<0.42.0>}
682 2> io:getopts(F).
683 [{binary,false},{encoding,latin1}]
684 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 3> io:getopts().
690 [{expand_fun,#Fun<group.0.120017273>},
691 {echo,true},
692 {binary,false},
693 {encoding,unicode}]
694 This example is, as can be seen, run in an environment where the
696 terminal supports Unicode input and output.
697 nl() -> ok
699 nl(IoDevice) -> ok
701 Types:
703 IoDevice = device()
705 Writes new line to the standard output (IoDevice).
707 parse_erl_exprs(Prompt) -> Result
709 parse_erl_exprs(IoDevice, Prompt) -> Result
711 parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
713 parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
715 Result
716 Types:
718 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 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 The function returns:
743 {ok, ExprList, EndLocation}:
745 The parsing was successful.
746 {eof, EndLocation}:
748 End of file was encountered by the tokenizer.
749 eof:
751 End of file was encountered by the I/O server.
752 {error, ErrorInfo, ErrorLocation}:
754 An error occurred while tokenizing or parsing.
755 {error, ErrorDescription}:
757 Other (rare) error condition, such as {error, estale} if
758 reading from an NFS file system.
759 Example:
761 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 parse_erl_form(Prompt) -> Result
770 parse_erl_form(IoDevice, Prompt) -> Result
772 parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
774 parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
776 Types:
778 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 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 The function returns:
803 {ok, AbsForm, EndLocation}:
805 The parsing was successful.
806 {eof, EndLocation}:
808 End of file was encountered by the tokenizer.
809 eof:
811 End of file was encountered by the I/O server.
812 {error, ErrorInfo, ErrorLocation}:
814 An error occurred while tokenizing or parsing.
815 {error, ErrorDescription}:
817 Other (rare) error condition, such as {error, estale} if
818 reading from an NFS file system.
819 printable_range() -> unicode | latin1
821 Returns the user-requested range of printable Unicode charac‐
823 ters.
824 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 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 By default, Erlang is started so that only the latin1 range of
837 characters indicate that a list of integers is a string.
838 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 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 put_chars(CharData) -> ok
850 put_chars(IoDevice, CharData) -> ok
852 Types:
854 IoDevice = device()
856 CharData = unicode:chardata()
857 Writes the characters of CharData to the I/O server (IoDevice).
859 read(Prompt) -> Result
861 read(IoDevice, Prompt) -> Result
863 Types:
865 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 Reads a term Term from the standard input (IoDevice), prompting
875 it with Prompt.
876 The function returns:
878 {ok, Term}:
880 The parsing was successful.
881 eof:
883 End of file was encountered.
884 {error, ErrorInfo}:
886 The parsing failed.
887 {error, ErrorDescription}:
889 Other (rare) error condition, such as {error, estale} if
890 reading from an NFS file system.
891 read(IoDevice, Prompt, StartLocation) -> Result
893 read(IoDevice, Prompt, StartLocation, Options) -> Result
895 Types:
897 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 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 The function returns:
915 {ok, Term, EndLocation}:
917 The parsing was successful.
918 {eof, EndLocation}:
920 End of file was encountered.
921 {error, ErrorInfo, ErrorLocation}:
923 The parsing failed.
924 {error, ErrorDescription}:
926 Other (rare) error condition, such as {error, estale} if
927 reading from an NFS file system.
928 rows() -> {ok, integer() >= 1} | {error, enotsup}
930 rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
932 Types:
934 IoDevice = device()
936 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 scan_erl_exprs(Prompt) -> Result
942 scan_erl_exprs(Device, Prompt) -> Result
944 scan_erl_exprs(Device, Prompt, StartLocation) -> Result
946 scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
948 Types:
950 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 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 The function returns:
966 {ok, Tokens, EndLocation}:
968 The tokenization succeeded.
969 {eof, EndLocation}:
971 End of file was encountered by the tokenizer.
972 eof:
974 End of file was encountered by the I/O server.
975 {error, ErrorInfo, ErrorLocation}:
977 An error occurred while tokenizing.
978 {error, ErrorDescription}:
980 Other (rare) error condition, such as {error, estale} if
981 reading from an NFS file system.
982 Example:
984 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 scan_erl_form(Prompt) -> Result
993 scan_erl_form(IoDevice, Prompt) -> Result
995 scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
997 scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
999 Types:
1001 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 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 The return values are the same as for scan_erl_exprs/1,2,3,4.
1018 setopts(Opts) -> ok | {error, Reason}
1020 setopts(IoDevice, Opts) -> ok | {error, Reason}
1022 Types:
1024 IoDevice = device()
1026 Opts = [setopt()]
1027 Reason = term()
1028 Set options for the standard I/O device (IoDevice).
1030 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 The options and values supported by the OTP I/O devices are as
1036 follows:
1037 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 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 This option is supported by the standard shell (group.erl),
1053 the 'oldshell' (user.erl), and the file I/O servers.
1054 {echo, boolean()}:
1056 Denotes if the terminal is to echo input. Only supported for
1057 the standard shell I/O server (group.erl)
1058 {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 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 Trivial example (beep on anything except empty line, which
1075 is expanded to "quit"):
1076 fun("") -> {yes, "quit", []};
1078 (_) -> {no, "", ["quit"]} end
1079 This option is only supported by the standard shell
1081 (group.erl).
1082 {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 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 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 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 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 {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 {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 {encoding, utf8} has the same effect as {encoding, unicode}
1127 on files.
1128 The extended encodings are only supported on disk files
1130 (opened by function file:open/2).
1131 write(Term) -> ok
1133 write(IoDevice, Term) -> ok
1135 Types:
1137 IoDevice = device()
1139 Term = term()
1140 Writes term Term to the standard output (IoDevice).
1142
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 27> io:read('enter>').
1153 enter>foo.
1154 {ok,foo}
1155 28> io:read(standard_io, 'enter>').
1156 enter>bar.
1157 {ok,bar}
1158 There is always a process registered under the name of user. This can
1160 be used for sending output to the user.
1161
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 $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
1170 'init:stop().' > /dev/null
1171 Error: error 11
1172
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 {ErrorLocation, Module, ErrorDescriptor}
1179 A string that describes the error is obtained with the following call:
1181 Module:format_error(ErrorDescriptor)
1183Ericsson AB stdlib 3.10 io(3)