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 a IoDevice returned by file:open/2. If no IoDe‐
16 vice is given, standard_io is used.
17 For a description of the I/O protocols, see section The Erlang I/O Pro‐
19 tocol in the User's Guide.
20 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 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 To work with binaries in ISO Latin-1 encoding, use the file module in‐
32 stead.
33 For conversion functions between character encodings, see the unicode
35 module.
36
39 device() = atom() | pid()
40 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 For more information about the built-in devices see Standard In‐
46 put/Output and Standard Error.
47 opt_pair() =
49 {binary, boolean()} |
50 {echo, boolean()} |
51 {expand_fun, expand_fun()} |
52 {encoding, encoding()}
53 expand_fun() =
55 fun((term()) -> {yes | no, string(), [string(), ...]})
56 encoding() =
58 latin1 | unicode | utf8 | utf16 | 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 bi‐
110 nary_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 de‐
121 fault 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 ar‐
155 gument:
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 de‐
170 faults 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 de‐
196 fault 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 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 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 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 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 be‐
378 low 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 in‐
411 sert before the number, but after the leading dash, if any.
412 The prefix can be a possibly deep list of characters or an
414 atom. Example:
415 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 #:
424 Like B, but prints the number with an Erlang style #-sepa‐
425 rated base prefix. Example:
426 1> io:fwrite("~.10#~n", [31]).
428 10#31
429 ok
430 2> io:fwrite("~.16#~n", [-31]).
431 -16#1F
432 ok
433 b:
435 Like B, but prints lowercase letters.
436 x:
438 Like X, but prints lowercase letters.
439 +:
441 Like #, but prints lowercase letters.
442 n:
444 Writes a new line.
445 i:
447 Ignores the next term.
448 The function returns:
450 ok:
452 The formatting succeeded.
453 If an error occurs, there is no output. Example:
455 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 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 fread(Prompt, Format) -> Result
468 fread(IoDevice, Prompt, Format) -> Result
470 Types:
472 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 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 Format can contain the following:
488 * Whitespace characters (Space, Tab, and Newline) that cause
490 input to be read to the next non-whitespace character.
491 * Ordinary characters that must match the next input charac‐
493 ter.
494 * Control sequences, which have the general format ~*FMC,
496 where:
497 * Character * is an optional return suppression character.
499 It provides a method to specify a field that is to be
500 omitted.
501 * F is the field width of the input field.
503 * M is an optional translation modifier (of which t is the
505 only supported, meaning Unicode translation).
506 * C determines the type of control sequence.
508 Unless otherwise specified, leading whitespace is ignored
510 for all control sequences. An input field cannot be more
511 than one line wide.
512 Available control sequences:
514 ~:
516 A single ~ is expected in the input.
517 d:
519 A decimal integer is expected.
520 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 -:
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 #:
533 An integer in base 2-36 with Erlang-style base prefix (for
534 example, "16#ffff") is expected.
535 f:
537 A floating point number is expected. It must follow the
538 Erlang floating point number syntax.
539 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 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 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 a:
559 Similar to s, but the resulting string is converted into
560 an atom.
561 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 The Unicode translation modifier works as with s:
569 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 l:
578 Returns the number of characters that have been scanned up
579 to that point, including whitespace characters.
580 The function returns:
582 {ok, Terms}:
584 The read was successful and Terms is the list of success‐
585 fully matched and read items.
586 eof:
588 End of file was encountered.
589 {error, FreadError}:
591 The reading failed and FreadError gives a hint about the
592 error.
593 {error, ErrorDescription}:
595 The read operation failed and parameter ErrorDescription
596 gives a hint about the error.
597 Examples:
599 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 get_chars(Prompt, Count) -> Data | server_no_data()
611 get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
613 Types:
615 IoDevice = device()
617 Prompt = prompt()
618 Count = integer() >= 0
619 Data = string() | unicode:unicode_binary()
620 server_no_data() = {error, ErrorDescription :: term()} | eof
621 Reads Count characters from standard input (IoDevice), prompting
623 it with Prompt.
624 The function returns:
626 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 eof:
635 End of file was encountered.
636 {error, ErrorDescription}:
638 Other (rare) error condition, such as {error, estale} if
639 reading from an NFS file system.
640 get_line(Prompt) -> Data | server_no_data()
642 get_line(IoDevice, Prompt) -> Data | server_no_data()
644 Types:
646 IoDevice = device()
648 Prompt = prompt()
649 Data = string() | unicode:unicode_binary()
650 server_no_data() = {error, ErrorDescription :: term()} | eof
651 Reads a line from the standard input (IoDevice), prompting it
653 with Prompt.
654 The function returns:
656 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 eof:
665 End of file was encountered.
666 {error, ErrorDescription}:
668 Other (rare) error condition, such as {error, estale} if
669 reading from an NFS file system.
670 getopts() -> [opt_pair()] | {error, Reason}
672 getopts(IoDevice) -> [opt_pair()] | {error, Reason}
674 Types:
676 IoDevice = device()
678 Reason = term()
679 Requests all available options and their current values for a
681 specific I/O device, for example:
682 1> {ok,F} = file:open("/dev/null",[read]).
684 {ok,<0.42.0>}
685 2> io:getopts(F).
686 [{binary,false},{encoding,latin1}]
687 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 3> io:getopts().
693 [{expand_fun,#Fun<group.0.120017273>},
694 {echo,true},
695 {binary,false},
696 {encoding,unicode}]
697 This example is, as can be seen, run in an environment where the
699 terminal supports Unicode input and output.
700 nl() -> ok
702 nl(IoDevice) -> ok
704 Types:
706 IoDevice = device()
708 Writes new line to the standard output (IoDevice).
710 parse_erl_exprs(Prompt) -> Result
712 parse_erl_exprs(IoDevice, Prompt) -> Result
714 parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
716 parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
718 Result
719 Types:
721 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 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 The function returns:
746 {ok, ExprList, EndLocation}:
748 The parsing was successful.
749 {eof, EndLocation}:
751 End of file was encountered by the tokenizer.
752 eof:
754 End of file was encountered by the I/O server.
755 {error, ErrorInfo, ErrorLocation}:
757 An error occurred while tokenizing or parsing.
758 {error, ErrorDescription}:
760 Other (rare) error condition, such as {error, estale} if
761 reading from an NFS file system.
762 Example:
764 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 parse_erl_form(Prompt) -> Result
773 parse_erl_form(IoDevice, Prompt) -> Result
775 parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
777 parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
779 Types:
781 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 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 The function returns:
806 {ok, AbsForm, EndLocation}:
808 The parsing was successful.
809 {eof, EndLocation}:
811 End of file was encountered by the tokenizer.
812 eof:
814 End of file was encountered by the I/O server.
815 {error, ErrorInfo, ErrorLocation}:
817 An error occurred while tokenizing or parsing.
818 {error, ErrorDescription}:
820 Other (rare) error condition, such as {error, estale} if
821 reading from an NFS file system.
822 printable_range() -> unicode | latin1
824 Returns the user-requested range of printable Unicode charac‐
826 ters.
827 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 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 By default, Erlang is started so that only the latin1 range of
840 characters indicate that a list of integers is a string.
841 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 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 put_chars(CharData) -> ok
853 put_chars(IoDevice, CharData) -> ok
855 Types:
857 IoDevice = device()
859 CharData = unicode:chardata()
860 Writes the characters of CharData to the I/O server (IoDevice).
862 read(Prompt) -> Result
864 read(IoDevice, Prompt) -> Result
866 Types:
868 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 Reads a term Term from the standard input (IoDevice), prompting
878 it with Prompt.
879 The function returns:
881 {ok, Term}:
883 The parsing was successful.
884 eof:
886 End of file was encountered.
887 {error, ErrorInfo}:
889 The parsing failed.
890 {error, ErrorDescription}:
892 Other (rare) error condition, such as {error, estale} if
893 reading from an NFS file system.
894 read(IoDevice, Prompt, StartLocation) -> Result
896 read(IoDevice, Prompt, StartLocation, Options) -> Result
898 Types:
900 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 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 The function returns:
918 {ok, Term, EndLocation}:
920 The parsing was successful.
921 {eof, EndLocation}:
923 End of file was encountered.
924 {error, ErrorInfo, ErrorLocation}:
926 The parsing failed.
927 {error, ErrorDescription}:
929 Other (rare) error condition, such as {error, estale} if
930 reading from an NFS file system.
931 rows() -> {ok, integer() >= 1} | {error, enotsup}
933 rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
935 Types:
937 IoDevice = device()
939 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 scan_erl_exprs(Prompt) -> Result
945 scan_erl_exprs(Device, Prompt) -> Result
947 scan_erl_exprs(Device, Prompt, StartLocation) -> Result
949 scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
951 Types:
953 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 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 The function returns:
969 {ok, Tokens, EndLocation}:
971 The tokenization succeeded.
972 {eof, EndLocation}:
974 End of file was encountered by the tokenizer.
975 eof:
977 End of file was encountered by the I/O server.
978 {error, ErrorInfo, ErrorLocation}:
980 An error occurred while tokenizing.
981 {error, ErrorDescription}:
983 Other (rare) error condition, such as {error, estale} if
984 reading from an NFS file system.
985 Example:
987 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 scan_erl_form(Prompt) -> Result
996 scan_erl_form(IoDevice, Prompt) -> Result
998 scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
1000 scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
1002 Types:
1004 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 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 The return values are the same as for scan_erl_exprs/1,2,3,4.
1021 setopts(Opts) -> ok | {error, Reason}
1023 setopts(IoDevice, Opts) -> ok | {error, Reason}
1025 Types:
1027 IoDevice = device()
1029 Opts = [setopt()]
1030 Reason = term()
1031 Set options for the standard I/O device (IoDevice).
1033 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 The options and values supported by the OTP I/O devices are as
1039 follows:
1040 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 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 This option is supported by the standard shell (group.erl),
1056 the 'oldshell' (user.erl), and the file I/O servers.
1057 {echo, boolean()}:
1059 Denotes if the terminal is to echo input. Only supported for
1060 the standard shell I/O server (group.erl)
1061 {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 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 Trivial example (beep on anything except empty line, which
1078 is expanded to "quit"):
1079 fun("") -> {yes, "quit", []};
1081 (_) -> {no, "", ["quit"]} end
1082 This option is only supported by the standard shell
1084 (group.erl).
1085 {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 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 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 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 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 {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 {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 {encoding, utf8} has the same effect as {encoding, unicode}
1130 on files.
1131 The extended encodings are only supported on disk files
1133 (opened by function file:open/2).
1134 write(Term) -> ok
1136 write(IoDevice, Term) -> ok
1138 Types:
1140 IoDevice = device()
1142 Term = term()
1143 Writes term Term to the standard output (IoDevice).
1145
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 27> io:read('enter>').
1156 enter>foo.
1157 {ok,foo}
1158 28> io:read(standard_io, 'enter>').
1159 enter>bar.
1160 {ok,bar}
1161 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 There is always a process registered under the name of user. This can
1168 be used for sending output to the user.
1169
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 $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
1178 'init:stop().' > /dev/null
1179 Error: error 11
1180
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 {ErrorLocation, Module, ErrorDescriptor}
1187 A string that describes the error is obtained with the following call:
1189 Module:format_error(ErrorDescriptor)
1191Ericsson AB stdlib 3.16.1 io(3)