Log of autodoc.git/traditional_manual/chapter

2019-01-24

2019-01-24 15:05:56 by Henrik Grubbström (Grubba) <grubba@grubba.org>

c3ab1f6e3446183b8f04ed20215e582bb01123e7 (2056 lines) (+2041/-15) ^{[

Show
| Annotate

]}
Branch: master

Documentation [Stdio.File]: Fixed some markup issues.

3405: <hr /> <dl class='group--doc'> <dt class='head--type'>Constant + IPPROTO_IP + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>IPPROTO_IP</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set IP-level options + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + IPPROTO_TCP + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>IPPROTO_TCP</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set TCP-level options + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + IP_TOS + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>IP_TOS</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set Type Of Service + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_ATTRIB + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_ATTRIB</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_DELETE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_DELETE</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_EXTEND + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_EXTEND</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_LINK + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_LINK</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_RENAME + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_RENAME</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_REVOKE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_REVOKE</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + NOTE_WRITE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_WRITE</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BIDIRECTIONAL + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BIDIRECTIONAL</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file is bi-directional. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BUFFERED + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BUFFERED</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file is buffered (usually 4KB). + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_IPC + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_IPC</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file may be used for inter process communication. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_NONBLOCK + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_NONBLOCK</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file supports nonblocking I/O. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_REVERSE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_REVERSE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Request reversed operation. + Used as argument to <code>Stdio.File()->pipe()</code>, when + <code>PROP_BIDIRECTIONAL</code> hasn't been specified, to + request the direction of the resulting pipe to + reversed. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SEND_FD + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SEND_FD</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The <code>Stdio.File</code> object might support the <code>Stdio.File()->send_fd()</code> + operation. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->pipe()</code>, <code>Stdio.File()->send_fd()</code>, + <code>Stdio.File()->receive_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SHUTDOWN + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SHUTDOWN</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The file supports shutting down transmission in either + direction. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->close()</code>, <code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + SOL_SOCKET + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>SOL_SOCKET</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set socket-level options + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + SO_KEEPALIVE + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>SO_KEEPALIVE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to control TCP/IP keep-alive packets. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + TCP_NODELAY + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>TCP_NODELAY</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used in <code>File.setsockopt()</code> to control Nagle's Algorithm. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant TCSADRAIN </dt> <dd><code><code class='datatype'>constant</code> <code class='datatype'>string</code> Stdio.<code class='constant'>TCSADRAIN</code></code></dd>
3444: <hr /> <dl class='group--doc'> + <dt class='head--type'>Constant + XATTR_CREATE + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>XATTR_CREATE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used by <code>setxattr</code> function and method to signify a pure + create, which will fail if the attribute already exists. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + XATTR_REPLACE + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>XATTR_REPLACE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Used by <code>setxattr</code> function and method to signify a replace, + which will fail the the attribute does not already exists. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __HAVE_OOB__ + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>__HAVE_OOB__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Exists and has the value 1 if OOB operations are available. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In Pike 7.5 and later OOB operations are always present. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __HAVE_SEND_FD__ + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>__HAVE_SEND_FD__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Support for sending of file descriptors over + <code>Stdio.File()->pipe()</code> objects with <code>PROP_SEND_FD</code> + capability is supported. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File()->send_fd()</code>, <code>Stdio.File()->receive_fd()</code>, + <code>Stdio.File()->read()</code>, <code>Stdio.File()->write()</code>, + <code>Stdio.File()->pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __OOB__ + </dt> + <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>__OOB__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Implementation level of nonblocking I/O OOB support. + <table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Nonblocking OOB support is not supported. + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td>Nonblocking OOB works a little. + </td></tr> + <tr><td><code><code class='key'>2</code></code></td><td>Nonblocking OOB almost works. + </td></tr> + <tr><td><code><code class='key'>3</code></code></td><td>Nonblocking OOB works as intended. + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td>Unknown level of nonblocking OOB support. + </td></tr> + </table>This constant only exists when OOB operations are + available, i.e. when <code>__HAVE_OOB__</code> is 1. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method append_file </dt>
3638: <hr /> <dl class='group--doc'> + <dt class='head--type'>Method + get_all_active_fd + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_all_active_fd()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the id of all the active file descriptors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + gethostip + </dt> + <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mapping</code>) gethostip()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the IP addresses of the host. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns a mapping that maps interface name to a mapping with + more information about that interface. That information mapping + looks as follows. + <table class='box'><tr><td><code><code class='key'>"ips"</code> : <code class='datatype'>array</code>(<code class='datatype'>string</code>)</code></td><td>A list of all IP addresses bound to this interface. + </td></tr> + </table></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + getprotobyname + </dt> + <dd><code><code class='datatype'>int</code> getprotobyname(<code class='datatype'>string(8bit)</code> <code class='argument'>name</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the protocol number of the protocol <code class='expr'>name</code>. + This calls the POSIX function getprotobyname. + If the protocol cannot be found an error is thrown. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Inherit _Stdio </dt>
4022: <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>append_file()</code>, <code>read_bytes()</code>, <code>Stdio.File()->open()</code> </dd></dl> - <dl><dt><h2 class='header'>Class Stdio.BlockFile</h2> + <dl><dt><h2 class='header'>Enum Stdio.FileModeFlags</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - + <dd class='body--doc'>File mode flags returned by <code>Fd()->mode()</code>. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_APPEND + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_APPEND</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File open for appending. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_CREATE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_CREATE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Create a new file if it didn't exist earlier. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_EXCLUSIVE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_EXCLUSIVE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Exclusive access to the file. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_NONBLOCKING + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_NONBLOCKING</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File opened in nonblocking mode. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_READ + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_READ</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File open for reading. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_TRUNC + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_TRUNC</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Truncate the file on open. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + FILE_WRITE + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_WRITE</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File open for writing. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Enum Stdio.FilePropertyFlags</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File properties for use with eg <code>Fd()->pipe()</code>, + and returned by eg <code>Fd()->mode()</code>. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BIDIRECTIONAL + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BIDIRECTIONAL</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports both sending and receiving. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_BUFFERED + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BUFFERED</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File has internal buffering. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_IPC + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_IPC</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File can be used for interprocess communication. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_NONBLOCK + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_NONBLOCK</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports nonblocking operation. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SEND_FD + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SEND_FD</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File is capable of sending open file descriptors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + PROP_SHUTDOWN + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SHUTDOWN</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>File supports unidirectional close. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.BlockFile</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>The Stdio.BlockFile API. This class exists purely for typing reasons. Use in types in place of <code>Stdio.File</code> where only blocking
5936: </dt> <dd><code><code class='datatype'>int</code> write(<code class='object unresolved'>sprintf_format</code>|<code class='datatype'>array</code>(<code class='datatype'>string(8bit)</code>) <code class='argument'>data</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code>)</code></dd> </dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.Fd</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - + <dd class='body--doc'>Low level I/O operations. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This is not the class you want. Use <code>Stdio.File</code> and friends instead. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File</code>, <code>Stdio.FILE</code>, <code>_Stdio.Fd_ref</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _errno + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>int(0..)</code> Stdio.Fd._errno</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Variable containing the internal value returned by <code>errno()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>errno()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _fd + </dt> + <dd><code><code class='object unresolved'>Fd</code> Stdio.Fd._fd</code></dd> + + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Read only + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _read_callback + Variable + _write_callback + Variable + _read_oob_callback + Variable + _write_oob_callback + Variable + _fs_event_callback + </dt> + <dd><code><code class='datatype'>mixed</code> Stdio.Fd._read_callback</code> + <code><code class='datatype'>mixed</code> Stdio.Fd._write_callback</code> + <code><code class='datatype'>mixed</code> Stdio.Fd._read_oob_callback</code> + <code><code class='datatype'>mixed</code> Stdio.Fd._write_oob_callback</code> + <code><code class='datatype'>mixed</code> Stdio.Fd._fs_event_callback</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Callback functions installed by <code>Stdio.File()->set_callbacks()</code> et al. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + close + </dt> + <dd><code><code class='datatype'>int</code> close()</code> + <code><code class='datatype'>int</code> close(<code class='datatype'>string</code> <code class='argument'>direction</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Close a file or stream. + If direction is not specified, both the read and the write + direction are closed. Otherwise only the directions specified is + closed. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> if the file or stream now is closed in + all directions, and <code class='expr'>0</code> otherwise. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An exception is thrown if an I/O error occurs. + The default behaviour for sockets is typically to flush buffered + data in the background, but this can be changed with <code>linger()</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>linger()</code>, <code>open()</code>, <code>open_socket()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + connect + </dt> + <dd><code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>)</code> + <code><code class='datatype'>bool</code> connect(<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>)</code> + <code><code class='datatype'>string(8bit)</code>|<code class='datatype'>int(0..0)</code> connect(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a TCP/IP connection to the specified destination. + In nonblocking mode, success is indicated with the write-callback, + and failure with the close-callback or the read_oob-callback. + If the <code>data</code> argument is included the socket will use + TCP_FAST_OPEN if available, if not the data will not be + sent. 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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> or the remaining <code class='expr'>data</code> on success, and + <code class='expr'>0</code> on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + connect_unix + </dt> + <dd><code><code class='datatype'>bool</code> connect_unix(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a UNIX domain socket connection to the specified destination. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>filename</code></dt> + <dd></dd><dd class='body--doc'>Filename to create. + In nonblocking mode, success is indicated with the write-callback, + and failure with the close-callback or the read_oob-callback. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>path</code> had a quite restrictive length limit (~100 characters) + prior to Pike 7.8.334. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>Stdio.Fd Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> + <code>Stdio.Fd Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code>Stdio.Fd Stdio.Fd(<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>)</code> + <code>Stdio.Fd Stdio.Fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code> + <code>Stdio.Fd Stdio.Fd(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>See <code>open()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + dup + </dt> + <dd><code><code class='object unresolved'>Stdio.Fd</code> dup()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Duplicate the file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>dup2()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + dup2 + </dt> + <dd><code><code class='datatype'>int</code> dup2(<code class='object unresolved'>Stdio.File</code> <code class='argument'>to</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Duplicate a file over another. + 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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>to</code> need not be open, in which + case a new fd is allocated. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note also that <code>to</code> is also assigned to the same backend (if any) + as this object. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>assign()</code>, <code>dup()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + errno + </dt> + <dd><code><code class='datatype'>int</code> errno()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the errno for the latest failed file operation. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + fd_factory + </dt> + <dd><code><code class='object unresolved'>Fd</code> fd_factory()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Factory creating <code>Stdio.Fd</code> objects. + This function is called by <code>openat()</code>, <code>pipe()</code>, <code>dup()</code> + and other functions creating new file objects. + The default implementation calls <code class='expr'>object_program(this_object())()</code> + to create the new object, and returns the <code>Fd</code> inherit in it. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Note that this function must return the <code>Fd</code> inherit in the object. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.Port()->fd_factory()</code>, <code>openat()</code>, <code>pipe()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + get_dir + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) get_dir(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>path</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get directory contents relative to an open directory. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>path</code></dt> + <dd></dd><dd class='body--doc'>Path relative to the open directory. Defaults to the + directory itself. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an array of filenames. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Not available on all architectures. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>predef::get_dir()</code>, <code>statat()</code>, <code>openat()</code>, <code>unlinkat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + getxattr + </dt> + <dd><code><code class='datatype'>string</code> getxattr(<code class='datatype'>string</code> <code class='argument'>attr</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the value of a specified attribute, or 0 if it does not exist + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + grantpt + </dt> + <dd><code><code class='datatype'>string</code> grantpt()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the filename of the corresponding pts. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function is only available on some platforms. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + is_open + </dt> + <dd><code><code class='datatype'>int</code> is_open()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns true if the file is open. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>If the file is a socket that has been closed from the remote side, + this function might still return true. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + linger + </dt> + <dd><code><code class='datatype'>bool</code> linger(<code class='datatype'>int(-1..65535)</code>|<code class='datatype'>void</code> <code class='argument'>seconds</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the socket linger behaviour on <code>close()</code>. + </dd> + <dt class='head--doc'>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>Reset to default behaviour. This typically means that + <code>close()</code> will return immediately, but any buffered + data will still be sent if possible. + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>Terminate the connection immediately on <code>close()</code>, + and discard any buffered data. + </td></tr> + <tr><td><code><code class='key'>(1..65535)</code></code></td><td>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. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This operation is only valid on sockets. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function was not available in Pike 7.8.775 and earlier. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>close()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + listxattr + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) listxattr()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return an array of all extended attributes set on the file + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + lock + </dt> + <dd><code><code class='object unresolved'>Stdio.FileLockKey</code> lock()</code> + <code><code class='object unresolved'>Stdio.FileLockKey</code> lock(<code class='datatype'>bool</code> <code class='argument'>is_recursive</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Makes an exclusive file lock on this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>trylock()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + mode + </dt> + <dd><code><code class='object unresolved'>FileModeFlags</code>|<code class='object unresolved'>FilePropertyFlags</code> mode()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the open mode and capabilities for the file. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an <code>`|()</code> of the following flags: + <table class='box'><tr><td><code><code class='key'>0x1000</code></code></td><td><code>FILE_READ</code> + </td></tr> + <tr><td><code><code class='key'>0x2000</code></code></td><td><code>FILE_WRITE</code> + </td></tr> + <tr><td><code><code class='key'>0x4000</code></code></td><td><code>FILE_APPEND</code> + </td></tr> + <tr><td><code><code class='key'>0x8000</code></code></td><td><code>FILE_CREATE</code> + </td></tr> + <tr><td><code><code class='key'>0x0100</code></code></td><td><code>FILE_TRUNC</code> + </td></tr> + <tr><td><code><code class='key'>0x0200</code></code></td><td><code>FILE_EXCLUSIVE</code> + </td></tr> + <tr><td><code><code class='key'>0x0400</code></code></td><td><code>FILE_NONBLOCKING</code> + </td></tr> + <tr><td><code><code class='key'>0x0040</code></code></td><td><code>PROP_SEND_FD</code> + </td></tr> + <tr><td><code><code class='key'>0x0010</code></code></td><td><code>PROP_BIDIRECTIONAL</code> + </td></tr> + <tr><td><code><code class='key'>0x0008</code></code></td><td><code>PROP_BUFFERED</code> + </td></tr> + <tr><td><code><code class='key'>0x0004</code></code></td><td><code>PROP_SHUTDOWN</code> + </td></tr> + <tr><td><code><code class='key'>0x0002</code></code></td><td><code>PROP_NONBLOCK</code> + </td></tr> + <tr><td><code><code class='key'>0x0001</code></code></td><td><code>PROP_IPC</code> + </td></tr> + </table> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>In some versions of Pike 7.8 the <tt>PROP_</tt> flags were + filtered from the result. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + open + </dt> + <dd><code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='datatype'>int</code> open(<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>)</code> + <code><code class='datatype'>int</code> open(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a file, or use an existing fd. + 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. + <code>mode</code> describes how the file is opened. It's a case-insensitive + string consisting of one or more of the following letters: + <dl class='group--doc'><dt>"r"</dt> + <dd>Open for reading. + </dd> + <dt>"w"</dt> + <dd>Open for writing. + </dd> + <dt>"a"</dt> + <dd>Append new data to the end. + </dd> + <dt>"c"</dt> + <dd>Create the file if it doesn't exist already. + </dd> + <dt>"t"</dt> + <dd>Truncate the file to zero length if it already contains data. + Use only together with <code class='expr'>"w"</code>. + </dd> + <dt>"x"</dt> + <dd>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. + </dd> + </dl><code>access</code> specifies the permissions to use if a new file is + created. It is a UNIX style permission bitfield: + <dl class='group--doc'><dt>0400</dt> + <dd>User has read permission. + </dd> + <dt>0200</dt> + <dd>User has write permission. + </dd> + <dt>0100</dt> + <dd>User has execute permission. + </dd> + <dt>0040</dt> + <dd>Group has read permission. + </dd> + <dt>0020</dt> + <dd>Group has write permission. + </dd> + <dt>0010</dt> + <dd>Group has execute permission. + </dd> + <dt>0004</dt> + <dd>Others have read permission. + </dd> + <dt>0002</dt> + <dd>Others have write permission. + </dd> + <dt>0001</dt> + <dd>Others have execute permission. + </dd> + </dl>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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>close()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + open_socket + </dt> + <dd><code><code class='datatype'>bool</code> open_socket(<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>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + openat + </dt> + <dd><code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='object unresolved'>Stdio.File</code> openat(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open a file relative to an opened directory. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns a new file object on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Not available on all architectures. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code>, <code>statat()</code>, <code>unlinkat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + openpt + </dt> + <dd><code><code class='datatype'>int</code> openpt(<code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Open the master end of a pseudo-terminal pair. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>grantpt()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + peek + </dt> + <dd><code><code class='datatype'>int(-1..1)</code> peek()</code> + <code><code class='datatype'>int(-1..1)</code> peek(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>)</code> + <code><code class='datatype'>int(-1..1)</code> peek(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Check if there is data available to read, + or wait some time for available data to read. + 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). + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>timeout</code></dt> + <dd></dd><dd class='body--doc'>Timeout in seconds. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>not_eof</code></dt> + <dd></dd><dd class='body--doc'>Flag for specifying handling of end of file. + The following values are currently defined: + <table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Traditional (and default) behaviour. Return <code class='expr'>1</code> + at EOF. + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td>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. + </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>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. + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>There is no data available (ie timeout). + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td>Error condition. The error code returned by <code>errno()</code> + has been updated. + </td></tr> + </table> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>errno()</code>, <code>read()</code> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The function may be interrupted prematurely + of the timeout (due to signals); + check the timing manually if this is imporant. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + pipe + </dt> + <dd><code><code class='object unresolved'>Stdio.File</code> pipe()</code> + <code><code class='object unresolved'>Stdio.File</code> pipe(<code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + proxy + </dt> + <dd><code><code class='datatype'>void</code> proxy(<code class='object unresolved'>Stdio.File</code> <code class='argument'>from</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Starts a thread that asynchronously copies data from <code>from</code> + to this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.sendfile()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_address + </dt> + <dd><code><code class='datatype'>string</code> query_address()</code> + <code><code class='datatype'>string</code> query_address(<code class='datatype'>bool</code> <code class='argument'>local</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get address and port of a socket end-point. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>local</code></dt> + <dd></dd><dd class='body--doc'>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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns the address and port of a socket end-point + on the form <code class='expr'>"x.x.x.x port"</code> (IPv4) or + <code class='expr'>"x:x:x:x:x:x:x:x port"</code> (IPv6). IPv6 addresses + may use the contracted syntax. + 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. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error is thrown if the socket (or file) isn't open. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>connect()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_backend + </dt> + <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the backend used for the callbacks. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_backend</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + query_fd + </dt> + <dd><code><code class='datatype'>int</code> query_fd()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the file descriptor number associated with this object. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>string</code> read()</code> + <code><code class='datatype'>string</code> read(<code class='datatype'>int</code> <code class='argument'>len</code>)</code> + <code><code class='datatype'>string</code> read(<code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read data from a file or a stream. + 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: + <ul> + <li>end-of-file is encountered for a normal file, or + </li><li>it's a stream that has been closed from the other end, or + </li><li>it's a stream in nonblocking mode, or + </li><li>it's a stream and <code>not_all</code> is set, or + </li><li><code>not_all</code> isn't set and an error occurred (see below). + </li></ul>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. + 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. + 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. + If no arguments are given, <code>read()</code> reads to the end of the file + or stream. + 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. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It's not necessary to set <code>not_all</code> to avoid blocking reading + when nonblocking mode is used. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read_oob()</code>, <code>write()</code>, <code>receive_fd()</code>, <code>send_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>int</code> read(<code class='object unresolved'>System.Memory</code> <code class='argument'>dst</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..)</code> <code class='argument'>offset</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads data from a file or stream into the buffer <code>dst</code> at offset + <code>offset</code>. Tries to read as many bytes as buffer space available. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The number of bytes read. Returns <code class='expr'>-1</code> on error and + <code>errno()</code> will return the corresponding error code. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>int</code> read(<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>dst</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads data from a file or stream into the buffer <code>dst</code>. Tries to + read as many bytes as buffer space available. + Will advance the write position in <code>dst</code> by the number of bytes + read. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The number of bytes read. Returns <code class='expr'>-1</code> on error and + <code>errno()</code> will return the corresponding error code. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_oob + </dt> + <dd><code><code class='datatype'>string</code> read_oob()</code> + <code><code class='datatype'>string</code> read_oob(<code class='datatype'>int</code> <code class='argument'>len</code>)</code> + <code><code class='datatype'>string</code> read_oob(<code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>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: + <ul> + <li>the stream has been closed from the other end, or + </li><li>nonblocking mode is used, or + </li><li><code>not_all</code> is set, or + </li><li><code>not_all</code> isn't set and an error occurred (see below). + </li></ul>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. + 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. + If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. That includes an end due to remote close. + If no arguments are given, <code>read_oob()</code> reads to the end of the + stream. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It's not necessary to set <code>not_all</code> to avoid blocking reading + when nonblocking mode is used. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read()</code>, <code>write_oob()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + receive_fd + </dt> + <dd><code><code class='datatype'>void</code> receive_fd(<code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remote file descriptor reception handler. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>fd</code></dt> + <dd></dd><dd class='body--doc'>File descriptor received from the remote end of a <code>pipe()</code>. + This object has been created by <code>fd_factory()</code>. + 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>. + The default implementation is just a prototype. + Overload this function to enable reception of + remote file descriptors. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>send_fd()</code>, <code>read()</code>, <code>fd_factory()</code>, <code>__HAVE_SEND_FD__</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + release_fd + </dt> + <dd><code><code class='datatype'>int</code> release_fd()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>query_fd()</code>, <code>take_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + removexattr + </dt> + <dd><code><code class='datatype'>void</code> removexattr(<code class='datatype'>string</code> <code class='argument'>attr</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove the specified extended attribute. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + seek + </dt> + <dd><code><code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>offset</code>)</code> + <code><code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>offset</code>, <code class='datatype'>string</code> <code class='argument'>whence</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>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: + <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_SET</code></code></td><td>The offset is set to <code>offset</code> bytes. + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_CUR</code></code></td><td>The offset is set to its current location plus <code>offset</code> bytes. + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_END</code></code></td><td>The offset is set to the size of the file plus <code>offset</code> bytes. + </td></tr> + </table>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. + 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. + Seeking file data and holes + 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. + <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_DATA</code></code></td><td>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. + </td></tr> + <tr><td><code><code class='key'>Stdio.SEEK_HOLE</code></code></td><td>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). + </td></tr> + </table>In both of the above cases, seek() fails if offset points past the + end of the file. + 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. + 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.) + 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). + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>tell()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + send_fd + </dt> + <dd><code><code class='datatype'>void</code> send_fd(<code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Queues an open file descriptor for sending to the other end of a stream. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + This operation is only supported on <code>pipe()</code>'s created with + <code>PROP_SEND_FD</code>. + This function is not available on all operating systems, check + for <code>__HAVE_SEND_FD__</code>. + The queue is emptied on successful <code>write()</code> and when the + write direction is <code>close()</code>'d. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>receive_fd()</code>, <code>write()</code>, <code>pipe()</code>, <code>read()</code>, <code>__HAVE_SEND_FD__</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_backend + </dt> + <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the backend used for the callbacks. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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). + Also, this object does not keep a reference to the backend. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>query_backend</code>, <code>set_nonblocking</code>, <code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_fs_event_callback</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_blocking + </dt> + <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Sets this file to blocking operation. + This is the inverse operation of <code>set_nonblocking()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_nonblocking()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_buffer + </dt> + <dd><code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> + <code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set internal socket buffer. + This function sets the internal buffer size of a socket or stream. + 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>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>It is not guaranteed that this function actually does anything, + but it certainly helps to increase data transfer speed when it does. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open_socket()</code>, <code>accept()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_close_on_exec + </dt> + <dd><code><code class='datatype'>void</code> set_close_on_exec(<code class='datatype'>bool</code> <code class='argument'>yes_no</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Marks the file as to be closed in spawned processes. + This function determines whether this file will be closed when + calling exec(). + Default is that the file WILL be closed on exec except for + stdin, stdout and stderr. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Process.create_process()</code>, <code>exec()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_keepalive + </dt> + <dd><code><code class='datatype'>bool</code> set_keepalive(<code class='datatype'>bool</code> <code class='argument'>on_off</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Equivalent to setsockopt(Stdio.SO_KEEPALIVE, on_off), but will set errno + if SO_KEEPALIVE is not supported, rather than issuing a compilation error + for the missing constant. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_nodelay + </dt> + <dd><code><code class='datatype'>bool</code> set_nodelay(<code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>state</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Control Nagle's Algorithm (RFC 896) + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>state</code></dt> + <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Return to the normal state of using Nagle's Algorithm + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td>(default) Disable Nagling - small writes will not be queued. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This operation is only valid on sockets. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'>setsockopt() + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_nonblocking + </dt> + <dd><code><code class='datatype'>void</code> set_nonblocking()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Sets this file to nonblocking operation. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_blocking()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + setsockopt + </dt> + <dd><code><code class='datatype'>bool</code> setsockopt(<code class='datatype'>int</code> <code class='argument'>level</code>, <code class='datatype'>int</code> <code class='argument'>opt</code>, <code class='datatype'>int</code> <code class='argument'>state</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set socket options like Stdio.SO_KEEPALIVE. This function is always + available; the presence or absence of the option constants indicates + availability of those features. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>1 if successful, 0 if not (and sets errno()) + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>set_keepalive()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + setxattr + </dt> + <dd><code><code class='datatype'>void</code> setxattr(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the attribute <code>attr</code> to the value <code>value</code>. + The flags parameter can be used to refine the semantics of the operation. + <code>Stdio.XATTR_CREATE</code> specifies a pure create, which + fails if the named attribute exists already. + <code>Stdio.XATTR_REPLACE</code> specifies a pure replace operation, which + fails if the named attribute does not already exist. + By default (no flags), the extended attribute will be created if need be, + or will simply replace the value if the attribute exists. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>1 if successful, 0 otherwise, setting errno. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + stat + </dt> + <dd><code><code class='object unresolved'>Stat</code> stat()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get status for an open file. + 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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>See <code>file_stat()</code> for a description of the return value. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>file_stat()</code>, <code>statat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + statat + </dt> + <dd><code><code class='object unresolved'>Stat</code> statat(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get status for a file relative an open directory. + 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. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>See <code>file_stat()</code> for a description of the return value. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Not available on all architectures. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>file_stat()</code>, <code>stat()</code>, <code>openat()</code>, <code>unlinkat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + sync + </dt> + <dd><code><code class='datatype'>bool</code> sync()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Flush buffers to disk. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>0</code> (zero) and sets errno on failure. + Returns <code class='expr'>1</code> on success. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + take_fd + </dt> + <dd><code><code class='datatype'>void</code> take_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>release_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + tell + </dt> + <dd><code><code class='datatype'>int</code> tell()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the current offset in the file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>seek()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + truncate + </dt> + <dd><code><code class='datatype'>bool</code> truncate(<code class='datatype'>int</code> <code class='argument'>length</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Truncate a file. + Truncates the file to the specified length <code>length</code>. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>open()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + trylock + </dt> + <dd><code><code class='object unresolved'>Stdio.FileLockKey</code> trylock()</code> + <code><code class='object unresolved'>Stdio.FileLockKey</code> trylock(<code class='datatype'>bool</code> <code class='argument'>is_recursive</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Attempts to place a file lock on this file. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>lock()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + unlinkat + </dt> + <dd><code><code class='datatype'>int</code> unlinkat(<code class='datatype'>string</code> <code class='argument'>f</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a file or directory relative to an open file. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>0</code> (zero) on failure, <code class='expr'>1</code> otherwise. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>rm()</code>, <code>openat()</code>, <code>statat()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + write + </dt> + <dd><code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>data</code>)</code> + <code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code> + <code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>data</code>)</code> + <code><code class='datatype'>int</code> write(<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>)</code> + <code><code class='datatype'>int</code> write(<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>String.Buffer</code>|<code class='object unresolved'>System.Memory</code> <code class='argument'>data</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..)</code> <code class='argument'>offset</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Write data to a file or a stream. + If there are any file descriptors that have been queued for sending + (with <code>send_fd()</code>), they will be sent. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>data</code></dt> + <dd></dd><dd class='body--doc'>Data to write. + If <code>data</code> is an array of strings, they are written in sequence. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>format</code></dt> + <dd></dd> + <dt class='head--doc'>Parameter <code class='parameter'>extras</code></dt> + <dd></dd><dd class='body--doc'>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. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>offset</code></dt> + <dd></dd><dd class='body--doc'>The offset in data to start writing from. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Writes <code>data</code> and returns the number of bytes that were + actually written. + <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td>The number of bytes successfully written to the OS buffers. + This can be less than the size of the given data if eg: + <ul> + <li>Some data was written successfully and then something went + wrong. + 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>. + </li><li>Nonblocking mode is used and not all data could be written + without blocking. + </li></ul> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>No bytes were written. This may be due to + <ul> + <li><code>data</code> or the formatted data being the empty string. + </li><li>Nonblocking mode is used and no data could be written + without blocking. + </li></ul> + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td>Something went wrong and no bytes were written. + </td></tr> + </table>If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The variant of this function using a buffer object does not release + the interpreter lock. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read()</code>, <code>write_oob()</code>, <code>send_fd()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + write_oob + </dt> + <dd><code><code class='datatype'>int</code> write_oob(<code class='datatype'>string</code> <code class='argument'>data</code>)</code> + <code><code class='datatype'>int</code> write_oob(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Write out-of-band data to a stream. + 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. + -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. + If everything went fine, a call to <code>errno()</code> directly afterwards + returns zero. + If more than one argument is given, <code>sprintf()</code> is used to format + them. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read_oob()</code>, <code>write()</code> + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Fd_ref</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Proxy class that contains stub functions + that call the corresponding functions in + <code>Fd</code>. + Used by <code>Stdio.File</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This is not the class you want. Use <code>Stdio.File</code> and friends instead. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Stdio.File</code>, <code>Stdio.FILE</code>, <code>_Stdio.Fd</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + _fd + </dt> + <dd><code><code class='object unresolved'>Fd</code> Stdio.Fd_ref._fd</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Object to which called functions are relayed. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + Fd + </dt> + <dd><code>inherit Fd : Fd</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Fake inherit to propagate the documentation + from <code>_Stdio.Fd</code>. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>The Stdio.NonblockingStream API. This class exists purely for typing reasons. Use in types in place of <code>Stdio.File</code> where nonblocking and/or

autodoc.git/ traditional_manual/ chapter_9.html

2019-01-24

2019-01-24 15:05:56 by Henrik Grubbström (Grubba) <grubba@grubba.org>