6.8 – 输入输出库

I/O 库提供了两套不同风格的文件处理接口。第一种风格使用隐式的文件句柄；它提供设置默认输入文件及默认输出文件的操作，所有的输入输出操作都针对这些默认文件。第二种风格使用显式的文件句柄。

当使用隐式文件句柄时，所有的操作都由表 io 提供。若使用显式文件句柄，io.open 会返回一个文件句柄，且所有的操作都由该文件句柄的方法来提供。

表 io 中也提供了三个和 C 中含义相同的预定义文件句柄：io.stdin， io.stdout， 以及 io.stderr。I/O 库永远不会关闭这些文件。

除非另有说明，I/O 函数在出错时都返回 nil（第二个返回值为错误消息，第三个返回值为系统相关的错误码）。成功时返回与 nil 不同的值。在非 POSIX 系统上，根据错误码取出错误消息的过程可能并非线程安全的，因为这使用了 C 的全局变量 errno 。

io.close ([file])

等价于 file:close()。不给出 file 时将关闭默认输出文件。

io.flush ()

等价于 io.output():flush()。

io.input ([file])

用文件名调用它时，（以文本模式）来打开该名字的文件，并将文件句柄设为默认输入文件。如果用文件句柄去调用它，就简单的将该句柄设为默认输入文件。如果调用时不传参数，它返回当前的默认输入文件。

在出错的情况下，函数抛出错误而不是返回错误码。

io.lines ([filename ···])

以读模式打开指定的文件名并返回一个迭代函数。此迭代函数的工作方式和用一个已打开的文件去调用file:lines(···) 得到的迭代器相同。当迭代函数检测到文件结束，它不返回值（让循环结束）并自动关闭文件。

调用 io.lines() （不传文件名）等价于 io.input():lines("*l")；即，它将按行迭代标准输入文件。在此情况下，循环结束后它不会关闭文件。

在出错的情况下，函数抛出错误而不是返回错误码。

io.open (filename [, mode])

这个函数用字符串 mode 指定的模式打开一个文件。返回新的文件句柄。当出错时，返回 nil 加错误消息。

mode 字符串可以是下列任意值：

• "r": 读模式（默认）；
• "w": 写模式；
• "a": 追加模式；
• "r+": 更新模式，所有之前的数据都保留；
• "w+": 更新模式，所有之前的数据都删除；
• "a+": 追加更新模式，所有之前的数据都保留，只允许在文件尾部做写入。 mode 字符串可以在最后加一个 'b' ，这会在某些系统上以二进制方式打开文件。

io.output ([file])

类似于 io.input。不过都针对默认输出文件操作。

io.popen (prog [, mode])

这个函数和系统有关，不是所有的平台都提供。

用一个分离进程开启程序 prog，返回的文件句柄可用于从这个程序中读取数据（如果 mode 为 "r"，这是默认值）或是向这个程序写入输入（当mode 为 "w" 时）。

io.read (···)

等价于 io.input():read(···)。

io.tmpfile ()

如果成功，返回一个临时文件的句柄。这个文件以更新模式打开，在程序结束时会自动删除。

io.type (obj)

检查 obj 是否是合法的文件句柄。如果 obj 它是一个打开的文件句柄，返回字符串 "file"。如果 obj 是一个关闭的文件句柄，返回字符串 "closed file"。如果 obj 不是文件句柄，返回 nil 。

io.write (···)

等价于 io.output():write(···)。

file:close ()

关闭 file。注意，文件在句柄被垃圾回收时会自动关闭，但是多久以后发生，时间不可预期的。

当关闭用 io.popen 创建出来的文件句柄时，file:close返回 os.execute会返回的一样的值。

file:flush ()

将写入的数据保存到 file 中。

file:lines (···)

返回一个迭代器函数，每次调用迭代器时，都从文件中按指定格式读数据。如果没有指定格式，使用默认值 "l" 。看一个例子

     for c in file:lines(1) do body end

会从文件当前位置开始，中不断读出字符。和 io.lines 不同，这个函数在循环结束后不会关闭文件。

在出错的情况下，函数抛出错误而不是返回错误码。

file:read (···)

读文件 file，指定的格式决定了要读什么。对于每种格式，函数返回读出的字符对应的字符串或数字。若不能以该格式对应读出数据则返回 nil。（对于最后这种情况，函数不会读出后续的格式。）当调用时不传格式，它会使用默认格式读下一行（见下面描述）。

提供的格式有

• "n": 读取一个数字，根据 Lua 的转换文法，可能返回浮点数或整数。（数字可以有前置或后置的空格，以及符号。）只要能构成合法的数字，这个格式总是去读尽量长的串；如果读出来的前缀无法构成合法的数字（比如空串，"0x" 或 "3.4e-"），就中止函数运行，返回 nil。
• "a": 从当前位置开始读取整个文件。如果已在文件末尾，返回空串。
• "l": 读取一行并忽略行结束标记。当在文件末尾时，返回 nil这是默认格式。
• "L": 读取一行并保留行结束标记（如果有的话），当在文件末尾时，返回 nil。
• number: 读取一个不超过这个数量字节数的字符串。当在文件末尾时，返回 nil。如果 number 为零，它什么也不读，返回一个空串。当在文件末尾时，返回 nil。 格式 "l" 和 "L" 只能用于文本文件。

file:seek ([whence [, offset]])

设置及获取基于文件开头处计算出的位置。设置的位置由 offset 和whence 字符串 whence指定的基点决定。基点可以是：

• "set": 基点为 0 （文件开头）；
• "cur": 基点为当前位置；
• "end": 基点为文件尾； 当 seek 成功时，返回最终从文件开头计算起的文件的位置。当 seek 失败时，返回 nil 加上一个错误描述字符串。

whence 的默认值是 "cur"，offset 默认为 0 。因此，调用 file:seek() 可以返回文件当前位置，并不改变它；调用 file:seek("set") 将位置设为文件开头（并返回 0）；调用 file:seek("end") 将位置设到文件末尾，并返回文件大小。

file:setvbuf (mode [, size])

设置输出文件的缓冲模式。有三种模式：

• "no": 不缓冲；输出操作立刻生效。
• "full": 完全缓冲；只有在缓存满或当你显式的对文件调用flush（参见 io.flush）时才真正做输出操作。
• "line": 行缓冲；输出将缓冲到每次换行前，对于某些特殊文件（例如终端设备）缓冲到任何输入前。 对于后两种情况，size 以字节数为单位指定缓冲区大小。默认会有一个恰当的大小。

file:write (···)

将参数的值逐个写入 file。参数必须是字符串或数字。

成功时，函数返回 file。否则返回 nil 加错误描述字符串。