autodoc.git/ traditional_manual/ chapter_9.html

Branch: Tag:

2014-09-28

2014-09-28 19:11:31 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Stdio.Fd: Map _errno.

Make it possible to set the errno for a Stdio.File from Pike code.

Also added some minimal documentation for the other mapped fields
in Stdio.Fd, as well as moving the documentation for the low-level
functions from Stdio.File to Stdio.Fd.

22:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>`&lt;&lt;</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stdio.File</code> res = <code class='class'>Stdio.File()</code>&#32;&lt;&lt;&#32;<code class='class'>data</code></code><br> - <code><code class='object unresolved'>Stdio.File</code> res = <code class='class'>Stdio.File()</code>&#32;&lt;&lt;&#32;<code class='class'>data</code></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Write some data to a file.</p> - <p> If <code>data</code> is not a string, it is casted to string, and then -  written to the file.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Throws an error if not all data could be written.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>write()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>assign</b></span>   </dt>   <dd><p><code><code class='datatype'>int</code> <b><span class='method'>assign</span>(</b><code class='object unresolved'>File</code>|<code class='object unresolved'>Fd</code> <code class='argument'>o</code><b>)</b></code></p></dd>
136:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>close</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>close</span>(</b><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>close</span>(</b><code class='datatype'>string</code> <code class='argument'>direction</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Close a file or stream.</p> - <p> If direction is not specified, both the read and the write -  direction is closed. Otherwise only the directions specified is -  closed.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Nonzero is returned if the file or stream wasn't open in the -  specified direction, zero otherwise.</p> - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'><p>An exception is thrown if an I/O error occurs.</p> - <p> The default behaviour for sockets is typically to flush buffered -  data in the background, but this can be changed with <code>linger()</code>.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p><code>close()</code> has no effect if this file object has been associated -  with an already opened file, i.e. if <code>open()</code> was given an -  integer as the first argument.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>linger()</code>, <code>open()</code>, <code>open_socket()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>connect</b></span>   </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code><b>)</b></code><br> - <code><code class='datatype'>bool</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code> <code class='argument'>src_port</code><b>)</b></code><br> - <code><code class='datatype'>string(8bit)</code>|<code class='datatype'>int(0..0)</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_port</code>, <code class='datatype'>string(8bit)</code> <code class='argument'>data</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Open a TCP/IP connection to the specified destination.</p> - <p> In nonblocking mode, success is indicated with the write-callback, -  and failure with the close-callback or the read_oob-callback.</p> - <p> If the <code>data</code> argument is included the socket will use -  TCP_FAST_OPEN if available, if not the data will <i>not be -  sent</i>. In the data case the function either returns the data -  that has not been sent (only one packet can be sent with this -  option) or 0 if the connection failed immediately.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns <code class='expr'>1</code> or the remaining <code class='expr'>data</code> on success, and -  <code class='expr'>0</code> on failure.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set -  to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded -  as a connection failure.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>connect</b></span> - </dt> +    <dd><p><code><code class='modifier'>variant</code> <code class='datatype'>int</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code><b>)</b></code><br>   <code><code class='modifier'>variant</code> <code class='datatype'>int</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>client</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>client_port</code><b>)</b></code><br>   <code><code class='modifier'>variant</code> <code class='datatype'>string</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code><br>
246:   <dt class='head--type'><span class='homogen--type'>Method</span>   <span class='homogen--name'><b>connect_unix</b></span>   </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>connect_unix</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Open a UNIX domain socket connection to the specified destination.</p> - </dd> - <dt class='head--doc'><span id='p-filename'></span>Parameter <code class='parameter'>filename</code></dt> - <dd></dd><dd class='body--doc'><p>Filename to create.</p> - <p> In nonblocking mode, success is indicated with the write-callback, -  and failure with the close-callback or the read_oob-callback.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set -  to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded -  as a connection failure.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p><code>path</code> had a quite restrictive length limit (~100 characters) -  prior to Pike 7.8.334.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>connect_unix</b></span> - </dt> +    <dd><p><code><code class='datatype'>int</code> <b><span class='method'>connect_unix</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt>
330:   <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.File</span> <span class='class'>Stdio.File</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code><b>)</b></code><br> - <code><span class='object'>Stdio.File</span> <span class='class'>Stdio.File</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> - <code><span class='object'>Stdio.File</span> <span class='class'>Stdio.File</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code><b>)</b></code><br> - <code><span class='object'>Stdio.File</span> <span class='class'>Stdio.File</span><b>(</b><code class='datatype'>int</code> <code class='argument'>fd</code><b>)</b></code><br> - <code><span class='object'>Stdio.File</span> <span class='class'>Stdio.File</span><b>(</b><code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>See <code>open()</code>.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>open()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>dup</b></span>   </dt>   <dd><p><code><code class='object unresolved'>File</code> <b><span class='method'>dup</span>(</b><b>)</b></code></p></dd>
368:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>dup</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stdio.Fd</code> <b><span class='method'>dup</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Duplicate the file.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>dup2()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>dup2</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>dup2</span>(</b><code class='object unresolved'>Stdio.File</code> <code class='argument'>to</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Duplicate a file over another.</p> - <p> This function works similarly to <code>assign()</code>, but instead of making -  the argument a reference to the same file, it creates a new file -  with the same properties and places it in the argument.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success and <code class='expr'>0</code> (zero) on failure.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>In Pike 7.7 and later <code>to</code> need not be open, in which -  case a new fd is allocated.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Note also that <code>to</code> is also assigned to the same backend (if any) -  as this object.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>assign()</code>, <code>dup()</code></p> - </dd></dl> -  -  - <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>
424:      <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>Return the errno for the latest failed file operation.</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'>string</code>|<code class='datatype'>void</code> <code class='argument'>path</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Get directory contents relative to an open directory.</p> - </dd> - <dt class='head--doc'><span id='p-path'></span>Parameter <code class='parameter'>path</code></dt> - <dd></dd><dd class='body--doc'><p>Path relative to the open directory. Defaults to the -  directory itself.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns an array of filenames.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Not available on all architectures, or in Pike 7.6 and earlier.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>predef::get_dir()</code>, <code>statat()</code>, <code>openat()</code>, <code>unlinkat()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>getxattr</b></span> - </dt> - <dd><p><code><code class='datatype'>string</code> <b><span class='method'>getxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Return the value of a specified attribute, or 0 if it does not exist</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>grantpt</b></span> - </dt> - <dd><p><code><code class='datatype'>string</code> <b><span class='method'>grantpt</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>If this file has been created by calling <code>openpt()</code>, return the -  filename of the associated pts-file. This function should only be -  called once.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns the filename of the corresponding pts.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>This function is only available on some platforms.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> +    <dt class='head--type'><span class='homogen--type'>Inherit</span>   <span class='homogen--name'><b>Fd</b></span>   </dt>
503:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>is_open</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>is_open</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Returns true if the file is open.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>If the file is a socket that has been closed from the remote side, -  this function might still return true.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Most methods can't be called for a file descriptor that isn't -  open. Notable exceptions <code>errno</code>, <code>mode</code>, and the set and query -  functions for callbacks and backend.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>line_iterator</b></span>   </dt>   <dd><p><code><code class='object unresolved'>String.SplitIterator</code>|<code class='object unresolved'>LineIterator</code> <b><span class='method'>line_iterator</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>trim</code><b>)</b></code></p></dd>
538:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>linger</b></span> - </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>linger</span>(</b><code class='datatype'>int(-1..65535)</code>|<code class='datatype'>void</code> <code class='argument'>seconds</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Set the socket linger behaviour on <code>close()</code>.</p> - </dd> - <dt class='head--doc'><span id='p-seconds'></span>Parameter <code class='parameter'>seconds</code></dt> - <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>-1</code></code></td><td><p>Reset to default behaviour. This typically means that -  <code>close()</code> will return immediately, but any buffered -  data will still be sent if possible.</p> - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td><p>Terminate the connection immediately on <code>close()</code>, -  and discard any buffered data.</p> - </td></tr> - <tr><td><code><code class='key'>(1..65535)</code></code></td><td><p>Have <code>close()</code> wait for at most <code>seconds</code> seconds -  for any buffered data to be sent after which the -  connection is terminated.</p> - </td></tr> - </table> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>This operation is only valid on sockets.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>This function was not available in Pike 7.8.775 and earlier.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>close()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>listxattr</b></span> - </dt> - <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>listxattr</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Return an array of all extended attributes set on the file</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>lock</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>lock</span>(</b><b>)</b></code><br> - <code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>lock</span>(</b><code class='datatype'>bool</code> <code class='argument'>is_recursive</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Makes an exclusive file lock on this file.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>trylock()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>mode</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>mode</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Returns the open mode and capabilities for the file.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns an <code>`|()</code> of the following flags:</p> - <table class='box'><tr><td><code><code class='key'>0x1000</code></code></td><td><p><code>FILE_READ</code></p> - </td></tr> - <tr><td><code><code class='key'>0x2000</code></code></td><td><p><code>FILE_WRITE</code></p> - </td></tr> - <tr><td><code><code class='key'>0x4000</code></code></td><td><p><code>FILE_APPEND</code></p> - </td></tr> - <tr><td><code><code class='key'>0x8000</code></code></td><td><p><code>FILE_CREATE</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0100</code></code></td><td><p><code>FILE_TRUNC</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0200</code></code></td><td><p><code>FILE_EXCLUSIVE</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0400</code></code></td><td><p><code>FILE_NONBLOCKING</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0040</code></code></td><td><p><code>PROP_SEND_FD</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0010</code></code></td><td><p><code>PROP_BIDIRECTIONAL</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0008</code></code></td><td><p><code>PROP_BUFFERED</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0004</code></code></td><td><p><code>PROP_SHUTDOWN</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0002</code></code></td><td><p><code>PROP_NONBLOCK</code></p> - </td></tr> - <tr><td><code><code class='key'>0x0001</code></code></td><td><p><code>PROP_IPC</code></p> - </td></tr> - </table> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>In some versions of Pike 7.7 and 7.8 the <tt>PROP_</tt> flags were -  filtered from the result.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>open()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>open</b></span>   </dt>   <dd><p><code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br>
690:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>open</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Open a file, or use an existing fd.</p> - <p> If <code>filename</code> is given, attempt to open the named file. If <code>fd</code> -  is given instead, it should be the file descriptor for an already -  opened file, which will then be used by this object.</p> - <p> <code>mode</code> describes how the file is opened. It's a case-insensitive -  string consisting of one or more of the following letters:</p> - <dl class='group--doc'><dt>"r"</dt> - <dd><p>Open for reading.</p> - </dd> - <dt>"w"</dt> - <dd><p>Open for writing.</p> - </dd> - <dt>"a"</dt> - <dd><p>Append new data to the end.</p> - </dd> - <dt>"c"</dt> - <dd><p>Create the file if it doesn't exist already.</p> - </dd> - <dt>"t"</dt> - <dd><p>Truncate the file to zero length if it already contains data. -  Use only together with <code class='expr'>"w"</code>.</p> - </dd> - <dt>"x"</dt> - <dd><p>Open exclusively - the open fails if the file already exists. -  Use only together with <code class='expr'>"c"</code>. Note that it's not safe to -  assume that this is atomic on some systems.</p> - </dd> - </dl><p><code>access</code> specifies the permissions to use if a new file is -  created. It is a UNIX style permission bitfield:</p> - <dl class='group--doc'><dt>0400</dt> - <dd><p>User has read permission.</p> - </dd> - <dt>0200</dt> - <dd><p>User has write permission.</p> - </dd> - <dt>0100</dt> - <dd><p>User has execute permission.</p> - </dd> - <dt>0040</dt> - <dd><p>Group has read permission.</p> - </dd> - <dt>0020</dt> - <dd><p>Group has write permission.</p> - </dd> - <dt>0010</dt> - <dd><p>Group has execute permission.</p> - </dd> - <dt>0004</dt> - <dd><p>Others have read permission.</p> - </dd> - <dt>0002</dt> - <dd><p>Others have write permission.</p> - </dd> - <dt>0001</dt> - <dd><p>Others have execute permission.</p> - </dd> - </dl><p>It's system dependent on which of these bits that are actually -  heeded. If <code>access</code> is not specified, it defaults to -  <code class='expr'>00666</code>, but note that on UNIX systems it's masked with the -  process umask before use.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns nonzero on success and <code class='expr'>0</code> (zero) on failure. If -  there is a failure then <code>errno</code> returns the error code.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>close()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>open_socket</b></span>   </dt>   <dd><p><code><code class='datatype'>int</code> <b><span class='method'>open_socket</span>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code><b>)</b></code></p></dd>
810:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>open_socket</b></span> - </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>open_socket</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>addr</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code><b>)</b></code></p></dd> - </dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>openat</b></span>   </dt>   <dd><p><code><code class='object unresolved'>File</code> <b><span class='method'>openat</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br>
835:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>openat</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>openat</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> - <code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>openat</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Open a file relative to an opened directory.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns a new file object on success, and <code class='expr'>0</code> (zero) on failure.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Not available on all architectures, or in Pike 7.6 and earlier.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>open()</code>, <code>statat()</code>, <code>unlinkat()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>openpt</b></span>   </dt>   <dd><p><code><code class='datatype'>int</code> <b><span class='method'>openpt</span>(</b><code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd>
879:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>openpt</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>openpt</span>(</b><code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Open the master end of a pseudo-terminal pair.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>grantpt()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>peek</b></span> - </dt> - <dd><p><code><code class='datatype'>int(-1..1)</code> <b><span class='method'>peek</span>(</b><b>)</b></code><br> - <code><code class='datatype'>int(-1..1)</code> <b><span class='method'>peek</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code><b>)</b></code><br> - <code><code class='datatype'>int(-1..1)</code> <b><span class='method'>peek</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>, <code class='datatype'>int</code> <code class='argument'>not_eof</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Check if there is data available to read, -  or wait some time for available data to read.</p> - <p> More specifically, a later call to <code>read()</code> will return -  immediately, either due to data being present, or due to -  some error (eg if a socket has been closed).</p> - </dd> - <dt class='head--doc'><span id='p-timeout'></span>Parameter <code class='parameter'>timeout</code></dt> - <dd></dd><dd class='body--doc'><p>Timeout in seconds.</p> - </dd> - <dt class='head--doc'><span id='p-not_eof'></span>Parameter <code class='parameter'>not_eof</code></dt> - <dd></dd><dd class='body--doc'><p>Flag for specifying handling of end of file. -  The following values are currently defined:</p> - <table class='box'><tr><td><code><code class='key'>0</code></code></td><td><p>Traditional (and default) behaviour. Return <code class='expr'>1</code> -  at EOF.</p> - </td></tr> - <tr><td><code><code class='key'>1</code></code></td><td><p>Regard EOF as an error. Return <code class='expr'>-1</code> and set <code>errno()</code> -  to return <code class='expr'>EPIPE</code> at EOF.</p> - </td></tr> - </table> - </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>There is data available to <code>read()</code>, or <code>not_eof</code> is -  <code class='expr'>0</code> (zero) and we're at EOF. A later call to -  <code>read()</code> will not block.</p> - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td><p>There is no data available (ie timeout).</p> - </td></tr> - <tr><td><code><code class='key'>-1</code></code></td><td><p>Error condition. The error code returned by <code>errno()</code> -  has been updated.</p> - </td></tr> - </table> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>errno()</code>, <code>read()</code></p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>The function may be interrupted prematurely -  of the timeout (due to signals); -  check the timing manually if this is imporant.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>The <code>not_eof</code> parameter was added in Pike 7.7.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>This function was not available on NT in Pike 7.6 and earlier.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>pipe</b></span>   </dt> - <dd><p><code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>pipe</span>(</b><b>)</b></code><br> - <code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>pipe</span>(</b><code class='datatype'>int</code> <code class='argument'>flags</code><b>)</b></code></p></dd> - </dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>pipe</b></span> - </dt> +    <dd><p><code><code class='object unresolved'>File</code> <b><span class='method'>pipe</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>required_properties</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt>
1016:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>proxy</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>proxy</span>(</b><code class='object unresolved'>Stdio.File</code> <code class='argument'>from</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Starts a thread that asynchronously copies data from <code>from</code> -  to this file.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>Stdio.sendfile()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>query_address</b></span> - </dt> - <dd><p><code><code class='datatype'>string</code> <b><span class='method'>query_address</span>(</b><b>)</b></code><br> - <code><code class='datatype'>string</code> <b><span class='method'>query_address</span>(</b><code class='datatype'>bool</code> <code class='argument'>local</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Get address and port of a socket end-point.</p> - </dd> - <dt class='head--doc'><span id='p-local'></span>Parameter <code class='parameter'>local</code></dt> - <dd></dd><dd class='body--doc'><p>If the argument <code>local</code> is not specified, or is <code class='expr'>0</code> -  (zero), the remote end-point is returned. Otherwise, if <code>local</code> -  is <code class='expr'>1</code>, the local end-point is returned.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>This function returns the address and port of a socket end-point -  on the form <code class='expr'>"x.x.x.x&nbsp;port"</code> (IPv4) or -  <code class='expr'>"x:x:x:x:x:x:x:x&nbsp;port"</code> (IPv6). IPv6 addresses -  may use the contracted syntax.</p> - <p> If this file is not a socket, is not connected, or some other -  error occurs, <code class='expr'>0</code> (zero) is returned and <code>errno()</code> will -  return the error code.</p> - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'><p>An error is thrown if the socket (or file) isn't open.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>connect()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>query_backend</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Pike.Backend</code> <b><span class='method'>query_backend</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Return the backend used for the callbacks.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>set_backend</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>query_read_callback</b></span><br>   <span class='homogen--type'>Method</span>   <span class='homogen--name'><b>query_write_callback</b></span><br>
1116:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>query_fd</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>query_fd</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Returns the file descriptor number associated with this object.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>query_id</b></span>   </dt>   <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>query_id</span>(</b><b>)</b></code></p></dd>
1142:      <hr />   <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>read</b></span> - </dt> - <dd><p><code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><b>)</b></code><br> - <code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code><b>)</b></code><br> - <code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Read data from a file or a stream.</p> - <p> Attempts to read <code>len</code> bytes from the file, and return it as a -  string. Less than <code>len</code> bytes can be returned if:</p> - <ul> - <li><p>end-of-file is encountered for a normal file, or</p> - </li><li><p>it's a stream that has been closed from the other end, or</p> - </li><li><p>it's a stream in nonblocking mode, or</p> - </li><li><p>it's a stream and <code>not_all</code> is set, or</p> - </li><li><p><code>not_all</code> isn't set and an error occurred (see below).</p> - </li></ul><p>If <code>not_all</code> is nonzero, <code>read()</code> does not try its best to read -  as many bytes as you have asked for, but merely returns as much as -  the system read function returns. This is mainly useful with -  stream devices which can return exactly one row or packet at a -  time. If <code>not_all</code> is used in blocking mode, <code>read()</code> only -  blocks if there's no data at all available.</p> - <p> If something goes wrong and <code>not_all</code> is set, zero is returned. -  If something goes wrong and <code>not_all</code> is zero or left out, then -  either zero or a string shorter than <code>len</code> is returned. If the -  problem persists then a later call to <code>read()</code> fails and returns -  zero, however.</p> - <p> If everything went fine, a call to <code>errno()</code> directly afterwards -  returns zero. That includes an end due to end-of-file or remote -  close.</p> - <p> If no arguments are given, <code>read()</code> reads to the end of the file -  or stream.</p> - <p> If any file descriptors have been sent by the other side of the -  stream, <code>receive_fd()</code> will be called once for every sent file -  descriptor.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>It's not necessary to set <code>not_all</code> to avoid blocking reading -  when nonblocking mode is used.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>When at the end of a file or stream, repeated calls to <code>read()</code> -  will return the empty string since it's not considered an error. -  The empty string is never returned in other cases, unless nonblocking -  mode is used or <code>len</code> is zero.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>read_oob()</code>, <code>write()</code>, <code>receive_fd()</code>, <code>send_fd()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> +    <dt class='head--type'><span class='homogen--type'>Typedef</span>   <span class='homogen--name'><b>read_callback_t</b></span>   </dt>
1231:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>read_oob</b></span> - </dt> - <dd><p><code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><b>)</b></code><br> - <code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code><b>)</b></code><br> - <code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Attempts to read <code>len</code> bytes of out-of-band data from the stream, -  and returns it as a string. Less than <code>len</code> bytes can be returned -  if:</p> - <ul> - <li><p>the stream has been closed from the other end, or</p> - </li><li><p>nonblocking mode is used, or</p> - </li><li><p><code>not_all</code> is set, or</p> - </li><li><p><code>not_all</code> isn't set and an error occurred (see below).</p> - </li></ul><p>If <code>not_all</code> is nonzero, <code>read_oob()</code> only returns as many bytes -  of out-of-band data as are currently available.</p> - <p> If something goes wrong and <code>not_all</code> is set, zero is returned. -  If something goes wrong and <code>not_all</code> is zero or left out, then -  either zero or a string shorter than <code>len</code> is returned. If the -  problem persists then a later call to <code>read_oob()</code> fails and -  returns zero, however.</p> - <p> If everything went fine, a call to <code>errno()</code> directly afterwards -  returns zero. That includes an end due to remote close.</p> - <p> If no arguments are given, <code>read_oob()</code> reads to the end of the -  stream.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Out-of-band data was not supported in Pike 0.5 and earlier, and -  not in Pike 0.6 through 7.4 if they were compiled with the -  option <tt>'--without-oob'</tt>.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>It is not guaranteed that all out-of-band data sent from the -  other end is received. Most streams only allow for a single byte -  of out-of-band data at a time.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>It's not necessary to set <code>not_all</code> to avoid blocking reading -  when nonblocking mode is used.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>When at the end of a file or stream, repeated calls to <code>read()</code> -  returns the empty string since it's not considered an error. The -  empty string is never returned in other cases, unless nonblocking -  mode is used or <code>len</code> is zero.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>receive_fd</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>receive_fd</span>(</b><code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Remote file descriptor reception handler.</p> - </dd> - <dt class='head--doc'><span id='p-fd'></span>Parameter <code class='parameter'>fd</code></dt> - <dd></dd><dd class='body--doc'><p>File descriptor received from the remote end of a <code>pipe()</code>. -  This object has been created by <code>fd_factory()</code>.</p> - <p> This function is called from <code>read()</code> when a remote file -  descriptor has been received over a <code>PROP_SEND_FD</code> -  capable <code>pipe()</code>.</p> - <p> The default implementation is just a prototype.</p> - <p> Overload this function to enable reception of -  remote file descriptors.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>The capability of sending and receiving remote file -  descriptors is only available on some operating systems. -  This capability is indicated by the precence of <code>__HAVE_SEND_FD__</code>.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>send_fd()</code>, <code>read()</code>, <code>fd_factory()</code>, <code>__HAVE_SEND_FD__</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>release_fd</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>release_fd</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Returns the file descriptor number associated with this object, in -  addition to releasing it so that this object behaves as if closed. -  Other settings like callbacks and backend remain intact. -  <code>take_fd</code> can later be used to reinstate the file descriptor so -  that the state is restored.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>query_fd()</code>, <code>take_fd()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>removexattr</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>removexattr</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Remove the specified extended attribute.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>seek</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>seek</span>(</b><code class='datatype'>int</code> <code class='argument'>offset</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>seek</span>(</b><code class='datatype'>int</code> <code class='argument'>offset</code>, <code class='datatype'>string</code> <code class='argument'>whence</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>The seek() function repositions the offset of the open file -  associated with the file descriptor fd to the argument <code>offset</code> -  according to the directive <code>whence</code> as follows:</p> - <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_SET</code></code></td><td><p>The offset is set to <code>offset</code> bytes.</p> - </td></tr> - <tr><td><code><code class='key'>Stdio.SEEK_CUR</code></code></td><td><p>The offset is set to its current location plus <code>offset</code> bytes.</p> - </td></tr> - <tr><td><code><code class='key'>Stdio.SEEK_END</code></code></td><td><p>The offset is set to the size of the file plus <code>offset</code> bytes.</p> - </td></tr> - </table><p>If <code>whence</code> is not specified it is SEEK_SET if <code>offset</code> is -  positive, and if <code>offset</code> is negative SEEK_END.</p> - <p> The seek() function on most operating systems allows the file -  offset to be set beyond the end of the file (but this does not -  change the size of the file). If data is later written at this -  point, subsequent reads of the data in the gap (a "hole") return -  null bytes ('\0') until data is actually written into the gap.</p> - <p> Seeking file data and holes</p> - <p> Stdio.SEEK_DATA and Stdio.SEEK_HOLE are nonstandard extensions -  present in Linux, Solaris, FreeBSD, and DragonFly BSD; they are -  proposed for inclusion in the next POSIX revision.</p> - <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_DATA</code></code></td><td><p>Adjust the file offset to the next location in the file greater -  than or equal to offset containing data. If offset points to -  data, then the file offset is set to offset.</p> - </td></tr> - <tr><td><code><code class='key'>Stdio.SEEK_HOLE</code></code></td><td><p>Adjust the file offset to the next hole in the file greater than -  or equal to offset. If offset points into the middle of a hole, -  then the file offset is set to offset. If there is no hole past -  offset, then the file offset is adjusted to the end of the file -  (i.e., there is an implicit hole at the end of any file).</p> - </td></tr> - </table><p>In both of the above cases, seek() fails if offset points past the -  end of the file.</p> - <p> These operations allow applications to map holes in a sparsely -  allocated file. This can be useful for applications such as file -  backup tools, which can save space when creating backups and -  preserve holes, if they have a mechanism for discovering holes.</p> - <p> For the purposes of these operations, a hole is a sequence of -  zeros that (normally) has not been allocated in the underlying -  file storage. However, a filesystem is not obliged to report -  holes, so these operations are not a guaranteed mechanism for -  mapping the storage space actually allocated to a file. -  (Furthermore, a sequence of zeros that actually has been written -  to the underlying storage may or may not be reported as a hole.)</p> - <p> In the simplest implementation, a filesystem can support the -  operations by making SEEK_HOLE always return the offset of the end -  of the file, and making SEEK_DATA always return offset (i.e., even -  if the location referred to by offset is a hole, it can be -  considered to consist of data that is a sequence of zeros).</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Upon successful completion, seek() returns the resulting offset -  location as measured in bytes from the beginning of the file. On -  error, the value (off_t) -1 is returned and <code>errno</code> is set to -  indicate the error.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>tell()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>send_fd</b></span>   </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>send_fd</span>(</b><code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Queues an open file descriptor for sending to the other end of a stream.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>The actual sending is performed at the next successful call -  to <code>write()</code>, this is due to limitations in the system calls. -  This means that it isn't possible to send a file descriptor -  without also sending some in-band data.</p> - <p> This operation is only supported on <code>pipe()</code>'s created with -  <code>PROP_SEND_FD</code>.</p> - <p> This function is not available on all operating systems, check -  for <code>__HAVE_SEND_FD__</code>.</p> - <p> The queue is emptied on successful <code>write()</code> and when the -  write direction is <code>close()</code>'d.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>receive_fd()</code>, <code>write()</code>, <code>pipe()</code>, <code>read()</code>, <code>__HAVE_SEND_FD__</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>send_fd</b></span> - </dt> +    <dd><p><code><code class='datatype'>void</code> <b><span class='method'>send_fd</span>(</b><code class='object unresolved'>File</code>|<code class='object unresolved'>Fd</code> <code class='argument'>file</code><b>)</b></code></p></dd>   </dl>   
1452:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>set_backend</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_backend</span>(</b><code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Set the backend used for the callbacks.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>The backend keeps a reference to this object only when it is in -  callback mode. So if this object hasn't got any active callbacks -  and it runs out of other references, it will still be destructed -  quickly (after closing, if necessary).</p> - <p> Also, this object does not keep a reference to the backend.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>query_backend</code>, <code>set_nonblocking</code>, <code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_fs_event_callback</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>set_blocking</b></span>   </dt>   <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_blocking</span>(</b><b>)</b></code></p></dd>
1502:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>set_blocking</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_blocking</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Sets this file to blocking operation.</p> - <p> This is the inverse operation of <code>set_nonblocking()</code>.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>set_nonblocking()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>set_nonblocking_keep_callbacks</b></span><br>   <span class='homogen--type'>Method</span>   <span class='homogen--name'><b>set_blocking_keep_callbacks</b></span><br>
1537:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>set_buffer</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_buffer</span>(</b><code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> - <code><code class='datatype'>void</code> <b><span class='method'>set_buffer</span>(</b><code class='datatype'>int</code> <code class='argument'>bufsize</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Set internal socket buffer.</p> - <p> This function sets the internal buffer size of a socket or stream.</p> - <p> The second argument allows you to set the read or write buffer by -  specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>It is not guaranteed that this function actually does anything, -  but it certainly helps to increase data transfer speed when it does.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>open_socket()</code>, <code>accept()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>set_buffer_mode</b></span>   </dt>   <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_buffer_mode</span>(</b><code class='object unresolved'>Stdio.IOBuffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>in</code>, <code class='object unresolved'>Stdio.IOBuffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>out</code><b>)</b></code></p></dd>
1764:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>set_close_on_exec</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_close_on_exec</span>(</b><code class='datatype'>bool</code> <code class='argument'>yes_no</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Marks the file as to be closed in spawned processes.</p> - <p> This function determines whether this file will be closed when -  calling exec().</p> - <p> Default is that the file WILL be closed on exec except for -  stdin, stdout and stderr.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>Process.create_process()</code>, <code>exec()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>set_id</b></span>   </dt>   <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_id</span>(</b><code class='datatype'>mixed</code> <code class='argument'>id</code><b>)</b></code></p></dd>
1802:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>set_keepalive</b></span> - </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>set_keepalive</span>(</b><code class='datatype'>bool</code> <code class='argument'>on_off</code><b>)</b></code></p></dd> - </dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>set_nonblocking</b></span>   </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Sets this file to nonblocking operation.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Nonblocking operation is not supported on all Stdio.File objects. -  Notably it is not guaranteed to be supported on objects returned -  by <code>pipe()</code> unless <code>PROP_NONBLOCK</code> was specified in the call -  to <code>pipe()</code>.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>set_blocking()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>set_nonblocking</b></span> - </dt> +    <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><code class='object unresolved'>read_callback_t</code> <code class='argument'>read_callback</code>, <code class='object unresolved'>write_callback_t</code> <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><code class='object unresolved'>read_callback_t</code> <code class='argument'>read_callback</code>, <code class='object unresolved'>write_callback_t</code> <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_callback</code><b>)</b></code><br>   <code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><b>)</b></code></p></dd>
1867:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>setxattr</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>setxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>flags</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Set the attribute <code>attr</code> to the value <code>value</code>.</p> - <p> The flags parameter can be used to refine the semantics of the operation. </p> - <p> <code>Stdio.XATTR_CREATE</code> specifies a pure create, which -  fails if the named attribute exists already. </p> - <p> <code>Stdio.XATTR_REPLACE</code> specifies a pure replace operation, which -  fails if the named attribute does not already exist.</p> - <p> By default (no flags), the extended attribute will be created if need be, -  or will simply replace the value if the attribute exists.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>1 if successful, 0 otherwise, setting errno.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>stat</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stat</code> <b><span class='method'>stat</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Get status for an open file.</p> - <p> This function returns the same information as the function -  <code>file_stat()</code>, but for the file it is called in. If file is not -  an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned -  if file is a pipe or socket.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>See <code>file_stat()</code> for a description of the return value.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Prior to Pike 7.1 this function returned an array(int).</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>file_stat()</code>, <code>statat()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>statat</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stat</code> <b><span class='method'>statat</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>Get status for a file relative an open directory.</p> - <p> This function returns the same information as the function -  <code>file_stat()</code>, but relative to the file it is called in. If file is not -  an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned -  if file is a pipe or socket.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>See <code>file_stat()</code> for a description of the return value.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Not available on all architectures, or in Pike 7.6 and earlier.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>file_stat()</code>, <code>stat()</code>, <code>openat()</code>, <code>unlinkat()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>sync</b></span> - </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>sync</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Flush buffers to disk.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns <code class='expr'>0</code> (zero) and sets errno on failure.</p> - <p> Returns <code class='expr'>1</code> on success.</p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>take_fd</b></span> - </dt> - <dd><p><code><code class='datatype'>void</code> <b><span class='method'>take_fd</span>(</b><code class='datatype'>int</code> <code class='argument'>fd</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Rehooks the given file descriptor number to be associated with -  this object. As opposed to using <code>open</code> with a file descriptor -  number, it will be closed by this object upon destruct or when -  <code>close</code> is called.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>release_fd()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> +    <span class='homogen--name'><b>tcgetattr</b></span><br>   <span class='homogen--type'>Method</span>   <span class='homogen--name'><b>tcsetattr</b></span><br>
2041:      <hr />   <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>tell</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>tell</span>(</b><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Returns the current offset in the file.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>seek()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>truncate</b></span> - </dt> - <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>truncate</span>(</b><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>Truncate a file.</p> - <p> Truncates the file to the specified length <code>length</code>.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>open()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>trylock</b></span> - </dt> - <dd><p><code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>trylock</span>(</b><b>)</b></code><br> - <code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>trylock</span>(</b><code class='datatype'>bool</code> <code class='argument'>is_recursive</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Attempts to place a file lock on this file.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>lock()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>unlinkat</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>unlinkat</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 relative to an open file.</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>openat()</code>, <code>statat()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>write</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>data</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Write data to a file or a stream.</p> - <p> If there are any file descriptors that have been queued for sending -  (with <code>send_fd()</code>), they will be sent.</p> - </dd> - <dt class='head--doc'><span id='p-data'></span>Parameter <code class='parameter'>data</code></dt> - <dd></dd><dd class='body--doc'><p>Data to write.</p> - <p> If <code>data</code> is an array of strings, they are written in sequence.</p> - </dd> - <dt class='head--doc'><span id='p-format'></span>Parameter <code class='parameter'>format</code></dt> - <dd></dd> - <dt class='head--doc'><span id='p-extras'></span>Parameter <code class='parameter'>extras</code></dt> - <dd></dd><dd class='body--doc'><p>If more than one argument is given, <code>sprintf()</code> is used to format -  them using <code>format</code>. If <code>format</code> is an array, the strings in it -  are concatenated and the result is used as format string.</p> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><p>Writes <code>data</code> and returns the number of bytes that were -  actually written.</p> - <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td><p>The number of bytes successfully written to the OS buffers.</p> - <p> This can be less than the size of the given data if eg:</p> - <ul> - <li><p>Some data was written successfully and then something went -  wrong.</p> - <p> If only some data was written due to an error and that error -  persists, then a later call to <code>write()</code> will fail and return -  <code class='expr'>-1</code>.</p> - </li><li><p>Nonblocking mode is used and not all data could be written -  without blocking.</p> - </li></ul> - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td><p>No bytes were written. This may be due to</p> - <ul> - <li><p><code>data</code> or the formatted data being the empty string.</p> - </li><li><p>Nonblocking mode is used and no data could be written -  without blocking.</p> - </li></ul> - </td></tr> - <tr><td><code><code class='key'>-1</code></code></td><td><p>Something went wrong and no bytes were written.</p> - </td></tr> - </table><p>If everything went fine, a call to <code>errno()</code> directly afterwards -  returns zero.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Writing of wide strings is not supported. You have to encode the -  data somehow, e.g. with <code>string_to_utf8</code> or with one of the -  charsets supported by <code>Charset.encoder</code>.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code>, <code>send_fd()</code></p> - </dd></dl> -  -  - <hr /> - <dl class='group--doc'> +    <dt class='head--type'><span class='homogen--type'>Typedef</span>   <span class='homogen--name'><b>write_callback_t</b></span>   </dt>
2184:   <p> The IOBuffer version is used when an IOBuffer has been enabled    for reading, add data to that buffer to send it.</p>   </dd></dl> -  -  - <hr /> - <dl class='group--doc'> - <dt class='head--type'><span class='homogen--type'>Method</span> - <span class='homogen--name'><b>write_oob</b></span> - </dt> - <dd><p><code><code class='datatype'>int</code> <b><span class='method'>write_oob</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code><br> - <code><code class='datatype'>int</code> <b><span class='method'>write_oob</span>(</b><code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code></p></dd> -  - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Write out-of-band data to a stream.</p> - <p> Writes out-of-band data to a stream and returns how many bytes -  that were actually written. It can be less than the size of the -  given data if some data was written successfully and then -  something went wrong.</p> - <p> -1 is returned if something went wrong and no bytes were written. -  If only some data was written due to an error and that error -  persists, then a later call to <code>write_oob()</code> fails and returns -  -1.</p> - <p> If everything went fine, a call to <code>errno()</code> directly afterwards -  returns zero.</p> - <p> If more than one argument is given, <code>sprintf()</code> is used to format -  them.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Out-of-band data was not supported in Pike 0.5 and earlier, and -  not in Pike 0.6 through 7.4 if they were compiled with the -  option <tt>'--without-oob'</tt>.</p> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>It is not guaranteed that all out-of-band data sent from the -  other end is received. Most streams only allow for a single byte -  of out-of-band data at a time. Some streams sends the rest of -  the data as ordinary data.</p> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><p><code>read_oob()</code>, <code>write()</code></p> - </dd></dl> +    </dd></dl><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>
6024:   <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Variable</span> + <span class='homogen--name'><b>_errno</b></span> + </dt> + <dd><p><code><code class='modifier'>protected</code> <code class='datatype'>int(0..)</code> Stdio.Fd.<b><span class='variable'>_errno</span></b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Variable containing the internal value returned by <code>errno()</code>.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>errno()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Variable</span>   <span class='homogen--name'><b>_fd</b></span>   </dt>   <dd><p><code><code class='object unresolved'>Fd</code> Stdio.Fd.<b><span class='variable'>_fd</span></b></code></p></dd>
6035:      <hr />   <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Variable</span> + <span class='homogen--name'><b>_read_callback</b></span><br> + <span class='homogen--type'>Variable</span> + <span class='homogen--name'><b>_write_callback</b></span><br> + <span class='homogen--type'>Variable</span> + <span class='homogen--name'><b>_read_oob_callback</b></span><br> + <span class='homogen--type'>Variable</span> + <span class='homogen--name'><b>_write_oob_callback</b></span><br> + <span class='homogen--type'>Variable</span> + <span class='homogen--name'><b>_fs_event_callback</b></span><br> + </dt> + <dd><p><code><code class='datatype'>mixed</code> Stdio.Fd.<b><span class='variable'>_read_callback</span></b></code><br> + <code><code class='datatype'>mixed</code> Stdio.Fd.<b><span class='variable'>_write_callback</span></b></code><br> + <code><code class='datatype'>mixed</code> Stdio.Fd.<b><span class='variable'>_read_oob_callback</span></b></code><br> + <code><code class='datatype'>mixed</code> Stdio.Fd.<b><span class='variable'>_write_oob_callback</span></b></code><br> + <code><code class='datatype'>mixed</code> Stdio.Fd.<b><span class='variable'>_fs_event_callback</span></b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Callback functions installed by <code>Stdio.File()-&gt;set_callbacks()</code> et al.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> -  + <span class='homogen--name'><b>`&lt;&lt;</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stdio.File</code> res = <code class='class'>Stdio.Fd()</code>&#32;&lt;&lt;&#32;<code class='class'>data</code></code><br> + <code><code class='object unresolved'>Stdio.File</code> res = <code class='class'>Stdio.Fd()</code>&#32;&lt;&lt;&#32;<code class='class'>data</code></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Write some data to a file.</p> + <p> If <code>data</code> is not a string, it is casted to string, and then +  written to the file.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Throws an error if not all data could be written.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>write()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>close</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>close</span>(</b><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>close</span>(</b><code class='datatype'>string</code> <code class='argument'>direction</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Close a file or stream.</p> + <p> If direction is not specified, both the read and the write +  direction is closed. Otherwise only the directions specified is +  closed.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Nonzero is returned if the file or stream wasn't open in the +  specified direction, zero otherwise.</p> + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'><p>An exception is thrown if an I/O error occurs.</p> + <p> The default behaviour for sockets is typically to flush buffered +  data in the background, but this can be changed with <code>linger()</code>.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p><code>close()</code> has no effect if this file object has been associated +  with an already opened file, i.e. if <code>open()</code> was given an +  integer as the first argument.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>linger()</code>, <code>open()</code>, <code>open_socket()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>connect</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code><b>)</b></code><br> + <code><code class='datatype'>bool</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code> <code class='argument'>src_port</code><b>)</b></code><br> + <code><code class='datatype'>string(8bit)</code>|<code class='datatype'>int(0..0)</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_port</code>, <code class='datatype'>string(8bit)</code> <code class='argument'>data</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Open a TCP/IP connection to the specified destination.</p> + <p> In nonblocking mode, success is indicated with the write-callback, +  and failure with the close-callback or the read_oob-callback.</p> + <p> If the <code>data</code> argument is included the socket will use +  TCP_FAST_OPEN if available, if not the data will <i>not be +  sent</i>. In the data case the function either returns the data +  that has not been sent (only one packet can be sent with this +  option) or 0 if the connection failed immediately.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns <code class='expr'>1</code> or the remaining <code class='expr'>data</code> on success, and +  <code class='expr'>0</code> on failure.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set +  to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded +  as a connection failure.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>connect_unix</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>connect_unix</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Open a UNIX domain socket connection to the specified destination.</p> + </dd> + <dt class='head--doc'><span id='p-filename'></span>Parameter <code class='parameter'>filename</code></dt> + <dd></dd><dd class='body--doc'><p>Filename to create.</p> + <p> In nonblocking mode, success is indicated with the write-callback, +  and failure with the close-callback or the read_oob-callback.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set +  to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded +  as a connection failure.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p><code>path</code> had a quite restrictive length limit (~100 characters) +  prior to Pike 7.8.334.</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.Fd</span> <span class='class'>Stdio.Fd</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code><b>)</b></code><br> + <code><span class='object'>Stdio.Fd</span> <span class='class'>Stdio.Fd</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> + <code><span class='object'>Stdio.Fd</span> <span class='class'>Stdio.Fd</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code><b>)</b></code><br> + <code><span class='object'>Stdio.Fd</span> <span class='class'>Stdio.Fd</span><b>(</b><code class='datatype'>int</code> <code class='argument'>fd</code><b>)</b></code><br> + <code><span class='object'>Stdio.Fd</span> <span class='class'>Stdio.Fd</span><b>(</b><code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>See <code>open()</code>.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>open()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>dup</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stdio.Fd</code> <b><span class='method'>dup</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Duplicate the file.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>dup2()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>dup2</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>dup2</span>(</b><code class='object unresolved'>Stdio.File</code> <code class='argument'>to</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Duplicate a file over another.</p> + <p> This function works similarly to <code>assign()</code>, but instead of making +  the argument a reference to the same file, it creates a new file +  with the same properties and places it in the argument.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success and <code class='expr'>0</code> (zero) on failure.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>In Pike 7.7 and later <code>to</code> need not be open, in which +  case a new fd is allocated.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Note also that <code>to</code> is also assigned to the same backend (if any) +  as this object.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>assign()</code>, <code>dup()</code></p> + </dd></dl> +  +  + <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>Return the errno for the latest failed file operation.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span>   <span class='homogen--name'><b>fd_factory</b></span>   </dt>   <dd><p><code><code class='object unresolved'>Fd</code> <b><span class='method'>fd_factory</span>(</b><b>)</b></code></p></dd>
6053:   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>Stdio.Port()-&gt;fd_factory()</code>, <code>openat()</code>, <code>pipe()</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'>string</code>|<code class='datatype'>void</code> <code class='argument'>path</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Get directory contents relative to an open directory.</p> + </dd> + <dt class='head--doc'><span id='p-path'></span>Parameter <code class='parameter'>path</code></dt> + <dd></dd><dd class='body--doc'><p>Path relative to the open directory. Defaults to the +  directory itself.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns an array of filenames.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Not available on all architectures, or in Pike 7.6 and earlier.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>predef::get_dir()</code>, <code>statat()</code>, <code>openat()</code>, <code>unlinkat()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>getxattr</b></span> + </dt> + <dd><p><code><code class='datatype'>string</code> <b><span class='method'>getxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Return the value of a specified attribute, or 0 if it does not exist</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>grantpt</b></span> + </dt> + <dd><p><code><code class='datatype'>string</code> <b><span class='method'>grantpt</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>If this file has been created by calling <code>openpt()</code>, return the +  filename of the associated pts-file. This function should only be +  called once.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns the filename of the corresponding pts.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>This function is only available on some platforms.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>is_open</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>is_open</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Returns true if the file is open.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>If the file is a socket that has been closed from the remote side, +  this function might still return true.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Most methods can't be called for a file descriptor that isn't +  open. Notable exceptions <code>errno</code>, <code>mode</code>, and the set and query +  functions for callbacks and backend.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>linger</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>linger</span>(</b><code class='datatype'>int(-1..65535)</code>|<code class='datatype'>void</code> <code class='argument'>seconds</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Set the socket linger behaviour on <code>close()</code>.</p> + </dd> + <dt class='head--doc'><span id='p-seconds'></span>Parameter <code class='parameter'>seconds</code></dt> + <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>-1</code></code></td><td><p>Reset to default behaviour. This typically means that +  <code>close()</code> will return immediately, but any buffered +  data will still be sent if possible.</p> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td><p>Terminate the connection immediately on <code>close()</code>, +  and discard any buffered data.</p> + </td></tr> + <tr><td><code><code class='key'>(1..65535)</code></code></td><td><p>Have <code>close()</code> wait for at most <code>seconds</code> seconds +  for any buffered data to be sent after which the +  connection is terminated.</p> + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>This operation is only valid on sockets.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>This function was not available in Pike 7.8.775 and earlier.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>close()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>listxattr</b></span> + </dt> + <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>listxattr</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Return an array of all extended attributes set on the file</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>lock</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>lock</span>(</b><b>)</b></code><br> + <code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>lock</span>(</b><code class='datatype'>bool</code> <code class='argument'>is_recursive</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Makes an exclusive file lock on this file.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>trylock()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>mode</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>mode</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Returns the open mode and capabilities for the file.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns an <code>`|()</code> of the following flags:</p> + <table class='box'><tr><td><code><code class='key'>0x1000</code></code></td><td><p><code>FILE_READ</code></p> + </td></tr> + <tr><td><code><code class='key'>0x2000</code></code></td><td><p><code>FILE_WRITE</code></p> + </td></tr> + <tr><td><code><code class='key'>0x4000</code></code></td><td><p><code>FILE_APPEND</code></p> + </td></tr> + <tr><td><code><code class='key'>0x8000</code></code></td><td><p><code>FILE_CREATE</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0100</code></code></td><td><p><code>FILE_TRUNC</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0200</code></code></td><td><p><code>FILE_EXCLUSIVE</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0400</code></code></td><td><p><code>FILE_NONBLOCKING</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0040</code></code></td><td><p><code>PROP_SEND_FD</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0010</code></code></td><td><p><code>PROP_BIDIRECTIONAL</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0008</code></code></td><td><p><code>PROP_BUFFERED</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0004</code></code></td><td><p><code>PROP_SHUTDOWN</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0002</code></code></td><td><p><code>PROP_NONBLOCK</code></p> + </td></tr> + <tr><td><code><code class='key'>0x0001</code></code></td><td><p><code>PROP_IPC</code></p> + </td></tr> + </table> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>In some versions of Pike 7.7 and 7.8 the <tt>PROP_</tt> flags were +  filtered from the result.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>open()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>open</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Open a file, or use an existing fd.</p> + <p> If <code>filename</code> is given, attempt to open the named file. If <code>fd</code> +  is given instead, it should be the file descriptor for an already +  opened file, which will then be used by this object.</p> + <p> <code>mode</code> describes how the file is opened. It's a case-insensitive +  string consisting of one or more of the following letters:</p> + <dl class='group--doc'><dt>"r"</dt> + <dd><p>Open for reading.</p> + </dd> + <dt>"w"</dt> + <dd><p>Open for writing.</p> + </dd> + <dt>"a"</dt> + <dd><p>Append new data to the end.</p> + </dd> + <dt>"c"</dt> + <dd><p>Create the file if it doesn't exist already.</p> + </dd> + <dt>"t"</dt> + <dd><p>Truncate the file to zero length if it already contains data. +  Use only together with <code class='expr'>"w"</code>.</p> + </dd> + <dt>"x"</dt> + <dd><p>Open exclusively - the open fails if the file already exists. +  Use only together with <code class='expr'>"c"</code>. Note that it's not safe to +  assume that this is atomic on some systems.</p> + </dd> + </dl><p><code>access</code> specifies the permissions to use if a new file is +  created. It is a UNIX style permission bitfield:</p> + <dl class='group--doc'><dt>0400</dt> + <dd><p>User has read permission.</p> + </dd> + <dt>0200</dt> + <dd><p>User has write permission.</p> + </dd> + <dt>0100</dt> + <dd><p>User has execute permission.</p> + </dd> + <dt>0040</dt> + <dd><p>Group has read permission.</p> + </dd> + <dt>0020</dt> + <dd><p>Group has write permission.</p> + </dd> + <dt>0010</dt> + <dd><p>Group has execute permission.</p> + </dd> + <dt>0004</dt> + <dd><p>Others have read permission.</p> + </dd> + <dt>0002</dt> + <dd><p>Others have write permission.</p> + </dd> + <dt>0001</dt> + <dd><p>Others have execute permission.</p> + </dd> + </dl><p>It's system dependent on which of these bits that are actually +  heeded. If <code>access</code> is not specified, it defaults to +  <code class='expr'>00666</code>, but note that on UNIX systems it's masked with the +  process umask before use.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns nonzero on success and <code class='expr'>0</code> (zero) on failure. If +  there is a failure then <code>errno</code> returns the error code.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>close()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>open_socket</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>open_socket</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>addr</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code><b>)</b></code></p></dd> + </dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>openat</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>openat</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> + <code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>openat</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Open a file relative to an opened directory.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns a new file object on success, and <code class='expr'>0</code> (zero) on failure.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Not available on all architectures, or in Pike 7.6 and earlier.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>open()</code>, <code>statat()</code>, <code>unlinkat()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>openpt</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>openpt</span>(</b><code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Open the master end of a pseudo-terminal pair.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>grantpt()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>peek</b></span> + </dt> + <dd><p><code><code class='datatype'>int(-1..1)</code> <b><span class='method'>peek</span>(</b><b>)</b></code><br> + <code><code class='datatype'>int(-1..1)</code> <b><span class='method'>peek</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code><b>)</b></code><br> + <code><code class='datatype'>int(-1..1)</code> <b><span class='method'>peek</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>, <code class='datatype'>int</code> <code class='argument'>not_eof</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Check if there is data available to read, +  or wait some time for available data to read.</p> + <p> More specifically, a later call to <code>read()</code> will return +  immediately, either due to data being present, or due to +  some error (eg if a socket has been closed).</p> + </dd> + <dt class='head--doc'><span id='p-timeout'></span>Parameter <code class='parameter'>timeout</code></dt> + <dd></dd><dd class='body--doc'><p>Timeout in seconds.</p> + </dd> + <dt class='head--doc'><span id='p-not_eof'></span>Parameter <code class='parameter'>not_eof</code></dt> + <dd></dd><dd class='body--doc'><p>Flag for specifying handling of end of file. +  The following values are currently defined:</p> + <table class='box'><tr><td><code><code class='key'>0</code></code></td><td><p>Traditional (and default) behaviour. Return <code class='expr'>1</code> +  at EOF.</p> + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td><p>Regard EOF as an error. Return <code class='expr'>-1</code> and set <code>errno()</code> +  to return <code class='expr'>EPIPE</code> at EOF.</p> + </td></tr> + </table> + </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>There is data available to <code>read()</code>, or <code>not_eof</code> is +  <code class='expr'>0</code> (zero) and we're at EOF. A later call to +  <code>read()</code> will not block.</p> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td><p>There is no data available (ie timeout).</p> + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td><p>Error condition. The error code returned by <code>errno()</code> +  has been updated.</p> + </td></tr> + </table> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>errno()</code>, <code>read()</code></p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>The function may be interrupted prematurely +  of the timeout (due to signals); +  check the timing manually if this is imporant.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>The <code>not_eof</code> parameter was added in Pike 7.7.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>This function was not available on NT in Pike 7.6 and earlier.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>pipe</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>pipe</span>(</b><b>)</b></code><br> + <code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>pipe</span>(</b><code class='datatype'>int</code> <code class='argument'>flags</code><b>)</b></code></p></dd> + </dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>proxy</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>proxy</span>(</b><code class='object unresolved'>Stdio.File</code> <code class='argument'>from</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Starts a thread that asynchronously copies data from <code>from</code> +  to this file.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>Stdio.sendfile()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>query_address</b></span> + </dt> + <dd><p><code><code class='datatype'>string</code> <b><span class='method'>query_address</span>(</b><b>)</b></code><br> + <code><code class='datatype'>string</code> <b><span class='method'>query_address</span>(</b><code class='datatype'>bool</code> <code class='argument'>local</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Get address and port of a socket end-point.</p> + </dd> + <dt class='head--doc'><span id='p-local'></span>Parameter <code class='parameter'>local</code></dt> + <dd></dd><dd class='body--doc'><p>If the argument <code>local</code> is not specified, or is <code class='expr'>0</code> +  (zero), the remote end-point is returned. Otherwise, if <code>local</code> +  is <code class='expr'>1</code>, the local end-point is returned.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>This function returns the address and port of a socket end-point +  on the form <code class='expr'>"x.x.x.x&nbsp;port"</code> (IPv4) or +  <code class='expr'>"x:x:x:x:x:x:x:x&nbsp;port"</code> (IPv6). IPv6 addresses +  may use the contracted syntax.</p> + <p> If this file is not a socket, is not connected, or some other +  error occurs, <code class='expr'>0</code> (zero) is returned and <code>errno()</code> will +  return the error code.</p> + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'><p>An error is thrown if the socket (or file) isn't open.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>connect()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>query_backend</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Pike.Backend</code> <b><span class='method'>query_backend</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Return the backend used for the callbacks.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>set_backend</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>query_fd</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>query_fd</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Returns the file descriptor number associated with this object.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>read</b></span> + </dt> + <dd><p><code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><b>)</b></code><br> + <code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code><b>)</b></code><br> + <code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Read data from a file or a stream.</p> + <p> Attempts to read <code>len</code> bytes from the file, and return it as a +  string. Less than <code>len</code> bytes can be returned if:</p> + <ul> + <li><p>end-of-file is encountered for a normal file, or</p> + </li><li><p>it's a stream that has been closed from the other end, or</p> + </li><li><p>it's a stream in nonblocking mode, or</p> + </li><li><p>it's a stream and <code>not_all</code> is set, or</p> + </li><li><p><code>not_all</code> isn't set and an error occurred (see below).</p> + </li></ul><p>If <code>not_all</code> is nonzero, <code>read()</code> does not try its best to read +  as many bytes as you have asked for, but merely returns as much as +  the system read function returns. This is mainly useful with +  stream devices which can return exactly one row or packet at a +  time. If <code>not_all</code> is used in blocking mode, <code>read()</code> only +  blocks if there's no data at all available.</p> + <p> If something goes wrong and <code>not_all</code> is set, zero is returned. +  If something goes wrong and <code>not_all</code> is zero or left out, then +  either zero or a string shorter than <code>len</code> is returned. If the +  problem persists then a later call to <code>read()</code> fails and returns +  zero, however.</p> + <p> If everything went fine, a call to <code>errno()</code> directly afterwards +  returns zero. That includes an end due to end-of-file or remote +  close.</p> + <p> If no arguments are given, <code>read()</code> reads to the end of the file +  or stream.</p> + <p> If any file descriptors have been sent by the other side of the +  stream, <code>receive_fd()</code> will be called once for every sent file +  descriptor.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It's not necessary to set <code>not_all</code> to avoid blocking reading +  when nonblocking mode is used.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>When at the end of a file or stream, repeated calls to <code>read()</code> +  will return the empty string since it's not considered an error. +  The empty string is never returned in other cases, unless nonblocking +  mode is used or <code>len</code> is zero.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>read_oob()</code>, <code>write()</code>, <code>receive_fd()</code>, <code>send_fd()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>read_oob</b></span> + </dt> + <dd><p><code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><b>)</b></code><br> + <code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code><b>)</b></code><br> + <code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Attempts to read <code>len</code> bytes of out-of-band data from the stream, +  and returns it as a string. Less than <code>len</code> bytes can be returned +  if:</p> + <ul> + <li><p>the stream has been closed from the other end, or</p> + </li><li><p>nonblocking mode is used, or</p> + </li><li><p><code>not_all</code> is set, or</p> + </li><li><p><code>not_all</code> isn't set and an error occurred (see below).</p> + </li></ul><p>If <code>not_all</code> is nonzero, <code>read_oob()</code> only returns as many bytes +  of out-of-band data as are currently available.</p> + <p> If something goes wrong and <code>not_all</code> is set, zero is returned. +  If something goes wrong and <code>not_all</code> is zero or left out, then +  either zero or a string shorter than <code>len</code> is returned. If the +  problem persists then a later call to <code>read_oob()</code> fails and +  returns zero, however.</p> + <p> If everything went fine, a call to <code>errno()</code> directly afterwards +  returns zero. That includes an end due to remote close.</p> + <p> If no arguments are given, <code>read_oob()</code> reads to the end of the +  stream.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Out-of-band data was not supported in Pike 0.5 and earlier, and +  not in Pike 0.6 through 7.4 if they were compiled with the +  option <tt>'--without-oob'</tt>.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It is not guaranteed that all out-of-band data sent from the +  other end is received. Most streams only allow for a single byte +  of out-of-band data at a time.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It's not necessary to set <code>not_all</code> to avoid blocking reading +  when nonblocking mode is used.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>When at the end of a file or stream, repeated calls to <code>read()</code> +  returns the empty string since it's not considered an error. The +  empty string is never returned in other cases, unless nonblocking +  mode is used or <code>len</code> is zero.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>receive_fd</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>receive_fd</span>(</b><code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Remote file descriptor reception handler.</p> + </dd> + <dt class='head--doc'><span id='p-fd'></span>Parameter <code class='parameter'>fd</code></dt> + <dd></dd><dd class='body--doc'><p>File descriptor received from the remote end of a <code>pipe()</code>. +  This object has been created by <code>fd_factory()</code>.</p> + <p> This function is called from <code>read()</code> when a remote file +  descriptor has been received over a <code>PROP_SEND_FD</code> +  capable <code>pipe()</code>.</p> + <p> The default implementation is just a prototype.</p> + <p> Overload this function to enable reception of +  remote file descriptors.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>The capability of sending and receiving remote file +  descriptors is only available on some operating systems. +  This capability is indicated by the precence of <code>__HAVE_SEND_FD__</code>.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>send_fd()</code>, <code>read()</code>, <code>fd_factory()</code>, <code>__HAVE_SEND_FD__</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>release_fd</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>release_fd</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Returns the file descriptor number associated with this object, in +  addition to releasing it so that this object behaves as if closed. +  Other settings like callbacks and backend remain intact. +  <code>take_fd</code> can later be used to reinstate the file descriptor so +  that the state is restored.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>query_fd()</code>, <code>take_fd()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>removexattr</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>removexattr</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Remove the specified extended attribute.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>seek</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>seek</span>(</b><code class='datatype'>int</code> <code class='argument'>offset</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>seek</span>(</b><code class='datatype'>int</code> <code class='argument'>offset</code>, <code class='datatype'>string</code> <code class='argument'>whence</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>The seek() function repositions the offset of the open file +  associated with the file descriptor fd to the argument <code>offset</code> +  according to the directive <code>whence</code> as follows:</p> + <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_SET</code></code></td><td><p>The offset is set to <code>offset</code> bytes.</p> + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_CUR</code></code></td><td><p>The offset is set to its current location plus <code>offset</code> bytes.</p> + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_END</code></code></td><td><p>The offset is set to the size of the file plus <code>offset</code> bytes.</p> + </td></tr> + </table><p>If <code>whence</code> is not specified it is SEEK_SET if <code>offset</code> is +  positive, and if <code>offset</code> is negative SEEK_END.</p> + <p> The seek() function on most operating systems allows the file +  offset to be set beyond the end of the file (but this does not +  change the size of the file). If data is later written at this +  point, subsequent reads of the data in the gap (a "hole") return +  null bytes ('\0') until data is actually written into the gap.</p> + <p> Seeking file data and holes</p> + <p> Stdio.SEEK_DATA and Stdio.SEEK_HOLE are nonstandard extensions +  present in Linux, Solaris, FreeBSD, and DragonFly BSD; they are +  proposed for inclusion in the next POSIX revision.</p> + <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_DATA</code></code></td><td><p>Adjust the file offset to the next location in the file greater +  than or equal to offset containing data. If offset points to +  data, then the file offset is set to offset.</p> + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_HOLE</code></code></td><td><p>Adjust the file offset to the next hole in the file greater than +  or equal to offset. If offset points into the middle of a hole, +  then the file offset is set to offset. If there is no hole past +  offset, then the file offset is adjusted to the end of the file +  (i.e., there is an implicit hole at the end of any file).</p> + </td></tr> + </table><p>In both of the above cases, seek() fails if offset points past the +  end of the file.</p> + <p> These operations allow applications to map holes in a sparsely +  allocated file. This can be useful for applications such as file +  backup tools, which can save space when creating backups and +  preserve holes, if they have a mechanism for discovering holes.</p> + <p> For the purposes of these operations, a hole is a sequence of +  zeros that (normally) has not been allocated in the underlying +  file storage. However, a filesystem is not obliged to report +  holes, so these operations are not a guaranteed mechanism for +  mapping the storage space actually allocated to a file. +  (Furthermore, a sequence of zeros that actually has been written +  to the underlying storage may or may not be reported as a hole.)</p> + <p> In the simplest implementation, a filesystem can support the +  operations by making SEEK_HOLE always return the offset of the end +  of the file, and making SEEK_DATA always return offset (i.e., even +  if the location referred to by offset is a hole, it can be +  considered to consist of data that is a sequence of zeros).</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Upon successful completion, seek() returns the resulting offset +  location as measured in bytes from the beginning of the file. On +  error, the value (off_t) -1 is returned and <code>errno</code> is set to +  indicate the error.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>tell()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>send_fd</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>send_fd</span>(</b><code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Queues an open file descriptor for sending to the other end of a stream.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>The actual sending is performed at the next successful call +  to <code>write()</code>, this is due to limitations in the system calls. +  This means that it isn't possible to send a file descriptor +  without also sending some in-band data.</p> + <p> This operation is only supported on <code>pipe()</code>'s created with +  <code>PROP_SEND_FD</code>.</p> + <p> This function is not available on all operating systems, check +  for <code>__HAVE_SEND_FD__</code>.</p> + <p> The queue is emptied on successful <code>write()</code> and when the +  write direction is <code>close()</code>'d.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>receive_fd()</code>, <code>write()</code>, <code>pipe()</code>, <code>read()</code>, <code>__HAVE_SEND_FD__</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_backend</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_backend</span>(</b><code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Set the backend used for the callbacks.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>The backend keeps a reference to this object only when it is in +  callback mode. So if this object hasn't got any active callbacks +  and it runs out of other references, it will still be destructed +  quickly (after closing, if necessary).</p> + <p> Also, this object does not keep a reference to the backend.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>query_backend</code>, <code>set_nonblocking</code>, <code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_fs_event_callback</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_blocking</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_blocking</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Sets this file to blocking operation.</p> + <p> This is the inverse operation of <code>set_nonblocking()</code>.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>set_nonblocking()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_buffer</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_buffer</span>(</b><code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code><br> + <code><code class='datatype'>void</code> <b><span class='method'>set_buffer</span>(</b><code class='datatype'>int</code> <code class='argument'>bufsize</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Set internal socket buffer.</p> + <p> This function sets the internal buffer size of a socket or stream.</p> + <p> The second argument allows you to set the read or write buffer by +  specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It is not guaranteed that this function actually does anything, +  but it certainly helps to increase data transfer speed when it does.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>open_socket()</code>, <code>accept()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_close_on_exec</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_close_on_exec</span>(</b><code class='datatype'>bool</code> <code class='argument'>yes_no</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Marks the file as to be closed in spawned processes.</p> + <p> This function determines whether this file will be closed when +  calling exec().</p> + <p> Default is that the file WILL be closed on exec except for +  stdin, stdout and stderr.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>Process.create_process()</code>, <code>exec()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_keepalive</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>set_keepalive</span>(</b><code class='datatype'>bool</code> <code class='argument'>on_off</code><b>)</b></code></p></dd> + </dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>set_nonblocking</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Sets this file to nonblocking operation.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Nonblocking operation is not supported on all Stdio.File objects. +  Notably it is not guaranteed to be supported on objects returned +  by <code>pipe()</code> unless <code>PROP_NONBLOCK</code> was specified in the call +  to <code>pipe()</code>.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>set_blocking()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>setxattr</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>setxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>flags</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Set the attribute <code>attr</code> to the value <code>value</code>.</p> + <p> The flags parameter can be used to refine the semantics of the operation. </p> + <p> <code>Stdio.XATTR_CREATE</code> specifies a pure create, which +  fails if the named attribute exists already. </p> + <p> <code>Stdio.XATTR_REPLACE</code> specifies a pure replace operation, which +  fails if the named attribute does not already exist.</p> + <p> By default (no flags), the extended attribute will be created if need be, +  or will simply replace the value if the attribute exists.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>1 if successful, 0 otherwise, setting errno.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>stat</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stat</code> <b><span class='method'>stat</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Get status for an open file.</p> + <p> This function returns the same information as the function +  <code>file_stat()</code>, but for the file it is called in. If file is not +  an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned +  if file is a pipe or socket.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>See <code>file_stat()</code> for a description of the return value.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Prior to Pike 7.1 this function returned an array(int).</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>file_stat()</code>, <code>statat()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>statat</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stat</code> <b><span class='method'>statat</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>Get status for a file relative an open directory.</p> + <p> This function returns the same information as the function +  <code>file_stat()</code>, but relative to the file it is called in. If file is not +  an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned +  if file is a pipe or socket.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>See <code>file_stat()</code> for a description of the return value.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Not available on all architectures, or in Pike 7.6 and earlier.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>file_stat()</code>, <code>stat()</code>, <code>openat()</code>, <code>unlinkat()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>sync</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>sync</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Flush buffers to disk.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns <code class='expr'>0</code> (zero) and sets errno on failure.</p> + <p> Returns <code class='expr'>1</code> on success.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>take_fd</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>take_fd</span>(</b><code class='datatype'>int</code> <code class='argument'>fd</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Rehooks the given file descriptor number to be associated with +  this object. As opposed to using <code>open</code> with a file descriptor +  number, it will be closed by this object upon destruct or when +  <code>close</code> is called.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>release_fd()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>tell</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>tell</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Returns the current offset in the file.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>seek()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>truncate</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>truncate</span>(</b><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>Truncate a file.</p> + <p> Truncates the file to the specified length <code>length</code>.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>open()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>trylock</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>trylock</span>(</b><b>)</b></code><br> + <code><code class='object unresolved'>Stdio.FileLockKey</code> <b><span class='method'>trylock</span>(</b><code class='datatype'>bool</code> <code class='argument'>is_recursive</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Attempts to place a file lock on this file.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>lock()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>unlinkat</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>unlinkat</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 relative to an open file.</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>openat()</code>, <code>statat()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>write</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>data</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Write data to a file or a stream.</p> + <p> If there are any file descriptors that have been queued for sending +  (with <code>send_fd()</code>), they will be sent.</p> + </dd> + <dt class='head--doc'><span id='p-data'></span>Parameter <code class='parameter'>data</code></dt> + <dd></dd><dd class='body--doc'><p>Data to write.</p> + <p> If <code>data</code> is an array of strings, they are written in sequence.</p> + </dd> + <dt class='head--doc'><span id='p-format'></span>Parameter <code class='parameter'>format</code></dt> + <dd></dd> + <dt class='head--doc'><span id='p-extras'></span>Parameter <code class='parameter'>extras</code></dt> + <dd></dd><dd class='body--doc'><p>If more than one argument is given, <code>sprintf()</code> is used to format +  them using <code>format</code>. If <code>format</code> is an array, the strings in it +  are concatenated and the result is used as format string.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Writes <code>data</code> and returns the number of bytes that were +  actually written.</p> + <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td><p>The number of bytes successfully written to the OS buffers.</p> + <p> This can be less than the size of the given data if eg:</p> + <ul> + <li><p>Some data was written successfully and then something went +  wrong.</p> + <p> If only some data was written due to an error and that error +  persists, then a later call to <code>write()</code> will fail and return +  <code class='expr'>-1</code>.</p> + </li><li><p>Nonblocking mode is used and not all data could be written +  without blocking.</p> + </li></ul> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td><p>No bytes were written. This may be due to</p> + <ul> + <li><p><code>data</code> or the formatted data being the empty string.</p> + </li><li><p>Nonblocking mode is used and no data could be written +  without blocking.</p> + </li></ul> + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td><p>Something went wrong and no bytes were written.</p> + </td></tr> + </table><p>If everything went fine, a call to <code>errno()</code> directly afterwards +  returns zero.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Writing of wide strings is not supported. You have to encode the +  data somehow, e.g. with <code>string_to_utf8</code> or with one of the +  charsets supported by <code>Charset.encoder</code>.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code>, <code>send_fd()</code></p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>write_oob</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>write_oob</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code><br> + <code><code class='datatype'>int</code> <b><span class='method'>write_oob</span>(</b><code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Write out-of-band data to a stream.</p> + <p> Writes out-of-band data to a stream and returns how many bytes +  that were actually written. It can be less than the size of the +  given data if some data was written successfully and then +  something went wrong.</p> + <p> -1 is returned if something went wrong and no bytes were written. +  If only some data was written due to an error and that error +  persists, then a later call to <code>write_oob()</code> fails and returns +  -1.</p> + <p> If everything went fine, a call to <code>errno()</code> directly afterwards +  returns zero.</p> + <p> If more than one argument is given, <code>sprintf()</code> is used to format +  them.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>Out-of-band data was not supported in Pike 0.5 and earlier, and +  not in Pike 0.6 through 7.4 if they were compiled with the +  option <tt>'--without-oob'</tt>.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It is not guaranteed that all out-of-band data sent from the +  other end is received. Most streams only allow for a single byte +  of out-of-band data at a time. Some streams sends the rest of +  the data as ordinary data.</p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p><code>read_oob()</code>, <code>write()</code></p> + </dd></dl>   </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Fd_ref</b></h2>   </dt><dd><dl class='group--doc'>   <dt class='head--doc'>Description</dt>