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 Character C determines the type of control sequence to be used,
119 F and P are optional numeric arguments. If F, P, or Pad is *,
120 the next argument in Data is used as the numeric value of F or
121 P.
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. It is either a single
143 character (t, for Unicode translation, and l, for stopping p
144 and P from detecting printable characters) that changes the
145 interpretation of Data.
146 Available control sequences:
148 ~:
150 Character ~ is written.
151 c:
153 The argument is a number that is interpreted as an ASCII
154 code. The precision is the number of times the character is
155 printed and defaults to the field width, which in turn
156 defaults to 1. Example:
157 1> io:fwrite("|~10.5c|~-10.5c|~5c|~n", [$a, $b, $c]).
159 | aaaaa|bbbbb |ccccc|
160 ok
161 If the Unicode translation modifier (t) is in effect, the
163 integer argument can be any number representing a valid Uni‐
164 code codepoint, otherwise it is to be an integer less than
165 or equal to 255, otherwise it is masked with 16#FF:
166 2> io:fwrite("~tc~n",[1024]).
168 \x{400}
169 ok
170 3> io:fwrite("~c~n",[1024]).
171 ^@
172 ok
173 f:
175 The argument is a float that is written as [-]ddd.ddd, where
176 the precision is the number of digits after the decimal
177 point. The default precision is 6 and it cannot be < 1.
178 e:
180 The argument is a float that is written as [-]d.ddde+-ddd,
181 where the precision is the number of digits written. The
182 default precision is 6 and it cannot be < 2.
183 g:
185 The argument is a float that is written as f, if it is >=
186 0.1 and < 10000.0. Otherwise, it is written in the e format.
187 The precision is the number of significant digits. It
188 defaults to 6 and is not to be < 2. If the absolute value of
189 the float does not allow it to be written in the f format
190 with the desired number of significant digits, it is also
191 written in the e format.
192 s:
194 Prints the argument with the string syntax. The argument is,
195 if no Unicode translation modifier is present, an iolist(),
196 a binary(), or an atom(). If the Unicode translation modi‐
197 fier (t) is in effect, the argument is unicode:chardata(),
198 meaning that binaries are in UTF-8. The characters are
199 printed without quotes. The string is first truncated by the
200 specified precision and then padded and justified to the
201 specified field width. The default precision is the field
202 width.
203 This format can be used for printing any object and truncat‐
205 ing the output so it fits a specified field:
206 1> io:fwrite("|~10w|~n", [{hey, hey, hey}]).
208 |**********|
209 ok
210 2> io:fwrite("|~10s|~n", [io_lib:write({hey, hey, hey})]).
211 |{hey,hey,h|
212 3> io:fwrite("|~-10.8s|~n", [io_lib:write({hey, hey, hey})]).
213 |{hey,hey |
214 ok
215 A list with integers > 255 is considered an error if the
217 Unicode translation modifier is not specified:
218 4> io:fwrite("~ts~n",[[1024]]).
220 \x{400}
221 ok
222 5> io:fwrite("~s~n",[[1024]]).
223 ** exception exit: {badarg,[{io,format,[<0.26.0>,"~s~n",[[1024]]]},
224 ...
225 w:
227 Writes data with the standard syntax. This is used to output
228 Erlang terms. Atoms are printed within quotes if they con‐
229 tain embedded non-printable characters. Atom characters >
230 255 are escaped unless the Unicode translation modifier (t)
231 is used. Floats are printed accurately as the shortest, cor‐
232 rectly rounded string.
233 p:
235 Writes the data with standard syntax in the same way as ~w,
236 but breaks terms whose printed representation is longer than
237 one line into many lines and indents each line sensibly.
238 Left-justification is not supported. It also tries to detect
239 lists of printable characters and to output these as
240 strings. The Unicode translation modifier is used for deter‐
241 mining what characters are printable, for example:
242 1> T = [{attributes,[[{id,age,1.50000},{mode,explicit},
244 {typename,"INTEGER"}], [{id,cho},{mode,explicit},{typename,'Cho'}]]},
245 {typename,'Person'},{tag,{'PRIVATE',3}},{mode,implicit}].
246 2> io:fwrite("~w~n", [T]).
247 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,
248 [73,78,84,69,71,69,82]}],[{id,cho},{mode,explicit},{typena
249 me,'Cho'}]]},{typename,'Person'},{tag,{'PRIVATE',3}},{mode
250 ,implicit}]
251 ok
252 3> io:fwrite("~62p~n", [T]).
253 [{attributes,[[{id,age,1.5},
254 {mode,explicit},
255 {typename,"INTEGER"}],
256 [{id,cho},{mode,explicit},{typename,'Cho'}]]},
257 {typename,'Person'},
258 {tag,{'PRIVATE',3}},
259 {mode,implicit}]
260 ok
261 The field width specifies the maximum line length. Defaults
263 to 80. The precision specifies the initial indentation of
264 the term. It defaults to the number of characters printed on
265 this line in the same call to write/1 or format/1,2,3. For
266 example, using T above:
267 4> io:fwrite("Here T = ~62p~n", [T]).
269 Here T = [{attributes,[[{id,age,1.5},
270 {mode,explicit},
271 {typename,"INTEGER"}],
272 [{id,cho},
273 {mode,explicit},
274 {typename,'Cho'}]]},
275 {typename,'Person'},
276 {tag,{'PRIVATE',3}},
277 {mode,implicit}]
278 ok
279 When the modifier l is specified, no detection of printable
281 character lists takes place, for example:
282 5> S = [{a,"a"}, {b, "b"}].
284 6> io:fwrite("~15p~n", [S]).
285 [{a,"a"},
286 {b,"b"}]
287 ok
288 7> io:fwrite("~15lp~n", [S]).
289 [{a,[97]},
290 {b,[98]}]
291 ok
292 Binaries that look like UTF-8 encoded strings are output
294 with the string syntax if the Unicode translation modifier
295 is specified:
296 9> io:fwrite("~p~n",[[1024]]).
298 [1024]
299 10> io:fwrite("~tp~n",[[1024]]).
300 "\x{400}"
301 11> io:fwrite("~tp~n", [<<128,128>>]).
302 <<128,128>>
303 12> io:fwrite("~tp~n", [<<208,128>>]).
304 <<"\x{400}"/utf8>>
305 ok
306 W:
308 Writes data in the same way as ~w, but takes an extra argu‐
309 ment that is the maximum depth to which terms are printed.
310 Anything below this depth is replaced with .... For example,
311 using T above:
312 8> io:fwrite("~W~n", [T,9]).
314 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
315 [{id,cho},{mode,...},{...}]]},{typename,'Person'},
316 {tag,{'PRIVATE',3}},{mode,implicit}]
317 ok
318 If the maximum depth is reached, it cannot be read in the
320 resultant output. Also, the ,... form in a tuple denotes
321 that there are more elements in the tuple but these are
322 below the print depth.
323 P:
325 Writes data in the same way as ~p, but takes an extra argu‐
326 ment that is the maximum depth to which terms are printed.
327 Anything below this depth is replaced with ..., for example:
328 9> io:fwrite("~62P~n", [T,9]).
330 [{attributes,[[{id,age,1.5},{mode,explicit},{typename,...}],
331 [{id,cho},{mode,...},{...}]]},
332 {typename,'Person'},
333 {tag,{'PRIVATE',3}},
334 {mode,implicit}]
335 ok
336 B:
338 Writes an integer in base 2-36, the default base is 10. A
339 leading dash is printed for negative integers.
340 The precision field selects base, for example:
342 1> io:fwrite("~.16B~n", [31]).
344 1F
345 ok
346 2> io:fwrite("~.2B~n", [-19]).
347 -10011
348 ok
349 3> io:fwrite("~.36B~n", [5*36+35]).
350 5Z
351 ok
352 X:
354 Like B, but takes an extra argument that is a prefix to
355 insert before the number, but after the leading dash, if
356 any.
357 The prefix can be a possibly deep list of characters or an
359 atom. Example:
360 1> io:fwrite("~X~n", [31,"10#"]).
362 10#31
363 ok
364 2> io:fwrite("~.16X~n", [-31,"0x"]).
365 -0x1F
366 ok
367 #:
369 Like B, but prints the number with an Erlang style #-sepa‐
370 rated base prefix. Example:
371 1> io:fwrite("~.10#~n", [31]).
373 10#31
374 ok
375 2> io:fwrite("~.16#~n", [-31]).
376 -16#1F
377 ok
378 b:
380 Like B, but prints lowercase letters.
381 x:
383 Like X, but prints lowercase letters.
384 +:
386 Like #, but prints lowercase letters.
387 n:
389 Writes a new line.
390 i:
392 Ignores the next term.
393 The function returns:
395 ok:
397 The formatting succeeded.
398 If an error occurs, there is no output. Example:
400 1> io:fwrite("~s ~w ~i ~w ~c ~n",['abc def', 'abc def', {foo, 1},{foo, 1}, 65]).
402 abc def 'abc def' {foo,1} A
403 ok
404 2> io:fwrite("~s", [65]).
405 ** exception exit: {badarg,[{io,format,[<0.22.0>,"~s","A"]},
406 {erl_eval,do_apply,5},
407 {shell,exprs,6},
408 {shell,eval_exprs,6},
409 {shell,eval_loop,3}]}
410 in function io:o_request/2
411 In this example, an attempt was made to output the single char‐
413 acter 65 with the aid of the string formatting directive "~s".
414 fread(Prompt, Format) -> Result
416 fread(IoDevice, Prompt, Format) -> Result
418 Types:
420 IoDevice = device()
422 Prompt = prompt()
423 Format = format()
424 Result =
425 {ok, Terms :: [term()]} |
426 {error, {fread, FreadError :: io_lib:fread_error()}} |
427 server_no_data()
428 server_no_data() = {error, ErrorDescription :: term()} | eof
429 Reads characters from the standard input (IoDevice), prompting
431 it with Prompt. Interprets the characters in accordance with
432 Format. Format contains control sequences that directs the
433 interpretation of the input.
434 Format can contain the following:
436 * Whitespace characters (Space, Tab, and Newline) that cause
438 input to be read to the next non-whitespace character.
439 * Ordinary characters that must match the next input charac‐
441 ter.
442 * Control sequences, which have the general format ~*FMC,
444 where:
445 * Character * is an optional return suppression character.
447 It provides a method to specify a field that is to be
448 omitted.
449 * F is the field width of the input field.
451 * M is an optional translation modifier (of which t is the
453 only supported, meaning Unicode translation).
454 * C determines the type of control sequence.
456 Unless otherwise specified, leading whitespace is ignored
458 for all control sequences. An input field cannot be more
459 than one line wide.
460 Available control sequences:
462 ~:
464 A single ~ is expected in the input.
465 d:
467 A decimal integer is expected.
468 u:
470 An unsigned integer in base 2-36 is expected. The field
471 width parameter is used to specify base. Leading white‐
472 space characters are not skipped.
473 -:
475 An optional sign character is expected. A sign character -
476 gives return value -1. Sign character + or none gives 1.
477 The field width parameter is ignored. Leading whitespace
478 characters are not skipped.
479 #:
481 An integer in base 2-36 with Erlang-style base prefix (for
482 example, "16#ffff") is expected.
483 f:
485 A floating point number is expected. It must follow the
486 Erlang floating point number syntax.
487 s:
489 A string of non-whitespace characters is read. If a field
490 width has been specified, this number of characters are
491 read and all trailing whitespace characters are stripped.
492 An Erlang string (list of characters) is returned.
493 If Unicode translation is in effect (~ts), characters >
495 255 are accepted, otherwise not. With the translation mod‐
496 ifier, the returned list can as a consequence also contain
497 integers > 255:
498 1> io:fread("Prompt> ","~s").
500 Prompt> <Characters beyond latin1 range not printable in this medium>
501 {error,{fread,string}}
502 2> io:fread("Prompt> ","~ts").
503 Prompt> <Characters beyond latin1 range not printable in this medium>
504 {ok,[[1091,1085,1080,1094,1086,1076,1077]]}
505 a:
507 Similar to s, but the resulting string is converted into
508 an atom.
509 c:
511 The number of characters equal to the field width are read
512 (default is 1) and returned as an Erlang string. However,
513 leading and trailing whitespace characters are not omitted
514 as they are with s. All characters are returned.
515 The Unicode translation modifier works as with s:
517 1> io:fread("Prompt> ","~c").
519 Prompt> <Character beyond latin1 range not printable in this medium>
520 {error,{fread,string}}
521 2> io:fread("Prompt> ","~tc").
522 Prompt> <Character beyond latin1 range not printable in this medium>
523 {ok,[[1091]]}
524 l:
526 Returns the number of characters that have been scanned up
527 to that point, including whitespace characters.
528 The function returns:
530 {ok, Terms}:
532 The read was successful and Terms is the list of success‐
533 fully matched and read items.
534 eof:
536 End of file was encountered.
537 {error, FreadError}:
539 The reading failed and FreadError gives a hint about the
540 error.
541 {error, ErrorDescription}:
543 The read operation failed and parameter ErrorDescription
544 gives a hint about the error.
545 Examples:
547 20> io:fread('enter>', "~f~f~f").
549 enter>1.9 35.5e3 15.0
550 {ok,[1.9,3.55e4,15.0]}
551 21> io:fread('enter>', "~10f~d").
552 enter> 5.67899
553 {ok,[5.678,99]}
554 22> io:fread('enter>', ":~10s:~10c:").
555 enter>: alan : joe :
556 {ok, ["alan", " joe "]}
557 get_chars(Prompt, Count) -> Data | server_no_data()
559 get_chars(IoDevice, Prompt, Count) -> Data | server_no_data()
561 Types:
563 IoDevice = device()
565 Prompt = prompt()
566 Count = integer() >= 0
567 Data = string() | unicode:unicode_binary()
568 server_no_data() = {error, ErrorDescription :: term()} | eof
569 Reads Count characters from standard input (IoDevice), prompting
571 it with Prompt.
572 The function returns:
574 Data:
576 The input characters. If the I/O device supports Unicode,
577 the data can represent codepoints > 255 (the latin1 range).
578 If the I/O server is set to deliver binaries, they are
579 encoded in UTF-8 (regardless of whether the I/O device sup‐
580 ports Unicode).
581 eof:
583 End of file was encountered.
584 {error, ErrorDescription}:
586 Other (rare) error condition, such as {error, estale} if
587 reading from an NFS file system.
588 get_line(Prompt) -> Data | server_no_data()
590 get_line(IoDevice, Prompt) -> Data | server_no_data()
592 Types:
594 IoDevice = device()
596 Prompt = prompt()
597 Data = string() | unicode:unicode_binary()
598 server_no_data() = {error, ErrorDescription :: term()} | eof
599 Reads a line from the standard input (IoDevice), prompting it
601 with Prompt.
602 The function returns:
604 Data:
606 The characters in the line terminated by a line feed (or end
607 of file). If the I/O device supports Unicode, the data can
608 represent codepoints > 255 (the latin1 range). If the I/O
609 server is set to deliver binaries, they are encoded in UTF-8
610 (regardless of if the I/O device supports Unicode).
611 eof:
613 End of file was encountered.
614 {error, ErrorDescription}:
616 Other (rare) error condition, such as {error, estale} if
617 reading from an NFS file system.
618 getopts() -> [opt_pair()] | {error, Reason}
620 getopts(IoDevice) -> [opt_pair()] | {error, Reason}
622 Types:
624 IoDevice = device()
626 Reason = term()
627 Requests all available options and their current values for a
629 specific I/O device, for example:
630 1> {ok,F} = file:open("/dev/null",[read]).
632 {ok,<0.42.0>}
633 2> io:getopts(F).
634 [{binary,false},{encoding,latin1}]
635 Here the file I/O server returns all available options for a
637 file, which are the expected ones, encoding and binary. However,
638 the standard shell has some more options:
639 3> io:getopts().
641 [{expand_fun,#Fun<group.0.120017273>},
642 {echo,true},
643 {binary,false},
644 {encoding,unicode}]
645 This example is, as can be seen, run in an environment where the
647 terminal supports Unicode input and output.
648 nl() -> ok
650 nl(IoDevice) -> ok
652 Types:
654 IoDevice = device()
656 Writes new line to the standard output (IoDevice).
658 parse_erl_exprs(Prompt) -> Result
660 parse_erl_exprs(IoDevice, Prompt) -> Result
662 parse_erl_exprs(IoDevice, Prompt, StartLocation) -> Result
664 parse_erl_exprs(IoDevice, Prompt, StartLocation, Options) ->
666 Result
667 Types:
669 IoDevice = device()
671 Prompt = prompt()
672 StartLocation = location()
673 Options = erl_scan:options()
674 Result = parse_ret()
675 parse_ret() =
676 {ok,
677 ExprList :: [erl_parse:abstract_expr()],
678 EndLocation :: location()} |
679 {eof, EndLocation :: location()} |
680 {error,
681 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
682 ErrorLocation :: location()} |
683 server_no_data()
684 server_no_data() = {error, ErrorDescription :: term()} | eof
685 Reads data from the standard input (IoDevice), prompting it with
687 Prompt. Starts reading at location StartLocation (1). Argument
688 Options is passed on as argument Options of function
689 erl_scan:tokens/4. The data is tokenized and parsed as if it was
690 a sequence of Erlang expressions until a final dot (.) is
691 reached.
692 The function returns:
694 {ok, ExprList, EndLocation}:
696 The parsing was successful.
697 {eof, EndLocation}:
699 End of file was encountered by the tokenizer.
700 eof:
702 End of file was encountered by the I/O server.
703 {error, ErrorInfo, ErrorLocation}:
705 An error occurred while tokenizing or parsing.
706 {error, ErrorDescription}:
708 Other (rare) error condition, such as {error, estale} if
709 reading from an NFS file system.
710 Example:
712 25> io:parse_erl_exprs('enter>').
714 enter>abc(), "hey".
715 {ok, [{call,1,{atom,1,abc},[]},{string,1,"hey"}],2}
716 26> io:parse_erl_exprs ('enter>').
717 enter>abc("hey".
718 {error,{1,erl_parse,["syntax error before: ",["'.'"]]},2}
719 parse_erl_form(Prompt) -> Result
721 parse_erl_form(IoDevice, Prompt) -> Result
723 parse_erl_form(IoDevice, Prompt, StartLocation) -> Result
725 parse_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
727 Types:
729 IoDevice = device()
731 Prompt = prompt()
732 StartLocation = location()
733 Options = erl_scan:options()
734 Result = parse_form_ret()
735 parse_form_ret() =
736 {ok,
737 AbsForm :: erl_parse:abstract_form(),
738 EndLocation :: location()} |
739 {eof, EndLocation :: location()} |
740 {error,
741 ErrorInfo :: erl_scan:error_info() | erl_parse:error_info(),
742 ErrorLocation :: location()} |
743 server_no_data()
744 server_no_data() = {error, ErrorDescription :: term()} | eof
745 Reads data from the standard input (IoDevice), prompting it with
747 Prompt. Starts reading at location StartLocation (1). Argument
748 Options is passed on as argument Options of function
749 erl_scan:tokens/4. The data is tokenized and parsed as if it was
750 an Erlang form (one of the valid Erlang expressions in an Erlang
751 source file) until a final dot (.) is reached.
752 The function returns:
754 {ok, AbsForm, EndLocation}:
756 The parsing was successful.
757 {eof, EndLocation}:
759 End of file was encountered by the tokenizer.
760 eof:
762 End of file was encountered by the I/O server.
763 {error, ErrorInfo, ErrorLocation}:
765 An error occurred while tokenizing or parsing.
766 {error, ErrorDescription}:
768 Other (rare) error condition, such as {error, estale} if
769 reading from an NFS file system.
770 printable_range() -> unicode | latin1
772 Returns the user-requested range of printable Unicode charac‐
774 ters.
775 The user can request a range of characters that are to be con‐
777 sidered printable in heuristic detection of strings by the shell
778 and by the formatting functions. This is done by supplying +pc
779 <range> when starting Erlang.
780 The only valid values for <range> are latin1 and unicode. latin1
782 means that only code points < 256 (except control characters,
783 and so on) are considered printable. unicode means that all
784 printable characters in all Unicode character ranges are consid‐
785 ered printable by the I/O functions.
786 By default, Erlang is started so that only the latin1 range of
788 characters indicate that a list of integers is a string.
789 The simplest way to use the setting is to call io_lib:print‐
791 able_list/1, which uses the return value of this function to
792 decide if a list is a string of printable characters.
793 Note:
795 In a future release, this function may return more values and
796 ranges. To avoid compatibility problems, it is recommended to
797 use function io_lib:printable_list/1.
798 put_chars(CharData) -> ok
801 put_chars(IoDevice, CharData) -> ok
803 Types:
805 IoDevice = device()
807 CharData = unicode:chardata()
808 Writes the characters of CharData to the I/O server (IoDevice).
810 read(Prompt) -> Result
812 read(IoDevice, Prompt) -> Result
814 Types:
816 IoDevice = device()
818 Prompt = prompt()
819 Result =
820 {ok, Term :: term()} | server_no_data() | {error, Error‐
821 Info}
822 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
823 server_no_data() = {error, ErrorDescription :: term()} | eof
824 Reads a term Term from the standard input (IoDevice), prompting
826 it with Prompt.
827 The function returns:
829 {ok, Term}:
831 The parsing was successful.
832 eof:
834 End of file was encountered.
835 {error, ErrorInfo}:
837 The parsing failed.
838 {error, ErrorDescription}:
840 Other (rare) error condition, such as {error, estale} if
841 reading from an NFS file system.
842 read(IoDevice, Prompt, StartLocation) -> Result
844 read(IoDevice, Prompt, StartLocation, Options) -> Result
846 Types:
848 IoDevice = device()
850 Prompt = prompt()
851 StartLocation = location()
852 Options = erl_scan:options()
853 Result =
854 {ok, Term :: term(), EndLocation :: location()} |
855 {eof, EndLocation :: location()} |
856 server_no_data() |
857 {error, ErrorInfo, ErrorLocation :: location()}
858 ErrorInfo = erl_scan:error_info() | erl_parse:error_info()
859 server_no_data() = {error, ErrorDescription :: term()} | eof
860 Reads a term Term from IoDevice, prompting it with Prompt. Read‐
862 ing starts at location StartLocation. Argument Options is passed
863 on as argument Options of function erl_scan:tokens/4.
864 The function returns:
866 {ok, Term, EndLocation}:
868 The parsing was successful.
869 {eof, EndLocation}:
871 End of file was encountered.
872 {error, ErrorInfo, ErrorLocation}:
874 The parsing failed.
875 {error, ErrorDescription}:
877 Other (rare) error condition, such as {error, estale} if
878 reading from an NFS file system.
879 rows() -> {ok, integer() >= 1} | {error, enotsup}
881 rows(IoDevice) -> {ok, integer() >= 1} | {error, enotsup}
883 Types:
885 IoDevice = device()
887 Retrieves the number of rows of IoDevice (that is, the height of
889 a terminal). The function only succeeds for terminal devices,
890 for all other I/O devices the function returns {error, enotsup}.
891 scan_erl_exprs(Prompt) -> Result
893 scan_erl_exprs(Device, Prompt) -> Result
895 scan_erl_exprs(Device, Prompt, StartLocation) -> Result
897 scan_erl_exprs(Device, Prompt, StartLocation, Options) -> Result
899 Types:
901 Device = device()
903 Prompt = prompt()
904 StartLocation = location()
905 Options = erl_scan:options()
906 Result = erl_scan:tokens_result() | server_no_data()
907 server_no_data() = {error, ErrorDescription :: term()} | eof
908 Reads data from the standard input (IoDevice), prompting it with
910 Prompt. Reading starts at location StartLocation (1). Argument
911 Options is passed on as argument Options of function
912 erl_scan:tokens/4. The data is tokenized as if it were a
913 sequence of Erlang expressions until a final dot (.) is reached.
914 This token is also returned.
915 The function returns:
917 {ok, Tokens, EndLocation}:
919 The tokenization succeeded.
920 {eof, EndLocation}:
922 End of file was encountered by the tokenizer.
923 eof:
925 End of file was encountered by the I/O server.
926 {error, ErrorInfo, ErrorLocation}:
928 An error occurred while tokenizing.
929 {error, ErrorDescription}:
931 Other (rare) error condition, such as {error, estale} if
932 reading from an NFS file system.
933 Example:
935 23> io:scan_erl_exprs('enter>').
937 enter>abc(), "hey".
938 {ok,[{atom,1,abc},{'(',1},{')',1},{',',1},{string,1,"hey"},{dot,1}],2}
939 24> io:scan_erl_exprs('enter>').
940 enter>1.0er.
941 {error,{1,erl_scan,{illegal,float}},2}
942 scan_erl_form(Prompt) -> Result
944 scan_erl_form(IoDevice, Prompt) -> Result
946 scan_erl_form(IoDevice, Prompt, StartLocation) -> Result
948 scan_erl_form(IoDevice, Prompt, StartLocation, Options) -> Result
950 Types:
952 IoDevice = device()
954 Prompt = prompt()
955 StartLocation = location()
956 Options = erl_scan:options()
957 Result = erl_scan:tokens_result() | server_no_data()
958 server_no_data() = {error, ErrorDescription :: term()} | eof
959 Reads data from the standard input (IoDevice), prompting it with
961 Prompt. Starts reading at location StartLocation (1). Argument
962 Options is passed on as argument Options of function
963 erl_scan:tokens/4. The data is tokenized as if it was an Erlang
964 form (one of the valid Erlang expressions in an Erlang source
965 file) until a final dot (.) is reached. This last token is also
966 returned.
967 The return values are the same as for scan_erl_exprs/1,2,3,4.
969 setopts(Opts) -> ok | {error, Reason}
971 setopts(IoDevice, Opts) -> ok | {error, Reason}
973 Types:
975 IoDevice = device()
977 Opts = [setopt()]
978 Reason = term()
979 Set options for the standard I/O device (IoDevice).
981 Possible options and values vary depending on the I/O device.
983 For a list of supported options and their current values on a
984 specific I/O device, use function getopts/1.
985 The options and values supported by the OTP I/O devices are as
987 follows:
988 binary, list, or {binary, boolean()}:
990 If set in binary mode (binary or {binary, true}), the I/O
991 server sends binary data (encoded in UTF-8) as answers to
992 the get_line, get_chars, and, if possible, get_until
993 requests (for details, see section The Erlang I/O Protocol)
994 in the User's Guide). The immediate effect is that
995 get_chars/2,3 and get_line/1,2 return UTF-8 binaries instead
996 of lists of characters for the affected I/O device.
997 By default, all I/O devices in OTP are set in list mode.
999 However, the I/O functions can handle any of these modes and
1000 so should other, user-written, modules behaving as clients
1001 to I/O servers.
1002 This option is supported by the standard shell (group.erl),
1004 the 'oldshell' (user.erl), and the file I/O servers.
1005 {echo, boolean()}:
1007 Denotes if the terminal is to echo input. Only supported for
1008 the standard shell I/O server (group.erl)
1009 {expand_fun, expand_fun()}:
1011 Provides a function for tab-completion (expansion) like the
1012 Erlang shell. This function is called when the user presses
1013 the Tab key. The expansion is active when calling line-read‐
1014 ing functions, such as get_line/1,2.
1015 The function is called with the current line, up to the cur‐
1017 sor, as a reversed string. It is to return a three-tuple:
1018 {yes|no, string(), [string(), ...]}. The first element gives
1019 a beep if no, otherwise the expansion is silent; the second
1020 is a string that will be entered at the cursor position; the
1021 third is a list of possible expansions. If this list is not
1022 empty, it is printed and the current input line is written
1023 once again.
1024 Trivial example (beep on anything except empty line, which
1026 is expanded to "quit"):
1027 fun("") -> {yes, "quit", []};
1029 (_) -> {no, "", ["quit"]} end
1030 This option is only supported by the standard shell
1032 (group.erl).
1033 {encoding, latin1 | unicode}:
1035 Specifies how characters are input or output from or to the
1036 I/O device, implying that, for example, a terminal is set to
1037 handle Unicode input and output or a file is set to handle
1038 UTF-8 data encoding.
1039 The option does not affect how data is returned from the I/O
1041 functions or how it is sent in the I/O protocol, it only
1042 affects how the I/O device is to handle Unicode characters
1043 to the "physical" device.
1044 The standard shell is set for unicode or latin1 encoding
1046 when the system is started. The encoding is set with the
1047 help of the LANG or LC_CTYPE environment variables on Unix-
1048 like system or by other means on other systems. So, the user
1049 can input Unicode characters and the I/O device is in
1050 {encoding, unicode} mode if the I/O device supports it. The
1051 mode can be changed, if the assumption of the runtime system
1052 is wrong, by setting this option.
1053 The I/O device used when Erlang is started with the "-old‐
1055 shell" or "-noshell" flags is by default set to latin1
1056 encoding, meaning that any characters > codepoint 255 are
1057 escaped and that input is expected to be plain 8-bit ISO
1058 Latin-1. If the encoding is changed to Unicode, input and
1059 output from the standard file descriptors are in UTF-8
1060 (regardless of operating system).
1061 Files can also be set in {encoding, unicode}, meaning that
1063 data is written and read as UTF-8. More encodings are possi‐
1064 ble for files, see below.
1065 {encoding, unicode | latin1} is supported by both the stan‐
1067 dard shell (group.erl including werl on Windows), the 'old‐
1068 shell' (user.erl), and the file I/O servers.
1069 {encoding, utf8 | utf16 | utf32 | {utf16,big} | {utf16,little}
1071 | {utf32,big} | {utf32,little}}:
1072 For disk files, the encoding can be set to various UTF vari‐
1073 ants. This has the effect that data is expected to be read
1074 as the specified encoding from the file, and the data is
1075 written in the specified encoding to the disk file.
1076 {encoding, utf8} has the same effect as {encoding, unicode}
1078 on files.
1079 The extended encodings are only supported on disk files
1081 (opened by function file:open/2).
1082 write(Term) -> ok
1084 write(IoDevice, Term) -> ok
1086 Types:
1088 IoDevice = device()
1090 Term = term()
1091 Writes term Term to the standard output (IoDevice).
1093
1095 All Erlang processes have a default standard I/O device. This device is
1096 used when no IoDevice argument is specified in the function calls in
1097 this module. However, it is sometimes desirable to use an explicit
1098 IoDevice argument that refers to the default I/O device. This is the
1099 case with functions that can access either a file or the default I/O
1100 device. The atom standard_io has this special meaning. The following
1101 example illustrates this:
1102 27> io:read('enter>').
1104 enter>foo.
1105 {ok,foo}
1106 28> io:read(standard_io, 'enter>').
1107 enter>bar.
1108 {ok,bar}
1109 There is always a process registered under the name of user. This can
1111 be used for sending output to the user.
1112
1114 In certain situations, especially when the standard output is redi‐
1115 rected, access to an I/O server specific for error messages can be con‐
1116 venient. The I/O device standard_error can be used to direct output to
1117 whatever the current operating system considers a suitable I/O device
1118 for error output. Example on a Unix-like operating system:
1119 $ erl -noshell -noinput -eval 'io:format(standard_error,"Error: ~s~n",["error 11"]),'\
1121 'init:stop().' > /dev/null
1122 Error: error 11
1123
1125 The ErrorInfo mentioned in this module is the standard ErrorInfo struc‐
1126 ture that is returned from all I/O modules. It has the following for‐
1127 mat:
1128 {ErrorLocation, Module, ErrorDescriptor}
1130 A string that describes the error is obtained with the following call:
1132 Module:format_error(ErrorDescriptor)
1134Ericsson AB stdlib 3.4.5.1 io(3)