6.4 I/O Facilities

All I/O operations in Lua are done over two current files, one for reading and one for writing. Initially, the current input file is stdin , and the current output file is stdout .

Unless otherwise stated, all I/O functions return 1 on success and nil on failure.

readfrom (filename)

This function opens a file named filename and sets it as the current input file. When called without parameters, this function closes the current input file, and restores stdin as the current input file.

System dependent: if filename starts with a | , then a piped input is open, via function popen.

writeto (filename)

This function opens a file named filename and sets it as the current output file. Notice that, if the file already exists, it will be completely erased with this operation. When called without parameters, this function closes the current output file, and restores stdout as the current output file.

System dependent: if filename starts with a | , then a piped output is open, via function popen.

appendto (filename)

This function opens a file named filename and sets it as the current output file. Unlike the writeto operation, this function does not erase any previous content of the file.

remove (filename)

This function deletes the file with the given name.

rename (name1, name2)

This function renames file name1 to name2 .

tmpname ()

This function returns a string with a file name that can safely be used for a temporary file.

read ([format])

This function returns a value read from the current input. An optional string argument specifies the way the input is interpreted.

Without a format argument, read first skips blanks, tabs and newlines. Then it checks whether the current character is " or ' . If so, it reads a string up to the ending quotation mark, and returns this string, without the quotation marks. Otherwise it reads up to a blank, tab or newline.

The format string can have the following format:

   ?[n]

's' or 'S'

to read a string;

'f' or 'F'

to read a real number;

'i' or 'I'

to read an integer.

readuntil (char)

Reads the current input until the first ocurrence of the given character. When called with no parameters, reads until the end of the current input file. Returns the string read. The character itself is not read.

write (value, [format])

This function writes the value of its first argument to the current output. An optional second argument specifies the format to be used. This format is given as a string, composed of four parts. The first part is the only one not optional, and must be one of the following characters:

's' or 'S'

to write strings;

'f' or 'F'

to write floats;

'i' or 'I'

to write integers;

'q' or 'Q'

to write quoted strings. This format writes the string in a form suitable to be safely read back by the Lua interpreter. The string is written between double quotes, and all double quotes, returns and backslashes in the string are correctly escaped when written.

   [?][m][.n]

?

indicates justification inside the field.

'< '

right justification (default);

'> '

left justification;

'| '

center justification.

m

Indicates the field size in characters.

.n

For reals, indicates the number of digital places. For integers, it is the minimum number of digits. This option has no meaning for strings.

When called without a format string, this function writes numbers using the %g format and strings with %s . For better format facilities, the function format should be used (see Section 6.2).

date ([format])

This function returns a string containing date and time formatted according to the given string format , following the same rules of the ANSI C function strftime . When called without arguments, it returns a reasonable date and time representation.

This function replaces functions date and time from previous Lua versions.

exit ([code])

This function calls the C function exit , with an optional code , to terminate the program.