| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html> |
| <head> |
| <link rel="stylesheet" href="stylesheet.css" type="text/css"/> |
| </head> |
| <body> |
| <div id="container"> |
| <div id="product"> |
| <div id="product_logo"></div> |
| <div id="product_name"><big><b></b></big></div> |
| <div id="product_description"></div> |
| </div> |
| <div id="main"> |
| <div id="navigation"> |
| <h2>Modules</h2> |
| <ul><li> |
| <a href="index.html">index</a> |
| </li></ul> |
| <ul> |
| <li><a href="coroutine.html">coroutine</a></li> |
| <li><a href="debug.html">debug</a></li> |
| <li><a href="global.html">global</a></li> |
| <li>io</li> |
| <li><a href="math.html">math</a></li> |
| <li><a href="os.html">os</a></li> |
| <li><a href="package.html">package</a></li> |
| <li><a href="string.html">string</a></li> |
| <li><a href="table.html">table</a></li> |
| </ul> |
| </div> |
| <div id="content"> |
| <h1>Module <code>io</code></h1> |
| |
| <p>Input and Output Facilities.</p> |
| |
| |
| <p>The I/O library provides function for file manipulation. |
| There are two different styles for file manipulation. |
| The first one uses implicit file descriptors; |
| that is, there are operations to set a default input file and a default output file, |
| and all input/output operations are over these default files. |
| The second style uses explicit file descriptors.</p> |
| |
| <p>When using implicit file descriptors, all operations are supplied by table io.</p> |
| |
| <p>When using explicit file descriptors, the operation io.open returns a file descriptor |
| and then all operations are supplied as methods of the file descriptor.</p> |
| |
| <p>The table io also provides three predefined file descriptors with their usual meanings from C: io.stdin, io.stdout, and io.stderr. |
| The I/O library never closes these files.</p> |
| |
| <p>Unless otherwise stated, all I/O functions return nil on failure (plus an error message as a second result and a system-dependent error code as a third result) |
| and some value different from nil on success.</p> |
| |
| <h2><a id="#(io)" >Type <code>io</code></a></h2> |
| <table class="function_list"> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).close">io.close(file)</a></td> |
| <td class="summary"> |
| <p>Equivalent to <code>file:close</code>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).flush">io.flush()</a></td> |
| <td class="summary"> |
| <p>Equivalent to <code>file:flush</code> over the default output file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).input">io.input(file)</a></td> |
| <td class="summary"> |
| <p>When called with a file name, it opens the named file (in text mode), |
| and sets its handle as the default input file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).lines">io.lines(a)</a></td> |
| <td class="summary"> |
| <p>Opens the given file name in read mode and returns an iterator function |
| that, each time it is called, returns a new line from the file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).open">io.open(filename, mode)</a></td> |
| <td class="summary"> |
| <p>This function opens a file, in the mode specified in the string <code>mode</code>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).output">io.output(file)</a></td> |
| <td class="summary"> |
| <p>Similar to <code>io.input</code>, but operates over the default output file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).popen">io.popen(prog, mode)</a></td> |
| <td class="summary"> |
| <p>Starts program <code>prog</code> in a separated process and returns a file handle |
| that you can use to read data from this program (if <code>mode</code> is <code>"r"</code>, |
| the default) or to write data to this program (if <code>mode</code> is <code>"w"</code>).</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).read">io.read(format)</a></td> |
| <td class="summary"> |
| <p>Equivalent to <code>io.input():read</code>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).stderr">io.stderr</a></td> |
| <td class="summary"> |
| <p>io.stderr: Standard error.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).stdin">io.stdin</a></td> |
| <td class="summary"> |
| <p>io.stdin: Standard in.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).stdout">io.stdout</a></td> |
| <td class="summary"> |
| <p>io.stdout: Standard out.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).tmpfile">io.tmpfile()</a></td> |
| <td class="summary"> |
| <p>Returns a handle for a temporary file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(io).write">io.write(...)</a></td> |
| <td class="summary"> |
| <p>Equivalent to <code>io.output():write</code>.</p> |
| </td> |
| </tr> |
| </table> |
| |
| <h2><a id="#(file)">Type <code>file</code></a></h2> |
| <table class="function_list"> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).close">file:close()</a></td> |
| <td class="summary"> |
| <p>Closes <code>file</code>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).flush">file:flush()</a></td> |
| <td class="summary"> |
| <p>Saves any written data to <code>file</code>.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).lines">file:lines()</a></td> |
| <td class="summary"> |
| <p>Returns an iterator function that, each time it is called, returns a |
| new line from the file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).read">file:read(format)</a></td> |
| <td class="summary"> |
| <p>Reads the file <code>file</code>, according to the given formats, which specify |
| what to read.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).seek">file:seek(whence, offset)</a></td> |
| <td class="summary"> |
| <p>Sets and gets the file position.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).setvbuf">file:setvbuf(mode, size)</a></td> |
| <td class="summary"> |
| <p>Sets the buffering mode for an output file.</p> |
| </td> |
| </tr> |
| <tr> |
| <td class="name" nowrap="nowrap"><a href="##(file).write">file:write(...)</a></td> |
| <td class="summary"> |
| <p>Writes the value of each of its arguments to the <code>file</code>.</p> |
| </td> |
| </tr> |
| </table> |
| |
| <h2><a id="#(io)" >Type <code>io</code></a></h2> |
| <h3>Field(s)</h3> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).close" > |
| <strong>io.close(file)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Equivalent to <code>file:close</code>.</p> |
| |
| |
| <p>Without a <code>file</code>, closes the default |
| output file.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em><a href="##(file)">#file</a> file </em></code>: |
| file to close.</p> |
| |
| |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).flush" > |
| <strong>io.flush()</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Equivalent to <code>file:flush</code> over the default output file.</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).input" > |
| <strong>io.input(file)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>When called with a file name, it opens the named file (in text mode), |
| and sets its handle as the default input file.</p> |
| |
| |
| <p>When called with a file |
| handle, it simply sets this file handle as the default input file. When |
| called without parameters, it returns the current default input file.</p> |
| |
| <p>In case of errors this function raises the error, instead of returning an |
| error code.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> file </em></code>: |
| a filename or a file handle which will used as default input. (optional)</p> |
| |
| </li> |
| </ul> |
| <h3>Return value</h3> |
| |
| <p><em><a href="##(file)">#file</a>:</em> |
| the default input file handle.</p> |
| |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).lines" > |
| <strong>io.lines(a)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Opens the given file name in read mode and returns an iterator function |
| that, each time it is called, returns a new line from the file.</p> |
| |
| |
| <p>Therefore, |
| the construction </p> |
| |
| <pre><code>for line in io.lines(filename) do *body* end |
| </code></pre> |
| <p>will iterate over all lines of the file. When the iterator function detects |
| the end of file, it returns nil (to finish the loop) and automatically |
| closes the file.</p> |
| |
| <p>The call <code>io.lines()</code> (with no file name) is equivalent to |
| <code>io.input():lines()</code>; that is, it iterates over the lines of the default |
| input file. In this case it does not close the file when the loop ends.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> a </em></code>: |
| filename or a file handle. (default value is <code>io.input()</code>)</p> |
| |
| |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).open" > |
| <strong>io.open(filename, mode)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>This function opens a file, in the mode specified in the string <code>mode</code>.</p> |
| |
| |
| <p>It |
| returns a new file handle, or, in case of errors, nil plus an error message. |
| The <code>mode</code> string can be any of the following:</p> |
| |
| <ul> |
| <li><em>"r"</em>: read mode (the default);</li> |
| <li><em>"w"</em>: write mode;</li> |
| <li><em>"a"</em>: append mode;</li> |
| <li><em>"r+"</em>: update mode, all previous data is preserved;</li> |
| <li><em>"w+"</em>: update mode, all previous data is erased;</li> |
| <li><em>"a+"</em>: append update mode, previous data is preserved, writing is only |
| allowed at the end of file.</li> |
| </ul> |
| |
| <p>The <code>mode</code> string can also have a '<code>b</code>' at the end, which is needed in |
| some systems to open the file in binary mode. This string is exactly what |
| is used in the standard C function <code>fopen</code>.</p> |
| |
| <h3>Parameters</h3> |
| <ul> |
| <li> |
| |
| <p><code><em>#string filename </em></code>: |
| path to the file. </p> |
| |
| </li> |
| <li> |
| |
| <p><code><em>#string mode </em></code>: |
| used to specify the open mode.</p> |
| |
| </li> |
| </ul> |
| <h3>Return value</h3> |
| |
| <p><em><a href="##(file)">#file</a>:</em> |
| a file handle.</p> |
| |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).output" > |
| <strong>io.output(file)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Similar to <code>io.input</code>, but operates over the default output file.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> file </em></code>: |
| a filename or a file handle which will used as default output. (optional)</p> |
| |
| </li> |
| </ul> |
| <h3>Return value</h3> |
| |
| <p><em><a href="##(file)">#file</a>:</em> |
| the default ouput file handle.</p> |
| |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).popen" > |
| <strong>io.popen(prog, mode)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Starts program <code>prog</code> in a separated process and returns a file handle |
| that you can use to read data from this program (if <code>mode</code> is <code>"r"</code>, |
| the default) or to write data to this program (if <code>mode</code> is <code>"w"</code>).</p> |
| |
| |
| |
| <p>This function is system dependent and is not available on all platforms.</p> |
| |
| <h3>Parameters</h3> |
| <ul> |
| <li> |
| |
| <p><code><em>#string prog </em></code>: |
| the program to start.</p> |
| |
| </li> |
| <li> |
| |
| <p><code><em>#string mode </em></code>: |
| used to specify the open mode.</p> |
| |
| </li> |
| </ul> |
| <h3>Return value</h3> |
| |
| <p><em><a href="##(file)">#file</a>:</em> |
| a file handle used to read from or write to the program <code>prog</code>.</p> |
| |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).read" > |
| <strong>io.read(format)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Equivalent to <code>io.input():read</code>.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> format </em></code>: </p> |
| |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <em><a href="##(file)">#file</a></em> |
| <a id="#(io).stderr" > |
| <strong>io.stderr</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>io.stderr: Standard error.</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <em><a href="##(file)">#file</a></em> |
| <a id="#(io).stdin" > |
| <strong>io.stdin</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>io.stdin: Standard in.</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <em><a href="##(file)">#file</a></em> |
| <a id="#(io).stdout" > |
| <strong>io.stdout</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>io.stdout: Standard out.</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).tmpfile" > |
| <strong>io.tmpfile()</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Returns a handle for a temporary file.</p> |
| |
| |
| <p>This file is opened in update |
| mode and it is automatically removed when the program ends.</p> |
| |
| <h3>Return value</h3> |
| |
| <p><em><a href="##(file)">#file</a>:</em> |
| a file handle for a temporary file.</p> |
| |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(io).write" > |
| <strong>io.write(...)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Equivalent to <code>io.output():write</code>.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> ... </em></code>: </p> |
| |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| |
| <h2><a id="#(file)" >Type <code>file</code></a></h2> |
| <h3>Field(s)</h3> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).close" > |
| <strong>file:close()</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Closes <code>file</code>.</p> |
| |
| |
| <p>Note that files are automatically closed when their |
| handles are garbage collected, but that takes an unpredictable amount of |
| time to happen.</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).flush" > |
| <strong>file:flush()</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Saves any written data to <code>file</code>.</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).lines" > |
| <strong>file:lines()</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Returns an iterator function that, each time it is called, returns a |
| new line from the file.</p> |
| |
| |
| <p>Therefore, the construction</p> |
| |
| <pre><code>for line in file:lines() do *body* end |
| </code></pre> |
| <p>will iterate over all lines of the file. (Unlike <code>io.lines</code>, this function |
| does not close the file when the loop ends.)</p> |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).read" > |
| <strong>file:read(format)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Reads the file <code>file</code>, according to the given formats, which specify |
| what to read.</p> |
| |
| |
| <p>For each format, the function returns a string (or a number) |
| with the characters read, or nil if it cannot read data with the specified |
| format. When called without formats, it uses a default format that reads |
| the entire next line (see below). |
| The available formats are</p> |
| |
| <ul> |
| <li><em>"*n"</em>: reads a number; this is the only format that returns a number |
| instead of a string.</li> |
| <li><em>"*a"</em>: reads the whole file, starting at the current position. On end of |
| file, it returns the empty string.</li> |
| <li><em>"*l"</em>: reads the next line (skipping the end of line), returning nil on |
| end of file. This is the default format.</li> |
| <li><em>number</em>: reads a string with up to this number of characters, returning |
| nil on end of file. If number is zero, it reads nothing and returns an |
| empty string, or nil on end of file.</li> |
| </ul> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> format </em></code>: |
| <em>"*n"</em>, <em>"*a"</em>, <em>"*l"</em> or a number.</p> |
| |
| </li> |
| </ul> |
| <h3>Return value</h3> |
| |
| |
| <p>A string (or a number) with the characters read, or nil if it cannot read data with the specified format.</p> |
| |
| |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).seek" > |
| <strong>file:seek(whence, offset)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Sets and gets the file position.</p> |
| |
| |
| <p>It is measured from the beginning of the |
| file, to the position given by <code>offset</code> plus a base specified by the string |
| <code>whence</code>, as follows:</p> |
| |
| <ul> |
| <li><code>"set"</code>: base is position 0 (beginning of the file);</li> |
| <li><code>"cur"</code>: base is current position;</li> |
| <li><code>"end"</code>: base is end of file;</li> |
| </ul> |
| |
| <p>In case of success, function <code>seek</code> returns the final file position, |
| measured in bytes from the beginning of the file. If this function fails, |
| it returns nil, plus a string describing the error. |
| The default value for <code>whence</code> is <code>"cur"</code>, and for <code>offset</code> is 0. Therefore, |
| the call <code>file:seek()</code> returns the current file position, without changing |
| it; the call <code>file:seek("set")</code> sets the position to the beginning of the |
| file (and returns 0); and the call <code>file:seek("end")</code> sets the position |
| to the end of the file, and returns its size.</p> |
| |
| <h3>Parameters</h3> |
| <ul> |
| <li> |
| |
| <p><code><em>#string whence </em></code>: |
| <code>"set"</code>, <code>"cur"</code> or <code>"end"</code> (default value is <code>"cur"</code>)</p> |
| |
| </li> |
| <li> |
| |
| <p><code><em>#number offset </em></code>: |
| offset of end position. (default value is 0)</p> |
| |
| </li> |
| </ul> |
| <h3>Return values</h3> |
| <ol> |
| <li> |
| |
| <p><em>#number:</em> |
| the final file position in bytes, if it succeed.</p> |
| |
| </li> |
| <li> |
| |
| <p><em>#nil, #string:</em> |
| an error message, if it failed.</p> |
| |
| |
| </li> |
| </ol> |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).setvbuf" > |
| <strong>file:setvbuf(mode, size)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Sets the buffering mode for an output file.</p> |
| |
| |
| <p>There are three available |
| modes:</p> |
| |
| <ul> |
| <li><code>"no"</code> : no buffering; the result of any output operation appears immediately.</li> |
| <li><code>"full"</code> : full buffering; output operation is performed only when the |
| buffer is full (or when you explicitly <code>flush</code> the file (see <code>io.flush</code>)).</li> |
| <li><code>"line"</code> : line buffering; output is buffered until a newline is output or |
| there is any input from some special files (such as a terminal device).</li> |
| </ul> |
| |
| <p>For the last two cases, <code>size</code> specifies the size of the buffer, in |
| bytes. The default is an appropriate size.</p> |
| |
| <h3>Parameters</h3> |
| <ul> |
| <li> |
| |
| <p><code><em>#string mode </em></code>: |
| the buffering mode : <code>"no"</code>, <code>"full"</code> or <code>"line"</code>.</p> |
| |
| </li> |
| <li> |
| |
| <p><code><em>#number size </em></code>: |
| the size of the buffer.(default value is an appropriate size)</p> |
| |
| |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| <dl class="function"> |
| <dt> |
| <a id="#(file).write" > |
| <strong>file:write(...)</strong> |
| </a> |
| </dt> |
| <dd> |
| |
| <p>Writes the value of each of its arguments to the <code>file</code>.</p> |
| |
| |
| <p>The arguments |
| must be strings or numbers. To write other values, use <code>tostring</code> or |
| <code>string.format</code> before <code>write</code>.</p> |
| |
| <h3>Parameter</h3> |
| <ul> |
| <li> |
| |
| <p><code><em> ... </em></code>: |
| must be strings or a numbers.</p> |
| |
| |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| |
| </div> |
| |
| </div> |
| </body> |
| </html> |
