autodoc.git/
traditional_manual/
chapter_9.html
Branch:
Tag:
Non-build tags
All tags
No tags
2019-07-04
2019-07-04 12:45:39 by Henrik Grubbström (Grubba) <grubba@grubba.org>
9add8172aef1ccab977fe06f690edc0e53343ca0 (
775
lines) (+
608
/-
167
)
[
Show
|
Annotate
]
Branch:
master
Documentation
[Traditional]
: Added some structure to the I/O chapter.
1:
<!doctype html><html><head><title>Pike Reference Manual</title> <meta charset='utf-8'></head>
-
<body><dl><dt><h1 class='header'>9. I/O</h1></dt><dd><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.
File
</b></h2>
+
<body><dl><dt><h1 class='header'>9. I/O</h1></dt><dd><
/dd>
+
<dt><a name='9.1'></a>
+
<h2 class='header'>9.1. File system manipulation</h2></dt>
+
<dd>
+
+
<hr />
+
<
dl
class='group--doc'
>
+
<dt
class='head--type'
><
span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>access</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>access</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>mode</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>access() checks if the calling process can access the file
+
<code>path</code>. Symbolic links are dereferenced.</p>
+
</dd>
+
<dt class='head--doc'><span id='p-mode'></span>Parameter <code class='parameter'>mode</code></dt>
+
<dd></dd><dd class='body--doc'><p>The <code>mode</code> specifies the accessibility checks to be performed, and
+
is either not specified or empty, in which case access() just tests
+
if the file exists, or one or more of the characters <code class='expr'>"rwx"</code>.</p>
+
<p> r, w, and x test whether the file exists and grants read, write,
+
and execute permissions, respectively.</p>
+
<p> The check is done using the calling process's real UID and GID,
+
rather than the effective IDs as is done when actually attempting
+
an operation (e.g., open(2)) on the file. This allows set-user-ID
+
programs to easily determine the invoking user's authority.</p>
+
<p> If the calling process is privileged (i.e., its real UID is zero),
+
then an X_OK check is successful for a regular file if execute
+
permission is enabled for any of the file owner, group, or other.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>When the file is accessible using the given permissions.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>0</code></code></td><td><p>When the file is not accessible, in which case <code>errno</code> is set
+
to one of the following values:</p>
+
<table class='box'><tr><td><code><code class='key'>EACCESS</code></code></td><td><p>Access denied.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>ELOOP</code></code></td><td><p>Too many symbolic links.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>ENAMETOOLONG</code></code></td><td><p>The path is too long.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>ENOENT</code></code></td><td><p>The file does not exist.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>ENOTDIR</code></code></td><td><p>One of the directories used in <code>path</code> is not, in fact, a directory.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>EROFS</code></code></td><td><p>The filesystem is read only and write access was requested.</p>
+
</td></tr>
+
</table><p>Other errors can occur, but are not directly related to the
+
requested path, such as <code class='expr'>ENOMEM</code>, etc.</p>
+
</td></tr>
+
</table>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>errno()</code>, <code>Stdio.File</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>cd</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>cd</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Change the current directory for the whole Pike process.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns <code class='expr'>1</code> for success, <code class='expr'>0</code> (zero) otherwise.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>getcwd()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>getcwd</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string</code> <b><span class='method'>getcwd</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns the current working directory.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>cd()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>get_dir</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>get_dir</span>(</b><code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>dirname</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns an array of all filenames in the directory <code>dirname</code>, or
+
<code class='expr'>0</code> (zero) if the directory does not exist. When no
+
<code>dirname</code> is given, current work directory is used.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>mkdir()</code>, <code>cd()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>mkdir</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>mkdir</span>(</b><code class='datatype'>string</code> <code class='argument'>dirname</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>mode</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Create a directory.</p>
+
<p> If <code>mode</code> is specified, it's will be used for the new directory after
+
being <code class='expr'>&</code>'ed with the current umask (on OS'es that support this).</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns <code class='expr'>0</code> (zero) on failure, <code class='expr'>1</code> otherwise.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>rm()</code>, <code>cd()</code>, <code>Stdio.mkdirhier()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>cp</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>cp</span>(</b><code class='datatype'>string</code> <code class='argument'>from</code>, <code class='datatype'>string</code> <code class='argument'>to</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Copies the file <code>from</code> to the new position <code>to</code>. This is an
+
alias for <code>Stdio.cp</code>.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>mv</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>mv</span>(</b><code class='datatype'>string</code> <code class='argument'>from</code>, <code class='datatype'>string</code> <code class='argument'>to</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Rename or move a file or directory.</p>
+
<p> If the destination already exists, it will be replaced.
+
Replacement often only works if <code>to</code> is of the same type as
+
<code>from</code>, i.e. a file can only be replaced by another file and so
+
on. Also, a directory will commonly be replaced only if it's
+
empty.</p>
+
<p> On some OSs this function can't move directories, only rename
+
them.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns <code class='expr'>0</code> (zero) on failure, <code class='expr'>1</code> otherwise. Call
+
<code>errno()</code> to get more error info on failure.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>rm()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>rm</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>rm</span>(</b><code class='datatype'>string</code> <code class='argument'>f</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Remove a file or directory.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns <code class='expr'>0</code> (zero) on failure, <code class='expr'>1</code> otherwise.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>May fail with <code>errno()</code> set to <code>EISDIR</code> or <code>ENOTDIR</code>
+
if the file has changed to a directory during the call
+
or the reverse.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>Stdio.File()->unlinkat()</code>, <code>mkdir()</code>, <code>Stdio.recursive_rm()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>file_truncate</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>file_truncate</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>int</code> <code class='argument'>length</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Truncates the file <code>file</code> to the length specified in <code>length</code>.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns 1 if ok, 0 if failed.</p>
+
</dd></dl>
+
</dd>
+
<dt><a name='9.2'></a>
+
<
h2 class='header'>
9.2. Path manipulation</h2></dt>
+
<dd>
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>basename</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string</code> <b><span class='method'>basename</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns the last segment of a path.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>dirname()</code>, <code>explode_path()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>dirname</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string</code> <b><span class='method'>dirname</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns all but the last segment of a path. Some example inputs and
+
outputs:</p>
+
<p> <table class='box'>
+
<tr><td><b>Expression</b></td><td><b>Value</b></td></tr>
+
<tr><td>dirname("/a/b")</td><td>"/a"</td></tr>
+
<tr><td>dirname("/a/")</td><td>"/a"</td></tr>
+
<tr><td>dirname("/a")</td><td>"/"</td></tr>
+
<tr><td>dirname("/")</td><td>"/"</td></tr>
+
<tr><td>dirname("")</td><td>""</td></tr>
+
</table>
+
</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>basename()</code>, <code>explode_path()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>combine_path</b></span><br>
+
<span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>combine_path_unix</b></span><br>
+
<span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>combine_path_nt</b></span><br>
+
<span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>combine_path_amigaos</b></span><br>
+
</dt>
+
<dd><p><code><code class='datatype'>string</code> <b><span class='method'>combine_path</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code> ... <code class='argument'>paths</code><b>)</b></code><br>
+
<code><code class='datatype'>string</code> <b><span class='method'>combine_path_unix</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code> ... <code class='argument'>paths</code><b>)</b></code><br>
+
<code><code class='datatype'>string</code> <b><span class='method'>combine_path_nt</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code> ... <code class='argument'>paths</code><b>)</b></code><br>
+
<code><code class='datatype'>string</code> <b><span class='method'>combine_path_amigaos</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code> ... <code class='argument'>paths</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Concatenate a number of paths to a straightforward path without
+
any <code class='expr'>"//"</code>, <code class='expr'>"/.."</code> or <code class='expr'>"/."</code>. If any path
+
argument is absolute then the result is absolute and the
+
preceding arguments are ignored. If the result is relative then
+
it might have leading <code class='expr'>".."</code> components. If the last
+
nonempty argument ends with a directory separator then the
+
result ends with that too. If all components in a relative path
+
disappear due to subsequent <code class='expr'>".."</code> components then the
+
result is <code class='expr'>"."</code>.</p>
+
<p> <code>combine_path_unix()</code> concatenates in UNIX style, which also is
+
appropriate for e.g. URL:s ("/" separates path components and
+
absolute paths start with "/"). <code>combine_path_nt()</code>
+
concatenates according to NT filesystem conventions ("/" and "\"
+
separates path components and there might be a drive letter in
+
front of absolute paths). <code>combine_path_amigaos()</code> concatenates
+
according to AmigaOS filesystem conventions.</p>
+
<p> <code>combine_path()</code> is equivalent to <code>combine_path_unix()</code> on UNIX-like
+
operating systems, and equivalent to <code>combine_path_nt()</code> on NT-like
+
operating systems, and equivalent to <code>combine_path_amigaos()</code> on
+
AmigaOS-like operating systems.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>getcwd()</code>, <code>Stdio.append_path()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>explode_path</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>explode_path</span>(</b><code class='datatype'>string</code> <code class='argument'>p</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Split a path <code>p</code> into its components.</p>
+
<p> This function divides a path into its components. This might seem like
+
it could be done by dividing the string on <tt>"/"</tt>, but that will
+
not work on some operating systems. To turn the components back into
+
a path again, use <code>combine_path()</code>.</p>
+
</dd></dl>
+
</dd>
+
<dt><a name='9.3'></a>
+
<h2 class='header'>9.3. Status</h2></dt>
+
<dd>
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>file_stat</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>Stdio.Stat</code> <b><span class='method'>file_stat</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Stat a file.</p>
+
<p> If the argument <code>symlink</code> is <code class='expr'>1</code> symlinks will not be followed.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>If the path specified by <code>path</code> doesn't exist <code class='expr'>0</code> (zero) will
+
be returned.</p>
+
<p> Otherwise an object describing the properties of <code>path</code> will be
+
returned.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>In Pike 7.0 and earlier this function returned an array with 7 elements.
+
The old behaviour can be simulated with the following function:</p>
+
<pre><code><span class='type'>array</span><span class='delim'>(</span><span class='type'>int</span><span class='delim'>)</span> file_stat<span class='delim'>(</span><span class='type'>string</span> path<span class='delim'>,</span> <span class='type'>void</span><span class='delim'>|</span><span class='type'>int</span><span class='delim'>(</span>0..1<span class='delim'>)</span> symlink<span class='delim'>)</span>
+
<span class='delim'>{</span>
+
File<span class='delim'>.</span>Stat st <span class='delim'>=</span> predef::file_stat<span class='delim'>(</span>path<span class='delim'>,</span> symlink<span class='delim'>)</span><span class='delim'>;</span>
+
<span class='lang'>if</span> <span class='delim'>(</span><span class='delim'>!</span>st<span class='delim'>)</span> <span class='lang'>return</span> 0<span class='delim'>;</span>
+
<span class='lang'>return</span> <span class='delim'>(</span><span class='type'>array</span><span class='delim'>(</span><span class='type'>int</span><span class='delim'>)</span><span class='delim'>)</span>st<span class='delim'>;</span>
+
<span class='delim'>}</span>
+
</code></pre>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>Stdio.Stat</code>, <code>Stdio.File->stat()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>filesystem_stat</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>) <b><span class='method'>filesystem_stat</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns a mapping describing the properties of the filesystem
+
containing the path specified by <code>path</code>.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>If a filesystem cannot be determined <code class='expr'>0</code> (zero) will be returned.</p>
+
<p> Otherwise a mapping(string:int) with the following fields will be
+
returned:</p>
+
<table class='box'><tr><td><code><code class='key'>"blocksize"</code> : <code class='datatype'>int</code></code></td><td><p>Size in bytes of the filesystem blocks.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"blocks"</code> : <code class='datatype'>int</code></code></td><td><p>Size of the entire filesystem in blocks.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"bfree"</code> : <code class='datatype'>int</code></code></td><td><p>Number of free blocks in the filesystem.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"bavail"</code> : <code class='datatype'>int</code></code></td><td><p>Number of available blocks in the filesystem.
+
This is usually somewhat less than the <code class='expr'>"bfree"</code> value, and
+
can usually be adjusted with eg tunefs(1M).</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"files"</code> : <code class='datatype'>int</code></code></td><td><p>Total number of files (aka inodes) allowed by this filesystem.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"ffree"</code> : <code class='datatype'>int</code></code></td><td><p>Number of free files in the filesystem.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"favail"</code> : <code class='datatype'>int</code></code></td><td><p>Number of available files in the filesystem.
+
This is usually the same as the <code class='expr'>"ffree"</code> value, and can
+
usually be adjusted with eg tunefs(1M).</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"fsname"</code> : <code class='datatype'>string</code></code></td><td><p>Name assigned to the filesystem. This item is not available
+
on all systems.</p>
+
</td></tr>
+
<tr><td><code><code class='key'>"fstype"</code> : <code class='datatype'>string</code></code></td><td><p>Type of filesystem (eg <code class='expr'>"nfs"</code>). This item is not
+
available on all systems. For some more uncommon filesystems
+
this may be an integer representing the magic number for the
+
filesystem type (cf <tt>statfs(2)</tt> on eg Linux systems).</p>
+
</td></tr>
+
</table>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>Please note that not all members are present on all OSs.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>file_stat()</code></p>
+
</dd></dl>
+
<dl><dt><h2 class='header'>
Class <b class='ms datatype'>Stdio.
Stat
</b></h2>
</dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>
-
+
<dd class='body--doc'><p>This object is used to represent file status information
+
from e.g. <code>file_stat()</code>.</p>
+
<p> It contains the following items usually found in a C <tt>struct
+
stat</tt>:</p>
+
<dl class='group--doc'><dt>mode</dt>
+
<dd><p>File mode (see <tt>mknod(2)</tt>).</p>
+
</dd>
+
<dt>size</dt>
+
<dd><p>File size in bytes.</p>
+
</dd>
+
<dt>uid</dt>
+
<dd><p>User ID of the file's owner.</p>
+
</dd>
+
<dt>gid</dt>
+
<dd><p>Group ID of the file's owner.</p>
+
</dd>
+
<dt>atime</dt>
+
<dd><p>Time of last access in seconds since 00:00:00 UTC, 1970-01-01.</p>
+
</dd>
+
<dt>mtime</dt>
+
<dd><p>Time of last data modification.</p>
+
</dd>
+
<dt>ctime</dt>
+
<dd><p>Time of last file status change.</p>
+
</dd>
+
<dt>atime_nsec</dt>
+
<dd><p>Time of last access in nanoseconds, added to atime to get
+
sub-second time</p>
+
</dd>
+
<dt>mtime_nsec</dt>
+
<dd><p>Time of last modification in nanoseconds, added to mtime to get
+
sub-second time</p>
+
</dd>
+
<dt>ctime_nsec</dt>
+
<dd><p>Time of last file status change in nanoseconds, added to ctime to
+
get sub-second time</p>
+
</dd>
+
<dt>ino</dt>
+
<dd><p>Inode number.</p>
+
</dd>
+
<dt>nlink</dt>
+
<dd><p>Number of links.</p>
+
</dd>
+
<dt>dev</dt>
+
<dd><p>ID of the device containing a directory entry for this file.</p>
+
</dd>
+
<dt>rdev</dt>
+
<dd><p>ID of the device.</p>
+
</dd>
+
</dl><p>It also contains some items that correspond to the C <tt>IS*</tt> macros:</p>
+
<dl class='group--doc'><dt>isreg</dt>
+
<dd><p>Set if the file is a regular file.</p>
+
</dd>
+
<dt>isdir</dt>
+
<dd><p>Set if the file is a directory.</p>
+
</dd>
+
<dt>islnk</dt>
+
<dd><p>Set if the file is a symbolic link. Note that symbolic links
+
are normally followed by the stat functions, so this might
+
only be set if you turn that off, e.g. by giving a nonzero
+
second argument to <code>file_stat()</code>.</p>
+
</dd>
+
<dt>isfifo</dt>
+
<dd><p>Set if the file is a FIFO (aka named pipe).</p>
+
</dd>
+
<dt>issock</dt>
+
<dd><p>Set if the file is a socket.</p>
+
</dd>
+
<dt>ischr</dt>
+
<dd><p>Set if the file is a character device.</p>
+
</dd>
+
<dt>isblk</dt>
+
<dd><p>Set if the file is a block device.</p>
+
</dd>
+
</dl><p>There are also some items that provide alternative representations
+
of the above:</p>
+
<dl class='group--doc'><dt>type</dt>
+
<dd><p>The type as a string, can be any of <code class='expr'>"reg"</code>,
+
<code class='expr'>"dir"</code>, <code class='expr'>"lnk"</code>, <code class='expr'>"fifo"</code>, <code class='expr'>"sock"</code>,
+
<code class='expr'>"chr"</code>, <code class='expr'>"blk"</code>, and <code class='expr'>"unknown"</code>.</p>
+
</dd>
+
<dt>mode_string</dt>
+
<dd><p>The file mode encoded as a string in <tt>ls -l</tt> style, e.g.
+
<code class='expr'>"drwxr-xr-x"</code>.</p>
+
</dd>
+
</dl><p>Note that some items might not exist or have meaningful values
+
on some platforms.</p>
+
<p> Additionally, the object may be initialized from or casted to an
+
<code class='expr'>array</code> on the form of a 'traditional' LPC stat-array, and
+
it's also possible to index the object directly with integers as
+
if it were such an array. The stat-array has this format:</p>
+
<table class='box'><tr><td colspan='2'>Array</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>0</code></code></td><td><p>File mode, same as <tt>mode</tt>.</p>
+
</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>1</code></code></td><td><p>If zero or greater, the file is a regular file and this is
+
its size in bytes. If less than zero it gives the type:
+
-2=directory, -3=symlink and -4=device.</p>
+
</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>2</code></code></td><td><p>Time of last access, same as <tt>atime</tt>.</p>
+
</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>3</code></code></td><td><p>Time of last data modification, same as <tt>mtime</tt>.</p>
+
</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>4</code></code></td><td><p>Time of last file status change, same as <tt>ctime</tt>.</p>
+
</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>5</code></code></td><td><p>User ID of the file's owner, same as <tt>uid</tt>.</p>
+
</td></tr>
+
<tr><td><code><code class='datatype'>int</code> <code class='key'>6</code></code></td><td><p>Group ID of the file's owner, same as <tt>gid</tt>.</p>
+
</td></tr>
+
</table><p>It's possible to modify the stat struct by assigning values to
+
the items. They essentially work as variables, although some of
+
them affect others, e.g. setting <code class='expr'>isdir</code> clears <code class='expr'>isreg</code>
+
and setting <code class='expr'>mode_string</code> changes many of the other items.</p>
+
</dd></dl>
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_equal</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>bool</code> <b><span class='method'>equal</span>(</b><span class='class'>Stdio.Stat</span> <span class='argument'>from</span>, <code class='datatype'>mixed</code> <code class='argument'>other</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Compare this object with another <code>Stat</code> object.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>other</code> is a <code>Stat</code> object with the
+
same content, and <code class='expr'>0</code> (zero) otherwise.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>cast</b></span>
+
</dt>
+
<dd><p><code><b>(</b><span class='datatype'><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>)</span><b>)</b><span class='class'>Stdio.Stat</span>()<br><b>(</b><span class='datatype'><code class='datatype'>array</code></span><b>)</b><span class='class'>Stdio.Stat</span>()<br></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Convert the stat object to a mapping or array.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>create</b></span>
+
</dt>
+
<dd><p><code><span class='object'>Stdio.Stat</span> <span class='class'>Stdio.Stat</span><b>(</b><code class='datatype'>void</code>|<code class='datatype'>object</code>|<code class='datatype'>array</code> <code class='argument'>stat</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>A new <code>Stdio.Stat</code> object can be initialized in two ways:</p>
+
<ul>
+
<li><p><code>stat</code> is an object, typically another <code>Stdio.Stat</code>. The
+
stat info is copied from the object by getting the values of
+
<code class='expr'>mode</code>, <code class='expr'>size</code>, <code class='expr'>atime</code>, <code class='expr'>mtime</code>,
+
<code class='expr'>ctime</code>, <code class='expr'>uid</code>, <code class='expr'>gid</code>, <code class='expr'>dev</code>, <code class='expr'>ino</code>,
+
<code class='expr'>nlink</code>, and <code class='expr'>rdev</code>.</p>
+
</li><li><p><code>stat</code> is a seven element array on the 'traditional' LPC
+
stat-array form (see the class doc).</p>
+
</li></ul></dd></dl>
+
</dd></dl></dd>
+
<dt><a name='9.4'></a>
+
<h2 class='header'>9.4. Error handling</h2></dt>
+
<dd>
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>errno</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>errno</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>This function returns the system error from the last file operation.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>Note that you should normally use <code>Stdio.File->errno()</code> instead.</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>Stdio.File->errno()</code>, <code>strerror()</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>strerror</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string</code> <b><span class='method'>strerror</span>(</b><code class='datatype'>int</code> <code class='argument'>errno</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>This function returns a description of an error code. The error
+
code is usually obtained from eg <code>Stdio.File->errno()</code>.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>On some platforms the string returned can be somewhat nondescriptive.</p>
+
</dd></dl>
+
</dd>
+
<dt><a name='9.5'></a>
+
<h2 class='header'>9.5. Files and sockets</h2></dt>
+
<dd><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.File</b></h2>
+
</dt><dd><dl class='group--doc'>
+
<dt class='head--doc'>Description</dt>
<dd class='body--doc'><p>This is the basic I/O object, it provides socket and pipe communication as well as file access. It does not buffer reads and writes by default, and provides no line-by-line reading, that is done
1200:
<dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Stdio.File()->write()</code></p> </dd></dl>
-
</dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Port</b></h2>
+
</dd></dl><
/dd>
+
<dt><a name='9.6'></a>
+
<h2 class='header'>9.6. Ports and UDP</h2></dt>
+
<dd><
dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Port</b></h2>
</dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Handles listening to socket ports. Whenever you need a bound
2039:
<dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if data are ready, <code class='expr'>0</code> (zero) otherwise.</p> </dd></dl>
-
</dd></dl><dl><dt><h2 class='header'>Module <b class='ms datatype'>Stdio.Terminfo</b></h2>
+
</dd></dl><
/dd>
+
<dt><a name='9.7'></a>
+
<h2 class='header'>9.7. Terminal I/O</h2></dt>
+
<dd><
dl><dt><h2 class='header'>Module <b class='ms datatype'>Stdio.Terminfo</b></h2>
</dt><dd> <hr />
3388:
</dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>word_break</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>hide</code><b>)</b></code></p></dd> </dl>
-
</dd></dl></dd></dl><dl><dt><h2 class='header'>Module <b class='ms datatype'>Stdio</b></h2>
+
</dd></dl></dd></dl><
/dd>
+
<dt><a name='9.8'></a>
+
<h2 class='header'>9.8. Other</h2></dt>
+
<dd><
dl><dt><h2 class='header'>Module <b class='ms datatype'>Stdio</b></h2>
</dt><dd> <hr />
8014:
<dd><p><code><code class='modifier'>optional</code> <code class='object unresolved'>NonblockingStream</code> <b><span class='method'>set_read_oob_callback</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code> ... <code class='argument'>rest</code><b>)</b></code><br> <code><code class='modifier'>optional</code> <code class='object unresolved'>NonblockingStream</code> <b><span class='method'>set_write_oob_callback</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code> ... <code class='argument'>rest</code><b>)</b></code></p></dd> </dl>
-
</dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Stat</b></h2>
-
</dt><dd><dl class='group--doc'>
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>This object is used to represent file status information
-
from e.g. <code>file_stat()</code>.</p>
-
<p> It contains the following items usually found in a C <tt>struct
-
stat</tt>:</p>
-
<dl class='group--doc'><dt>mode</dt>
-
<dd><p>File mode (see <tt>mknod(2)</tt>).</p>
-
</dd>
-
<dt>size</dt>
-
<dd><p>File size in bytes.</p>
-
</dd>
-
<dt>uid</dt>
-
<dd><p>User ID of the file's owner.</p>
-
</dd>
-
<dt>gid</dt>
-
<dd><p>Group ID of the file's owner.</p>
-
</dd>
-
<dt>atime</dt>
-
<dd><p>Time of last access in seconds since 00:00:00 UTC, 1970-01-01.</p>
-
</dd>
-
<dt>mtime</dt>
-
<dd><p>Time of last data modification.</p>
-
</dd>
-
<dt>ctime</dt>
-
<dd><p>Time of last file status change.</p>
-
</dd>
-
<dt>atime_nsec</dt>
-
<dd><p>Time of last access in nanoseconds, added to atime to get
-
sub-second time</p>
-
</dd>
-
<dt>mtime_nsec</dt>
-
<dd><p>Time of last modification in nanoseconds, added to mtime to get
-
sub-second time</p>
-
</dd>
-
<dt>ctime_nsec</dt>
-
<dd><p>Time of last file status change in nanoseconds, added to ctime to
-
get sub-second time</p>
-
</dd>
-
<dt>ino</dt>
-
<dd><p>Inode number.</p>
-
</dd>
-
<dt>nlink</dt>
-
<dd><p>Number of links.</p>
-
</dd>
-
<dt>dev</dt>
-
<dd><p>ID of the device containing a directory entry for this file.</p>
-
</dd>
-
<dt>rdev</dt>
-
<dd><p>ID of the device.</p>
-
</dd>
-
</dl><p>It also contains some items that correspond to the C <tt>IS*</tt> macros:</p>
-
<dl class='group--doc'><dt>isreg</dt>
-
<dd><p>Set if the file is a regular file.</p>
-
</dd>
-
<dt>isdir</dt>
-
<dd><p>Set if the file is a directory.</p>
-
</dd>
-
<dt>islnk</dt>
-
<dd><p>Set if the file is a symbolic link. Note that symbolic links
-
are normally followed by the stat functions, so this might
-
only be set if you turn that off, e.g. by giving a nonzero
-
second argument to <code>file_stat()</code>.</p>
-
</dd>
-
<dt>isfifo</dt>
-
<dd><p>Set if the file is a FIFO (aka named pipe).</p>
-
</dd>
-
<dt>issock</dt>
-
<dd><p>Set if the file is a socket.</p>
-
</dd>
-
<dt>ischr</dt>
-
<dd><p>Set if the file is a character device.</p>
-
</dd>
-
<dt>isblk</dt>
-
<dd><p>Set if the file is a block device.</p>
-
</dd>
-
</dl><p>There are also some items that provide alternative representations
-
of the above:</p>
-
<dl class='group--doc'><dt>type</dt>
-
<dd><p>The type as a string, can be any of <code class='expr'>"reg"</code>,
-
<code class='expr'>"dir"</code>, <code class='expr'>"lnk"</code>, <code class='expr'>"fifo"</code>, <code class='expr'>"sock"</code>,
-
<code class='expr'>"chr"</code>, <code class='expr'>"blk"</code>, and <code class='expr'>"unknown"</code>.</p>
-
</dd>
-
<dt>mode_string</dt>
-
<dd><p>The file mode encoded as a string in <tt>ls -l</tt> style, e.g.
-
<code class='expr'>"drwxr-xr-x"</code>.</p>
-
</dd>
-
</dl><p>Note that some items might not exist or have meaningful values
-
on some platforms.</p>
-
<p> Additionally, the object may be initialized from or casted to an
-
<code class='expr'>array</code> on the form of a 'traditional' LPC stat-array, and
-
it's also possible to index the object directly with integers as
-
if it were such an array. The stat-array has this format:</p>
-
<table class='box'><tr><td colspan='2'>Array</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>0</code></code></td><td><p>File mode, same as <tt>mode</tt>.</p>
-
</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>1</code></code></td><td><p>If zero or greater, the file is a regular file and this is
-
its size in bytes. If less than zero it gives the type:
-
-2=directory, -3=symlink and -4=device.</p>
-
</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>2</code></code></td><td><p>Time of last access, same as <tt>atime</tt>.</p>
-
</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>3</code></code></td><td><p>Time of last data modification, same as <tt>mtime</tt>.</p>
-
</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>4</code></code></td><td><p>Time of last file status change, same as <tt>ctime</tt>.</p>
-
</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>5</code></code></td><td><p>User ID of the file's owner, same as <tt>uid</tt>.</p>
-
</td></tr>
-
<tr><td><code><code class='datatype'>int</code> <code class='key'>6</code></code></td><td><p>Group ID of the file's owner, same as <tt>gid</tt>.</p>
-
</td></tr>
-
</table><p>It's possible to modify the stat struct by assigning values to
-
the items. They essentially work as variables, although some of
-
them affect others, e.g. setting <code class='expr'>isdir</code> clears <code class='expr'>isreg</code>
-
and setting <code class='expr'>mode_string</code> changes many of the other items.</p>
-
</dd></dl>
-
-
<hr />
-
<dl class='group--doc'>
-
<dt class='head--type'><span class='homogen--type'>Method</span>
-
<span class='homogen--name'><b>_equal</b></span>
-
</dt>
-
<dd><p><code><code class='datatype'>bool</code> <b><span class='method'>equal</span>(</b><span class='class'>Stdio.Stat</span> <span class='argument'>from</span>, <code class='datatype'>mixed</code> <code class='argument'>other</code><b>)</b></code></p></dd>
-
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>Compare this object with another <code>Stat</code> object.</p>
-
</dd>
-
<dt class='head--doc'>Returns</dt>
-
<dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>other</code> is a <code>Stat</code> object with the
-
same content, and <code class='expr'>0</code> (zero) otherwise.</p>
-
</dd></dl>
-
-
-
<hr />
-
<dl class='group--doc'>
-
<dt class='head--type'><span class='homogen--type'>Method</span>
-
<span class='homogen--name'><b>cast</b></span>
-
</dt>
-
<dd><p><code><b>(</b><span class='datatype'><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>)</span><b>)</b><span class='class'>Stdio.Stat</span>()<br><b>(</b><span class='datatype'><code class='datatype'>array</code></span><b>)</b><span class='class'>Stdio.Stat</span>()<br></code></p></dd>
-
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>Convert the stat object to a mapping or array.</p>
-
</dd></dl>
-
-
-
<hr />
-
<dl class='group--doc'>
-
<dt class='head--type'><span class='homogen--type'>Method</span>
-
<span class='homogen--name'><b>create</b></span>
-
</dt>
-
<dd><p><code><span class='object'>Stdio.Stat</span> <span class='class'>Stdio.Stat</span><b>(</b><code class='datatype'>void</code>|<code class='datatype'>object</code>|<code class='datatype'>array</code> <code class='argument'>stat</code><b>)</b></code></p></dd>
-
-
<dt class='head--doc'>Description</dt>
-
<dd class='body--doc'><p>A new <code>Stdio.Stat</code> object can be initialized in two ways:</p>
-
<ul>
-
<li><p><code>stat</code> is an object, typically another <code>Stdio.Stat</code>. The
-
stat info is copied from the object by getting the values of
-
<code class='expr'>mode</code>, <code class='expr'>size</code>, <code class='expr'>atime</code>, <code class='expr'>mtime</code>,
-
<code class='expr'>ctime</code>, <code class='expr'>uid</code>, <code class='expr'>gid</code>, <code class='expr'>dev</code>, <code class='expr'>ino</code>,
-
<code class='expr'>nlink</code>, and <code class='expr'>rdev</code>.</p>
-
</li><li><p><code>stat</code> is a seven element array on the 'traditional' LPC
-
stat-array form (see the class doc).</p>
-
</li></ul></dd></dl>
+
</dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Stream</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>