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 |
55 unicode |
56 utf8 |
57 utf16 |
58 utf32 |
59 {utf16, big | little} |
60 {utf32, big | little}
61 setopt() = binary | list | opt_pair()
63 format() = atom() | string() | binary()
65 location() = erl_anno:location()
67 prompt() = atom() | unicode:chardata()
69 server_no_data() = {error, ErrorDescription :: term()} | eof
71 What the I/O server sends when there is no data.
73
75 columns() -> {ok, integer() >= 1} | {error, enotsup}
76 columns(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
78 Types:
80 IoDevice = device()
82 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 format(Format) -> ok
88 format(Format, Data) -> ok
90 format(IoDevice, Format, Data) -> ok
92 fwrite(Format) -> ok
94 fwrite(Format, Data) -> ok
96 fwrite(IoDevice, Format, Data) -> ok
98 Types:
100 IoDevice = device()
102 Format = format()
103 Data = [term()]
104 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
110 binary_to_list/1. Example:
111 1> io:fwrite("Hello world!~n", []).
113 Hello world!
114 ok
115 The general format of a control sequence is ~F.P.PadModC.
117 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
121 default values for F and P, you can write ~..#C.
122 * 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 * 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 * 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 * 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 If F, P, or Pad is a * character, the next argument in Data is
148 used as the value. For example:
149 1> io:fwrite("~*.*.0f~n",[9, 5, 3.14159265]).
151 003.14159
152 ok
153 To use a literal * character as Pad, it must be passed as an
155 argument:
156 2> io:fwrite("~*.*.*f~n",[9, 5, $*, 3.14159265]).
158 **3.14159
159 ok
160 Available control sequences:
162 ~:
164 Character ~ is written.
165 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
170 defaults to 1. Example:
171 1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
173 | aaaaa|bbbbb |ccccc|
174 ok
175 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 2> io:fwrite("~tc~n",[1024]).
182 \x{400}
183 ok
184 3> io:fwrite("~c~n",[1024]).
185 ^@
186 ok
187 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 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
196 default precision is 6 and it cannot be < 2.
197 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
202 defaults 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 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 This format can be used for printing any object and truncat‐
219 ing the output so it fits a specified field:
220 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 A list with integers > 255 is considered an error if the
231 Unicode translation modifier is not specified:
232 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 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 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 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 The field width specifies the maximum line length. It
277 defaults 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 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 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 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 When the modifier l is specified, no detection of printable
303 character lists takes place, for example:
304 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 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 8> io:fwrite("~p~n",[list_to_atom([1024])]).
320 ok
321 9> io:fwrite("~tp~n",[list_to_atom([1024])]).
322 ok
323 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 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 but if Erlang was started with +pc unicode:
341 13> io:fwrite("~p~n",[[1024]]).
343 [1024]
344 ok
345 14> io:fwrite("~tp~n",[[1024]]).
346 "Ѐ"
347 ok
348 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 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 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 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 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
378 below the print depth.
379 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 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 B:
394 Writes an integer in base 2-36, the default base is 10. A
395 leading dash is printed for negative integers.
396 The precision field selects base, for example:
398 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 X:
410 Like B, but takes an extra argument that is a prefix to
411 insert before the number, but after the leading dash, if
412 any.
413 The prefix can be a possibly deep list of characters or an
415 atom. Example:
416 1> io:fwrite("~X~n", [31,"10#"]).
418 10#31
419 ok
420 2> io:fwrite("~.16X~n", [-31,"0x"]).
421 -0x1F
422 ok
423 #:
425 Like B, but prints the number with an Erlang style #-sepa‐
426 rated base prefix. Example:
427 1> io:fwrite("~.10#~n", [31]).
429 10#31
430 ok
431 2> io:fwrite("~.16#~n", [-31]).
432 -16#1F
433 ok
434 b:
436 Like B, but prints lowercase letters.
437 x:
439 Like X, but prints lowercase letters.
440 +:
442 Like #, but prints lowercase letters.
443 n:
445 Writes a new line.
446 i:
448 Ignores the next term.
449 The function returns:
451 ok:
453 The formatting succeeded.
454 If an error occurs, there is no output. Example:
456 1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
458 abc def 'abc def' {foo,1} A
459 ok
460 2> io:fwrite("~s", [65]).
461 ** exception error: bad argument
462 in function io:format/3
463 called as io:format(<0.53.0>,"~s","A")
464 In this example, an attempt was made to output the single char‐
466 acter 65 with the aid of the string formatting directive "~s".
467 fread(Prompt, Format) -> Result
469 fread(IoDevice, Prompt, Format) -> Result
471 Types:
473 IoDevice = device()
475 Prompt = prompt()
476 Format = format()
477 Result =
478 {ok, Terms :: [term()]} |
479 {error, {fread, FreadError :: io_lib:fread_error()}} |
480 server_no_data()
481 server_no_data() = {error, ErrorDescription :: term()} | eof
482 Reads characters from the standard input (IoDevice), prompting
484 it with Prompt. Interprets the characters in accordance with
485 Format. Format contains control sequences that directs the
486 interpretation of the input.
487 Format can contain the following:
489 * Whitespace characters (Space, Tab, and Newline) that cause
491 input to be read to the next non-whitespace character.
492 * Ordinary characters that must match the next input charac‐
494 ter.
495 * Control sequences, which have the general format ~*FMC,
497 where:
498 * Character * is an optional return suppression character.
500 It provides a method to specify a field that is to be
501 omitted.
502 * F is the field width of the input field.
504 * M is an optional translation modifier (of which t is the
506 only supported, meaning Unicode translation).
507 * C determines the type of control sequence.
509 Unless otherwise specified, leading whitespace is ignored
511 for all control sequences. An input field cannot be more
512 than one line wide.
513 Available control sequences:
515 ~:
517 A single ~ is expected in the input.
518 d:
520 A decimal integer is expected.
521 u:
523 An unsigned integer in base 2-36 is expected. The field
524 width parameter is used to specify base. Leading white‐
525 space characters are not skipped.
526 -:
528 An optional sign character is expected. A sign character -
529 gives return value -1. Sign character + or none gives 1.
530 The field width parameter is ignored. Leading whitespace
531 characters are not skipped.
532 #:
534 An integer in base 2-36 with Erlang-style base prefix (for
535 example, "16#ffff") is expected.
536 f:
538 A floating point number is expected. It must follow the
539 Erlang floating point number syntax.
540 s:
542 A string of non-whitespace characters is read. If a field
543 width has been specified, this number of characters are
544 read and all trailing whitespace characters are stripped.
545 An Erlang string (list of characters) is returned.
546 If Unicode translation is in effect (~ts), characters >
548 255 are accepted, otherwise not. With the translation mod‐
549 ifier, the returned list can as a consequence also contain
550 integers > 255:
551 1> io:fread("Prompt> ","~s").
553 Prompt> <Characters beyond latin1 range not printable in this medium>
554 {error,{fread,string}}
555 2> io:fread("Prompt> ","~ts").
556 Prompt> <Characters beyond latin1 range not printable in this medium>
557 {ok,[[1091,1085,1080,1094,1086,1076,1077]]}
558 a:
560 Similar to s, but the resulting string is converted into
561 an atom.
562 c:
564 The number of characters equal to the field width are read
565 (default is 1) and returned as an Erlang string. However,
566 leading and trailing whitespace characters are not omitted
567 as they are with s. All characters are returned.
568 The Unicode translation modifier works as with s:
570 1> io:fread("Prompt> ","~c").
572 Prompt> <Character beyond latin1 range not printable in this medium>
573 {error,{fread,string}}
574 2> io:fread("Prompt> ","~tc").
575 Prompt> <Character beyond latin1 range not printable in this medium>
576 {ok,[[1091]]}
577 l:
579 Returns the number of characters that have been scanned up
580 to that point, including whitespace characters.
581 The function returns:
583 {ok, Terms}:
585 The read was successful and Terms is the list of success‐
586 fully matched and read items.
587 eof:
589 End of file was encountered.
590 {error, FreadError}:
592 The reading failed and FreadError gives a hint about the
593 error.
594 {error, ErrorDescription}:
596 The read operation failed and parameter ErrorDescription
597 gives a hint about the error.
598 Examples:
600 20> io:fread('enter>', "~f~f~f").
602 enter>1.9 35.5e3 15.0
603 {ok,[1.9,3.55e4,15.0]}
604 21> io:fread('enter>', "~10f~d").
605 enter> 5.67899
606 {ok,[5.678,99]}
607 22> io:fread('enter>', ":~10s:~10c:").
608 enter>: alan : joe :
609 {ok, ["alan", " joe "]}
610 get_chars(Prompt, Count) -> Data | server_no_data()
612 get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
614 Types:
616 IoDevice = device()
618 Prompt = prompt()
619 Count = integer() >= 0
620 Data = string() | unicode:unicode_binary()
621 server_no_data() = {error, ErrorDescription :: term()} | eof
622 Reads Count characters from standard input (IoDevice), prompting
624 it with Prompt.
625 The function returns:
627 Data:
629 The input characters. If the I/O device supports Unicode,
630 the data can represent codepoints > 255 (the latin1 range).
631 If the I/O server is set to deliver binaries, they are
632 encoded in UTF-8 (regardless of whether the I/O device sup‐
633 ports Unicode).
634 eof:
636 End of file was encountered.
637 {error, ErrorDescription}:
639 Other (rare) error condition, such as {error, estale} if
640 reading from an NFS file system.
641 get_line(Prompt) -> Data | server_no_data()
643 get_line(IoDevice, Prompt) -> Data | server_no_data()
645 Types:
647 IoDevice = device()
649 Prompt = prompt()
650 Data = string() | unicode:unicode_binary()
651 server_no_data() = {error, ErrorDescription :: term()} | eof
652 Reads a line from the standard input (IoDevice), prompting it
654 with Prompt.
655 The function returns:
657 Data:
659 The characters in the line terminated by a line feed (or end
660 of file). If the I/O device supports Unicode, the data can
661 represent codepoints > 255 (the latin1 range). If the I/O
662 server is set to deliver binaries, they are encoded in UTF-8
663 (regardless of if the I/O device supports Unicode).
664 eof:
666 End of file was encountered.
667 {error, ErrorDescription}:
669 Other (rare) error condition, such as {error, estale} if
670 reading from an NFS file system.
671 getopts() -> [opt_pair()] | {error, Reason}
673 getopts(IoDevice) -> [opt_pair()] | {error, Reason}
675 Types:
677 IoDevice = device()
679 Reason = term()
680 Requests all available options and their current values for a
682 specific I/O device, for example:
683 1> {ok,F} = file:open("/dev/null",[read]).
685 {ok,<0.42.0>}
686 2> io:getopts(F).
687 [{binary,false},{encoding,latin1}]
688 Here the file I/O server returns all available options for a
690 file, which are the expected ones, encoding and binary. However,
691 the standard shell has some more options:
692 3> io:getopts().
694 [{expand_fun,#Fun<group.0.120017273>},
695 {echo,true},
696 {binary,false},
697 {encoding,unicode}]
698 This example is, as can be seen, run in an environment where the
700 terminal supports Unicode input and output.
701 nl() -> ok
703 nl(IoDevice) -> ok
705 Types:
707 IoDevice = device()
709 Writes new line to the standard output (IoDevice).
711 parse_erl_exprs(Prompt) -> Result
713 parse_erl_exprs(IoDevice, Prompt) -> Result
715 parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
717 parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
719 Result
720 Types:
722 IoDevice = device()
724 Prompt = prompt()
725 StartLocation = location()
726 Options = erl_scan:options()
727 Result = parse_ret()
728 parse_ret() =
729 {ok,
730 ExprList :: [erl_parse:abstract_expr()],
731 EndLocation :: location()} |
732 {eof, EndLocation :: location()} |
733 {error,
734 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
735 ErrorLocation :: location()} |
736 server_no_data()
737 server_no_data() = {error, ErrorDescription :: term()} | eof
738 Reads data from the standard input (IoDevice), prompting it with
740 Prompt. Starts reading at location StartLocation (1). Argument
741 Options is passed on as argument Options of function
742 erl_scan:tokens/4. The data is tokenized and parsed as if it was
743 a sequence of Erlang expressions until a final dot (.) is
744 reached.
745 The function returns:
747 {ok, ExprList, EndLocation}:
749 The parsing was successful.
750 {eof, EndLocation}:
752 End of file was encountered by the tokenizer.
753 eof:
755 End of file was encountered by the I/O server.
756 {error, ErrorInfo, ErrorLocation}:
758 An error occurred while tokenizing or parsing.
759 {error, ErrorDescription}:
761 Other (rare) error condition, such as {error, estale} if
762 reading from an NFS file system.
763 Example:
765 25> io:parse_erl_exprs('enter>').
767 enter>abc(), "hey".
768 {ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
769 26> io:parse_erl_exprs ('enter>').
770 enter>abc("hey".
771 {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
772 parse_erl_form(Prompt) -> Result
774 parse_erl_form(IoDevice, Prompt) -> Result
776 parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
778 parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
780 Types:
782 IoDevice = device()
784 Prompt = prompt()
785 StartLocation = location()
786 Options = erl_scan:options()
787 Result = parse_form_ret()
788 parse_form_ret() =
789 {ok,
790 AbsForm :: erl_parse:abstract_form(),
791 EndLocation :: location()} |
792 {eof, EndLocation :: location()} |
793 {error,
794 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
795 ErrorLocation :: location()} |
796 server_no_data()
797 server_no_data() = {error, ErrorDescription :: term()} | eof
798 Reads data from the standard input (IoDevice), prompting it with
800 Prompt. Starts reading at location StartLocation (1). Argument
801 Options is passed on as argument Options of function
802 erl_scan:tokens/4. The data is tokenized and parsed as if it was
803 an Erlang form (one of the valid Erlang expressions in an Erlang
804 source file) until a final dot (.) is reached.
805 The function returns:
807 {ok, AbsForm, EndLocation}:
809 The parsing was successful.
810 {eof, EndLocation}:
812 End of file was encountered by the tokenizer.
813 eof:
815 End of file was encountered by the I/O server.
816 {error, ErrorInfo, ErrorLocation}:
818 An error occurred while tokenizing or parsing.
819 {error, ErrorDescription}:
821 Other (rare) error condition, such as {error, estale} if
822 reading from an NFS file system.
823 printable_range() -> unicode | latin1
825 Returns the user-requested range of printable Unicode charac‐
827 ters.
828 The user can request a range of characters that are to be con‐
830 sidered printable in heuristic detection of strings by the shell
831 and by the formatting functions. This is done by supplying +pc
832 <range> when starting Erlang.
833 The only valid values for <range> are latin1 and unicode. latin1
835 means that only code points < 256 (except control characters,
836 and so on) are considered printable. unicode means that all
837 printable characters in all Unicode character ranges are consid‐
838 ered printable by the I/O functions.
839 By default, Erlang is started so that only the latin1 range of
841 characters indicate that a list of integers is a string.
842 The simplest way to use the setting is to call io_lib:print‐
844 able_list/1, which uses the return value of this function to
845 decide if a list is a string of printable characters.
846 Note:
848 In a future release, this function may return more values and
849 ranges. To avoid compatibility problems, it is recommended to
850 use function io_lib:printable_list/1.
851 put_chars(CharData) -> ok
854 put_chars(IoDevice, CharData) -> ok
856 Types:
858 IoDevice = device()
860 CharData = unicode:chardata()
861 Writes the characters of CharData to the I/O server (IoDevice).
863 read(Prompt) -> Result
865 read(IoDevice, Prompt) -> Result
867 Types:
869 IoDevice = device()
871 Prompt = prompt()
872 Result =
873 {ok, Term :: term()} | server_no_data() | {error, Error‐
874 Info}
875 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
876 server_no_data() = {error, ErrorDescription :: term()} | eof
877 Reads a term Term from the standard input (IoDevice), prompting
879 it with Prompt.
880 The function returns:
882 {ok, Term}:
884 The parsing was successful.
885 eof:
887 End of file was encountered.
888 {error, ErrorInfo}:
890 The parsing failed.
891 {error, ErrorDescription}:
893 Other (rare) error condition, such as {error, estale} if
894 reading from an NFS file system.
895 read(IoDevice, Prompt, StartLocation) -> Result
897 read(IoDevice, Prompt, StartLocation, Options) -> Result
899 Types:
901 IoDevice = device()
903 Prompt = prompt()
904 StartLocation = location()
905 Options = erl_scan:options()
906 Result =
907 {ok, Term :: term(), EndLocation :: location()} |
908 {eof, EndLocation :: location()} |
909 server_no_data() |
910 {error, ErrorInfo, ErrorLocation :: location()}
911 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
912 server_no_data() = {error, ErrorDescription :: term()} | eof
913 Reads a term Term from IoDevice, prompting it with Prompt. Read‐
915 ing starts at location StartLocation. Argument Options is passed
916 on as argument Options of function erl_scan:tokens/4.
917 The function returns:
919 {ok, Term, EndLocation}:
921 The parsing was successful.
922 {eof, EndLocation}:
924 End of file was encountered.
925 {error, ErrorInfo, ErrorLocation}:
927 The parsing failed.
928 {error, ErrorDescription}:
930 Other (rare) error condition, such as {error, estale} if
931 reading from an NFS file system.
932 rows() -> {ok, integer() >= 1} | {error, enotsup}
934 rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
936 Types:
938 IoDevice = device()
940 Retrieves the number of rows of IoDevice (that is, the height of
942 a terminal). The function only succeeds for terminal devices,
943 for all other I/O devices the function returns {error, enotsup}.
944 scan_erl_exprs(Prompt) -> Result
946 scan_erl_exprs(Device, Prompt) -> Result
948 scan_erl_exprs(Device, Prompt, StartLocation) -> Result
950 scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
952 Types:
954 Device = device()
956 Prompt = prompt()
957 StartLocation = location()
958 Options = erl_scan:options()
959 Result = erl_scan:tokens_result() | server_no_data()
960 server_no_data() = {error, ErrorDescription :: term()} | eof
961 Reads data from the standard input (IoDevice), prompting it with
963 Prompt. Reading starts at location StartLocation (1). Argument
964 Options is passed on as argument Options of function
965 erl_scan:tokens/4. The data is tokenized as if it were a
966 sequence of Erlang expressions until a final dot (.) is reached.
967 This token is also returned.
968 The function returns:
970 {ok, Tokens, EndLocation}:
972 The tokenization succeeded.
973 {eof, EndLocation}:
975 End of file was encountered by the tokenizer.
976 eof:
978 End of file was encountered by the I/O server.
979 {error, ErrorInfo, ErrorLocation}:
981 An error occurred while tokenizing.
982 {error, ErrorDescription}:
984 Other (rare) error condition, such as {error, estale} if
985 reading from an NFS file system.
986 Example:
988 23> io:scan_erl_exprs('enter>').
990 enter>abc(), "hey".
991 {ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
992 24> io:scan_erl_exprs('enter>').
993 enter>1.0er.
994 {error,{1,erl_scan,{illegal,float}},2}
995 scan_erl_form(Prompt) -> Result
997 scan_erl_form(IoDevice, Prompt) -> Result
999 scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
1001 scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
1003 Types:
1005 IoDevice = device()
1007 Prompt = prompt()
1008 StartLocation = location()
1009 Options = erl_scan:options()
1010 Result = erl_scan:tokens_result() | server_no_data()
1011 server_no_data() = {error, ErrorDescription :: term()} | eof
1012 Reads data from the standard input (IoDevice), prompting it with
1014 Prompt. Starts reading at location StartLocation (1). Argument
1015 Options is passed on as argument Options of function
1016 erl_scan:tokens/4. The data is tokenized as if it was an Erlang
1017 form (one of the valid Erlang expressions in an Erlang source
1018 file) until a final dot (.) is reached. This last token is also
1019 returned.
1020 The return values are the same as for scan_erl_exprs/1,2,3,4.
1022 setopts(Opts) -> ok | {error, Reason}
1024 setopts(IoDevice, Opts) -> ok | {error, Reason}
1026 Types:
1028 IoDevice = device()
1030 Opts = [setopt()]
1031 Reason = term()
1032 Set options for the standard I/O device (IoDevice).
1034 Possible options and values vary depending on the I/O device.
1036 For a list of supported options and their current values on a
1037 specific I/O device, use function getopts/1.
1038 The options and values supported by the OTP I/O devices are as
1040 follows:
1041 binary, list, or {binary, boolean()}:
1043 If set in binary mode (binary or {binary, true}), the I/O
1044 server sends binary data (encoded in UTF-8) as answers to
1045 the get_line, get_chars, and, if possible, get_until
1046 requests (for details, see section The Erlang I/O Protocol)
1047 in the User's Guide). The immediate effect is that
1048 get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead
1049 of lists of characters for the affected I/O device.
1050 By default, all I/O devices in OTP are set in list mode.
1052 However, the I/O functions can handle any of these modes and
1053 so should other, user-written, modules behaving as clients
1054 to I/O servers.
1055 This option is supported by the standard shell (group.erl),
1057 the 'oldshell' (user.erl), and the file I/O servers.
1058 {echo, boolean()}:
1060 Denotes if the terminal is to echo input. Only supported for
1061 the standard shell I/O server (group.erl)
1062 {expand_fun, expand_fun()}:
1064 Provides a function for tab-completion (expansion) like the
1065 Erlang shell. This function is called when the user presses
1066 the Tab key. The expansion is active when calling line-read‐
1067 ing functions, such as get_line/1,2.
1068 The function is called with the current line, up to the cur‐
1070 sor, as a reversed string. It is to return a three-tuple:
1071 {yes|no, string(), [string(), ...]}. The first element gives
1072 a beep if no, otherwise the expansion is silent; the second
1073 is a string that will be entered at the cursor position; the
1074 third is a list of possible expansions. If this list is not
1075 empty, it is printed and the current input line is written
1076 once again.
1077 Trivial example (beep on anything except empty line, which
1079 is expanded to "quit"):
1080 fun("") -> {yes, "quit", []};
1082 (_) -> {no, "", ["quit"]} end
1083 This option is only supported by the standard shell
1085 (group.erl).
1086 {encoding, latin1 | unicode}:
1088 Specifies how characters are input or output from or to the
1089 I/O device, implying that, for example, a terminal is set to
1090 handle Unicode input and output or a file is set to handle
1091 UTF-8 data encoding.
1092 The option does not affect how data is returned from the I/O
1094 functions or how it is sent in the I/O protocol, it only
1095 affects how the I/O device is to handle Unicode characters
1096 to the "physical" device.
1097 The standard shell is set for unicode or latin1 encoding
1099 when the system is started. The encoding is set with the
1100 help of the LANG or LC_CTYPE environment variables on Unix-
1101 like system or by other means on other systems. So, the user
1102 can input Unicode characters and the I/O device is in
1103 {encoding, unicode} mode if the I/O device supports it. The
1104 mode can be changed, if the assumption of the runtime system
1105 is wrong, by setting this option.
1106 The I/O device used when Erlang is started with the "-old‐
1108 shell" or "-noshell" flags is by default set to latin1
1109 encoding, meaning that any characters > codepoint 255 are
1110 escaped and that input is expected to be plain 8-bit ISO
1111 Latin-1. If the encoding is changed to Unicode, input and
1112 output from the standard file descriptors are in UTF-8
1113 (regardless of operating system).
1114 Files can also be set in {encoding, unicode}, meaning that
1116 data is written and read as UTF-8. More encodings are possi‐
1117 ble for files, see below.
1118 {encoding, unicode | latin1} is supported by both the stan‐
1120 dard shell (group.erl including werl on Windows), the 'old‐
1121 shell' (user.erl), and the file I/O servers.
1122 {encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little}
1124 | {utf32,big} | {utf32,little}}:
1125 For disk files, the encoding can be set to various UTF vari‐
1126 ants. This has the effect that data is expected to be read
1127 as the specified encoding from the file, and the data is
1128 written in the specified encoding to the disk file.
1129 {encoding, utf8} has the same effect as {encoding, unicode}
1131 on files.
1132 The extended encodings are only supported on disk files
1134 (opened by function file:open/2).
1135 write(Term) -> ok
1137 write(IoDevice, Term) -> ok
1139 Types:
1141 IoDevice = device()
1143 Term = term()
1144 Writes term Term to the standard output (IoDevice).
1146
1148 All Erlang processes have a default standard I/O device. This device is
1149 used when no IoDevice argument is specified in the function calls in
1150 this module. However, it is sometimes desirable to use an explicit
1151 IoDevice argument that refers to the default I/O device. This is the
1152 case with functions that can access either a file or the default I/O
1153 device. The atom standard_io has this special meaning. The following
1154 example illustrates this:
1155 27> io:read('enter>').
1157 enter>foo.
1158 {ok,foo}
1159 28> io:read(standard_io, 'enter>').
1160 enter>bar.
1161 {ok,bar}
1162 There is always a process registered under the name of user. This can
1164 be used for sending output to the user.
1165
1167 In certain situations, especially when the standard output is redi‐
1168 rected, access to an I/O server specific for error messages can be con‐
1169 venient. The I/O device standard_error can be used to direct output to
1170 whatever the current operating system considers a suitable I/O device
1171 for error output. Example on a Unix-like operating system:
1172 $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
1174 'init:stop().' > /dev/null
1175 Error: error 11
1176
1178 The ErrorInfo mentioned in this module is the standard ErrorInfo struc‐
1179 ture that is returned from all I/O modules. It has the following for‐
1180 mat:
1181 {ErrorLocation, Module, ErrorDescriptor}
1183 A string that describes the error is obtained with the following call:
1185 Module:format_error(ErrorDescriptor)
1187Ericsson AB stdlib 3.8.2.1 io(3)