9699552002-03-12Martin Nilsson <!doctype html><html><head><title>Pike Reference Manual</title> <meta charset='utf-8'></head>
c3fe742003-02-05Martin Nilsson <body><dl><dt><h1 class='header'>9. I/O</h1></dt><dd><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.File</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>This is the basic I/O object, it provides socket and pipe communication as well as file access. It does not buffer reads and writes or provide line-by-line reading, that is done with <code>Stdio.FILE</code> object.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The file or stream will normally be closed when this object is destructed (unless there are more objects that refer to the same file through use of <code>assign</code> or <code>dup</code>). Objects do not contain cyclic references in themselves, so they will be destructed timely when they run out of references.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Stdio.FILE</code></p>
c3fe742003-02-05Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>assign</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function takes a clone of Stdio.File and assigns all variables of this file from it. It can be used together with <code>dup()</code> to move files around.</p>
e4e3f32002-04-06Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>dup()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>async_connect</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
b27ad92003-04-22Marcus Comstedt <dd><p><code><code class='datatype'>int</code> <b><span class='method'>async_connect</span>(</b><code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>callback</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Open a TCP/IP connection asynchronously.</p> <p> This function is similar to <code>connect()</code>, but works asynchronously.</p> </dd> <dt class='head--doc'><span id='p-host'></span>Parameter <code class='parameter'>host</code></dt> <dd></dd><dd class='body--doc'><p>Hostname or IP to connect to.</p> </dd> <dt class='head--doc'><span id='p-port'></span>Parameter <code class='parameter'>port</code></dt>
b27ad92003-04-22Marcus Comstedt <dd></dd><dd class='body--doc'><p>Port number or service name to connect to.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'><span id='p-callback'></span>Parameter <code class='parameter'>callback</code></dt> <dd></dd><dd class='body--doc'><p>Function to be called on completion.
84ea4e2003-04-07Martin Nilsson  The first argument will be <code class='expr'>1</code> if a connection was
875daa2009-04-25Martin Stjernholm  successfully established, and <code class='expr'>0</code> (zero) on failure.
c3fe742003-02-05Martin Nilsson  The rest of the arguments to <code>callback</code> are passed verbatim from <code>args</code>.</p> </dd> <dt class='head--doc'><span id='p-args'></span>Parameter <code class='parameter'>args</code></dt> <dd></dd><dd class='body--doc'><p>Extra arguments to pass to <code>callback</code>.</p> </dd> <dt class='head--doc'>Returns</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>Returns <code class='expr'>0</code> on failure, and <code class='expr'>1</code> if <code>callback</code>
c3fe742003-02-05Martin Nilsson  will be used.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The socket may be opened with <code>open_socket()</code> ahead of the call to this function, but it is not required.</p>
7770c92003-10-29Martin Stjernholm </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This object is put in callback mode by this function. For <code>callback</code> to be called, the backend must be active. See e.g. <code>set_read_callback</code> for more details about backends and callback mode.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The socket will be in nonblocking state if the connection is successful, and any callbacks will be cleared.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>connect()</code>, <code>open_socket()</code>, <code>set_nonblocking()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>close</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Close the file. Optionally, specify "r", "w" or "rw" to close just the read, just the write or both read and write directions of the file respectively.</p>
d69f952003-10-22Martin Stjernholm <p> An exception is thrown if an I/O error occurs.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Nonzero is returned if the file wasn't open in the specified direction, zero otherwise.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function will not call the <tt>close_callback</tt>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>open</code>, <code>open_socket</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
1f918f2002-05-26Martin Nilsson 
f228872013-06-17Martin Nilsson <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>
b157ef2014-08-26Per Hedbor <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>
f228872013-06-17Martin Nilsson  <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>
b157ef2014-08-26Per Hedbor <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>
f228872013-06-17Martin Nilsson </dd> <dt class='head--doc'>Returns</dt>
b157ef2014-08-26Per Hedbor <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>
f228872013-06-17Martin Nilsson </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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>connect</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
b157ef2014-08-26Per Hedbor <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>
770b6a2014-08-26Per Hedbor <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>
b157ef2014-08-26Per Hedbor <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'>int(0..0)</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>, <code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
b157ef2014-08-26Per Hedbor <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> The <code>host</code> argument is the hostname or IP number of the remote machine.</p> <p> A local IP and port can be explicitly bound by specifying <code>client</code> and <code>client_port</code>.</p> <p> If the <code>data</code> argument is included the socket will use TCP_FAST_OPEN if posible. In this mode the the function will return the part of the data that has not been sent to the remote server yet instead of 1 (you will have to use <code>write</code> to send this data).</p> <p> Note that TCP_FAST_OPEN requires server support, the connection might fail even though the remote server exists. It might be advicable to retry without TCP_FAST_OPEN (and remember this fact)</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Returns</dt>
b157ef2014-08-26Per Hedbor <dd class='body--doc'><p>This function returns 1 or the remaining <code>data</code> for success, 0 otherwise.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and
b157ef2014-08-26Per Hedbor  <code>errno()</code> set to <code class='expr'>EWOULDBLOCK</code> or <code class='expr'>WSAEWOULDBLOCK</code>.</p> <p> This should not be regarded as a
84ea4e2003-04-07Martin Nilsson  connection failure. In nonblocking mode you need to wait for a write or close callback before you know if the connection failed or not.</p>
e4e3f32002-04-06Martin Nilsson </dd>
50af352002-07-15Martin Nilsson <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>query_address()</code>, <code>async_connect()</code>, <code>connect_unix()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>connect_unix</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Open a UNIX domain socket connection to the specified destination.</p>
e4e3f32002-04-06Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Returns</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Nonblocking mode is not supported while connecting</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>create</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='object'>Stdio.File</span> <span class='class'>Stdio.File</span><b>(</b><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><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'>mask</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'>descriptorname</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>There are four basic ways to create a Stdio.File object. The first is calling it without any arguments, in which case the you'd have to call <code>open()</code>, <code>connect()</code> or some other method which connects the File object with a stream.</p> <p> The second way is calling it with a <code>filename</code> and open <code>mode</code>. This is the same thing as cloning and then calling <code>open()</code>, except shorter and faster.</p>
84ea4e2003-04-07Martin Nilsson <p> The third way is to call it with <code>descriptorname</code> of <code class='expr'>"stdin"</code>, <code class='expr'>"stdout"</code> or <code class='expr'>"stderr"</code>. This will open the specified
c3fe742003-02-05Martin Nilsson  standard stream.</p> <p> For the advanced users, you can use the file descriptors of the systems (note: emulated by pike on some systems - like NT). This is only useful for streaming purposes on unix systems. This is <b>not recommended at all</b> if you don't know what you're into. Default
84ea4e2003-04-07Martin Nilsson  <code>mode</code> for this is <code class='expr'>"rw"</code>.</p>
715b8a2002-10-12Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Open mode will be filtered through the system UMASK. You might need to use <code>chmod()</code> later.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>open()</code>, <code>connect()</code>, <code>Stdio.FILE</code>,</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>dup</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>File</code> <b><span class='method'>dup</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function returns a clone of Stdio.File with all variables copied from this file.</p>
715b8a2002-10-12Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>All variables, even <tt>id</tt>, are copied.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>assign()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>errno</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>errno</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
f228872013-06-17Martin Nilsson <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>
4e6acb2014-03-03Henrik Grubbström (Grubba) <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>
f228872013-06-17Martin Nilsson <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>
e98dbb2013-11-13Henrik Grubbström (Grubba) <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the filename of the corresponding pts.</p> </dd>
f228872013-06-17Martin Nilsson <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only available on some platforms.</p> </dd></dl>
b5f0332009-02-22Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>Fd</b></span> </dt> <dd><p><code><span class='datatype'><code class='modifier'>optional</code> inherit Fd</span> : <span class='inherit'>Fd</span></code></p></dd> </dl>
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>line_iterator</b></span>
1f918f2002-05-26Martin Nilsson </dt>
88ba442003-04-21Henrik Grubbström (Grubba) <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>
c3fe742003-02-05Martin Nilsson  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns an iterator that will loop over the lines in this file.
0f4adf2003-07-22Henrik Grubbström (Grubba)  If trim is true, all <tt>'\r'</tt> characters will be removed from the input.</p>
c3fe742003-02-05Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
d961e22013-05-29Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
f228872013-06-17Martin Nilsson <span class='homogen--name'><b>linger</b></span>
d961e22013-05-29Henrik Grubbström (Grubba) </dt>
f228872013-06-17Martin Nilsson <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>
d961e22013-05-29Henrik Grubbström (Grubba)  <dt class='head--doc'>Description</dt>
f228872013-06-17Martin Nilsson <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>
aee4db2013-06-13Martin Nilsson </td></tr>
f228872013-06-17Martin Nilsson <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>
aee4db2013-06-13Martin Nilsson </td></tr>
f228872013-06-17Martin Nilsson <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>
aee4db2013-06-13Martin Nilsson </td></tr>
f228872013-06-17Martin Nilsson </table>
d961e22013-05-29Henrik Grubbström (Grubba) </dd> <dt class='head--doc'>Returns</dt>
f228872013-06-17Martin Nilsson <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>
d961e22013-05-29Henrik Grubbström (Grubba) </dd> <dt class='head--doc'>See also</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p><code>close()</code></p>
d961e22013-05-29Henrik Grubbström (Grubba) </dd></dl>
5465692008-06-13Martin Bähr <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
f228872013-06-17Martin Nilsson <span class='homogen--name'><b>listxattr</b></span>
5465692008-06-13Martin Bähr </dt>
f228872013-06-17Martin Nilsson <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>
5465692008-06-13Martin Bähr  <dt class='head--doc'>Description</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p>Return an array of all extended attributes set on the file</p>
5465692008-06-13Martin Bähr </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
f228872013-06-17Martin Nilsson <span class='homogen--name'><b>lock</b></span>
5465692008-06-13Martin Bähr </dt>
f228872013-06-17Martin Nilsson <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>
5465692008-06-13Martin Bähr  <dt class='head--doc'>Description</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p>Makes an exclusive file lock on this file.</p>
5465692008-06-13Martin Bähr </dd> <dt class='head--doc'>See also</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p><code>trylock()</code></p>
5465692008-06-13Martin Bähr </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
f228872013-06-17Martin Nilsson <span class='homogen--name'><b>mode</b></span>
5465692008-06-13Martin Bähr </dt>
f228872013-06-17Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>mode</span>(</b><b>)</b></code></p></dd>
5465692008-06-13Martin Bähr  <dt class='head--doc'>Description</dt>
f228872013-06-17Martin Nilsson <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>
85a1122009-06-10Henrik Grubbström (Grubba) </td></tr>
f228872013-06-17Martin Nilsson <tr><td><code><code class='key'>0x2000</code></code></td><td><p><code>FILE_WRITE</code></p>
85a1122009-06-10Henrik Grubbström (Grubba) </td></tr>
f228872013-06-17Martin Nilsson <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>
85a1122009-06-10Henrik Grubbström (Grubba) </dd>
5465692008-06-13Martin Bähr <dt class='head--doc'>See also</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p><code>open()</code></p>
5465692008-06-13Martin Bähr </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
f228872013-06-17Martin Nilsson <span class='homogen--name'><b>notify</b></span>
5465692008-06-13Martin Bähr </dt>
f228872013-06-17Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>notify</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>notification</code>, <code class='datatype'>function</code>(<code class='datatype'>void</code>:<code class='datatype'>void</code>) <code class='argument'>callback</code><b>)</b></code></p></dd>
5465692008-06-13Martin Bähr  <dt class='head--doc'>Description</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p>Receive notification when change occur within the fd. To use, create a Stdio.File object of a directory like Stdio.File(".") and then call notify() with the appropriate parameters.</p>
25eb8a2003-10-05Henrik Grubbström (Grubba) </dd>
f228872013-06-17Martin Nilsson <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>When a program registers for some notification, only the first notification will be received unless DN_MULTISHOT is specified as part of the notification argument.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>At present, this function is Linux-specific and requires a kernel which supports the F_NOTIFY fcntl() call.</p> </dd> <dt class='head--doc'><span id='p-notification'></span>Parameter <code class='parameter'>notification</code></dt> <dd></dd><dd class='body--doc'><p>What to notify the callback of. See the Stdio.DN_* constants for more information about possible notifications.</p> </dd> <dt class='head--doc'><span id='p-callback'></span>Parameter <code class='parameter'>callback</code></dt> <dd></dd><dd class='body--doc'><p>Function which should be called when notification is received. The function gets the signal used to indicate the notification as its argument and shouldn't return anyting.</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'>mask</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Open a file for read, write or append. The parameter <code>mode</code> should contain one or more of the following letters:</p> <table class='box'><tr><td><code><code class='key'>"r"</code></code></td><td><p>Open file for reading.</p> </td></tr> <tr><td><code><code class='key'>"w"</code></code></td><td><p>Open file for writing.</p> </td></tr> <tr><td><code><code class='key'>"a"</code></code></td><td><p>Open file for append (use with <code class='expr'>"w"</code>).</p> </td></tr> <tr><td><code><code class='key'>"t"</code></code></td><td><p>Truncate file at open (use with <code class='expr'>"w"</code>).</p> </td></tr> <tr><td><code><code class='key'>"c"</code></code></td><td><p>Create file if it doesn't exist (use with <code class='expr'>"w"</code>).</p> </td></tr> <tr><td><code><code class='key'>"x"</code></code></td><td><p>Fail if file already exists (use with <code class='expr'>"c"</code>).</p> </td></tr> </table><p><code>mode</code> should always contain at least one of the letters <code class='expr'>"r"</code> or <code class='expr'>"w"</code>.</p> <p> The parameter <code>mask</code> is protection bits to use if the file is created. Default is <code class='expr'>0666</code> (read+write for all in octal notation).</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>close()</code>, <code>create()</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'>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> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This makes this file into a socket ready for connections. The reason for this function is so that you can set the socket to nonblocking or blocking (default is blocking) before you call <code>connect()</code>.</p> </dd> <dt class='head--doc'><span id='p-port'></span>Parameter <code class='parameter'>port</code></dt> <dd></dd><dd class='body--doc'><p>If you give a port number to this function, the socket will be bound to this port locally before connecting anywhere. This is only useful for some silly protocols like <b>FTP</b>. The port can also be specified as a string, giving the name of the service
7aed9a2013-10-22Chris Angelico  associated with the port. Pass -1 to not specify a port (eg to bind only to an address).</p>
f228872013-06-17Martin Nilsson </dd> <dt class='head--doc'><span id='p-address'></span>Parameter <code class='parameter'>address</code></dt> <dd></dd><dd class='body--doc'><p>You may specify an address to bind to if your machine has many IP numbers.</p> </dd> <dt class='head--doc'><span id='p-family_hint'></span>Parameter <code class='parameter'>family_hint</code></dt> <dd></dd><dd class='body--doc'><p>A protocol family for the socket can be specified. If no family is specified, one which is appropriate for the address is automatically selected. Thus, there is normally no need to specify it. If you do not want to specify a bind address, you can provide the address as a hint here instead, to allow the automatic selection to work anyway.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>This function returns 1 for success, 0 otherwise.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>connect()</code>, <code>set_nonblocking()</code>, <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>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> <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>, <code class='datatype'>int</code> <code class='argument'>mask</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Open a file relative to an open directory.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>File.statat()</code>, <code>File.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>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. The parameter <code>mode</code> should contain one or more of the following letters:</p> <table class='box'><tr><td><code><code class='key'>"r"</code></code></td><td><p>Open terminal for reading.</p> </td></tr> <tr><td><code><code class='key'>"w"</code></code></td><td><p>Open terminal for writing.</p> </td></tr> </table><p><code>mode</code> should always contain at least one of the letters <code class='expr'>"r"</code> or <code class='expr'>"w"</code>.</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>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> <dd class='body--doc'><p>This function creates a pipe between the object it was called in and an object that is returned.</p> </dd> <dt class='head--doc'><span id='p-required_properties'></span>Parameter <code class='parameter'>required_properties</code></dt> <dd></dd><dd class='body--doc'><p>Binary or (<code>predef::`|()</code>) of required <code class='expr'>PROP_</code> properties.</p> <table class='box'><tr><td><code><code class='key'>PROP_IPC</code></code></td><td><p>The resulting pipe may be used for inter process communication.</p> </td></tr> <tr><td><code><code class='key'>PROP_NONBLOCK</code></code></td><td><p>The resulting pipe supports nonblocking I/O.</p> </td></tr> <tr><td><code><code class='key'>PROP_SHUTDOWN</code></code></td><td><p>The resulting pipe supports shutting down transmission in either direction (see <code>close()</code>).</p>
25eb8a2003-10-05Henrik Grubbström (Grubba) </td></tr> <tr><td><code><code class='key'>PROP_BUFFERED</code></code></td><td><p>The resulting pipe is buffered (usually 4KB).</p> </td></tr> <tr><td><code><code class='key'>PROP_BIDIRECTIONAL</code></code></td><td><p>The resulting pipe is bi-directional.</p> </td></tr>
60c5b22010-11-19Henrik Grubbström (Grubba) <tr><td><code><code class='key'>PROP_SEND_FD</code></code></td><td><p>The resulting pipe might support sending of file descriptors (see <code>send_fd()</code> and <code>receive_fd()</code> for details).</p>
15e2972010-11-19Henrik Grubbström (Grubba) </td></tr>
25eb8a2003-10-05Henrik Grubbström (Grubba) <tr><td><code><code class='key'>PROP_REVERSE</code></code></td><td><p>The resulting pipe supports communication "backwards" (but not necessarily "forwards", see <code>PROP_BIDIRECTIONAL</code>).</p> </td></tr> </table><p>The default is <code class='expr'>PROP_NONBLOCK|PROP_BIDIRECTIONAL</code>.</p> <p> If <code>PROP_BIDIRECTIONAL</code> isn't specified, the read-end is this object, and the write-end is the returned object (unless <code>PROP_REVERSE</code> has been specified, in which case it is the other way around).</p> <p> The two ends of a bi-directional pipe are indistinguishable.</p> <p> If the File object this function is called in was open to begin with, it will be closed before the pipe is created.</p> </dd> <dt class='head--doc'>Note</dt>
5465692008-06-13Martin Bähr <dd class='body--doc'><p>Calling this function with an argument of <tt>0</tt> is not the same as calling it with no arguments.</p> </dd> <dt class='head--doc'>See also</dt>
60c5b22010-11-19Henrik Grubbström (Grubba) <dd class='body--doc'><p><code>Process.create_process()</code>, <code>send_fd()</code>, <code>receive_fd()</code>,
15e2972010-11-19Henrik Grubbström (Grubba)  <code>PROP_IPC</code>, <code>PROP_NONBLOCK</code>, <code>PROP_SEND_FD</code>,
5465692008-06-13Martin Bähr  <code>PROP_SHUTDOWN</code>, <code>PROP_BUFFERED</code>, <code>PROP_REVERSE</code>, <code>PROP_BIDIRECTIONAL</code></p> </dd></dl>
f228872013-06-17Martin Nilsson <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>
5465692008-06-13Martin Bähr <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> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>query_read_oob_callback</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>query_write_oob_callback</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>query_close_callback</b></span><br>
f7261b2009-04-25Martin Stjernholm <span class='homogen--type'>Method</span> <span class='homogen--name'><b>query_callbacks</b></span><br>
5465692008-06-13Martin Bähr </dt>
b34a222014-09-15Per Hedbor <dd><p><code><code class='object unresolved'>read_callback_t</code> <b><span class='method'>query_read_callback</span>(</b><b>)</b></code><br> <code><code class='object unresolved'>write_callback_t</code> <b><span class='method'>query_write_callback</span>(</b><b>)</b></code><br>
5465692008-06-13Martin Bähr <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <b><span class='method'>query_read_oob_callback</span>(</b><b>)</b></code><br> <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <b><span class='method'>query_write_oob_callback</span>(</b><b>)</b></code><br>
f7261b2009-04-25Martin Stjernholm <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <b><span class='method'>query_close_callback</span>(</b><b>)</b></code><br> <code><code class='datatype'>array</code>(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code>:<code class='datatype'>int</code>)) <b><span class='method'>query_callbacks</span>(</b><b>)</b></code></p></dd>
5465692008-06-13Martin Bähr  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>These functions return the currently installed callbacks for the respective events.</p>
f7261b2009-04-25Martin Stjernholm <p> <code>query_callbacks</code> returns the callbacks in the same order as <code>set_callbacks</code> and <code>set_nonblocking</code> expect them.</p>
5465692008-06-13Martin Bähr </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_nonblocking()</code>, <code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_read_oob_callback</code>,
f7261b2009-04-25Martin Stjernholm  <code>set_write_oob_callback</code>, <code>set_close_callback</code>, <code>set_callbacks</code></p>
5465692008-06-13Martin Bähr </dd></dl>
f228872013-06-17Martin Nilsson <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>
5465692008-06-13Martin Bähr <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> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function returns the <tt>id</tt> that has been set with <code>set_id()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_id()</code></p> </dd></dl>
f228872013-06-17Martin Nilsson <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>
b34a222014-09-15Per Hedbor <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> <dd><p><code><code class='datatype'>typedef</code> <code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>) Stdio.File.<code class='typedef'>read_callback_t</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>The various read_callback signatures.</p> <p> The string (or void) version is used when buffer mode (see <code>set_buffer_mode</code>) has not been enabled for reading.</p> <p> The IOBuffer version is used when an IOBuffer has been enabled for reading</p> <p> In both cases the data is the newly arrived data, but in buffered mode data you did not fully read in the last read callback is kept in the buffer.</p> </dd></dl>
5465692008-06-13Martin Bähr <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>read_function</b></span> </dt> <dd><p><code><code class='datatype'>function</code>(:<code class='datatype'>string</code>) <b><span class='method'>read_function</span>(</b><code class='datatype'>int</code> <code class='argument'>nbytes</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns a function that when called will call <code>read</code> with nbytes as argument. Can be used to get various callback functions, eg for the fourth argument to <code>String.SplitIterator</code>.</p> </dd></dl>
f228872013-06-17Martin Nilsson <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>
7d43242014-09-23Per Hedbor <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>
f228872013-06-17Martin Nilsson  <dt class='head--doc'>Description</dt>
7d43242014-09-23Per Hedbor <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>
f228872013-06-17Martin Nilsson </dd> <dt class='head--doc'>Returns</dt>
7d43242014-09-23Per Hedbor <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>
f228872013-06-17Martin Nilsson </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>
60c5b22010-11-19Henrik Grubbström (Grubba) <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>
6582942013-06-17Martin Nilsson <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>
60c5b22010-11-19Henrik Grubbström (Grubba) </dl>
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_blocking</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_blocking</span>(</b><b>)</b></code></p></dd>
1f918f2002-05-26Martin Nilsson  <dt class='head--doc'>Description</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>This function clears all callbacks and sets a stream to blocking mode. i.e. reading, writing and closing will wait until data has been transferred before returning.</p>
1f918f2002-05-26Martin Nilsson </dd>
0f4adf2003-07-22Henrik Grubbström (Grubba) <dt class='head--doc'>Note</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>The callbacks are cleared and blocking mode is set in one atomic
aee4db2013-06-13Martin Nilsson  operation, so no callback gets called in between if the backend is running in another thread.</p> <p> Even so, if the stream is in callback mode (i.e. if any callbacks are installed) then only the backend thread can use this function reliably; it might otherwise already be running in a callback which is about to call e.g. <code>write</code> when the stream becomes blocking.</p>
5465692008-06-13Martin Bähr </dd> <dt class='head--doc'>See also</dt>
f228872013-06-17Martin Nilsson <dd class='body--doc'><p><code>set_nonblocking()</code>, <code>set_nonblocking_keep_callbacks()</code>, <code>set_blocking_keep_callbacks()</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>
5465692008-06-13Martin Bähr </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking_keep_callbacks</span>(</b><b>)</b></code><br> <code><code class='datatype'>void</code> <b><span class='method'>set_blocking_keep_callbacks</span>(</b><b>)</b></code></p></dd>
1f918f2002-05-26Martin Nilsson  <dt class='head--doc'>Description</dt>
0f4adf2003-07-22Henrik Grubbström (Grubba) <dd class='body--doc'><p>Toggle between blocking and nonblocking, without changing the callbacks.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_nonblocking()</code>, <code>set_blocking()</code></p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
f228872013-06-17Martin Nilsson <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>
2326c02014-09-03Per Hedbor <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>
8d4a002014-09-03Per Hedbor <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>
2326c02014-09-03Per Hedbor  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Toggle the file to IOBuffer mode.</p>
8d4a002014-09-03Per Hedbor <p> In this mode reading and writing will be done from IOBuffer objects, in the directions you included buffers.</p>
2326c02014-09-03Per Hedbor </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Normally you call <code>write</code> to re-trigger the write callback if you do not output anything in it (which will stop it from re-occuring again).</p>
8d4a002014-09-03Per Hedbor <p> This will work with buffered output mode as well, but simply adding more data to the output buffer will work as well.</p>
2326c02014-09-03Per Hedbor </dd></dl>
f7261b2009-04-25Martin Stjernholm <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_callbacks</b></span> </dt>
b34a222014-09-15Per Hedbor <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_callbacks</span>(</b><code class='object unresolved'>read_callback_t</code>|<code class='datatype'>void</code> <code class='argument'>read_cb</code>, <code class='object unresolved'>write_callback_t</code>|<code class='datatype'>void</code> <code class='argument'>write_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>, <code class='datatype'>void</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_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code><b>)</b></code></p></dd>
f7261b2009-04-25Martin Stjernholm  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Installs all the specified callbacks at once. Use <code>UNDEFINED</code> to keep the current setting for a callback.</p> <p> Like <code>set_nonblocking</code>, the callbacks are installed atomically. As opposed to <code>set_nonblocking</code>, this function does not do anything with the stream, and it doesn't even have to be open.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_read_oob_callback</code>, <code>set_write_oob_callback</code>, <code>set_close_callback</code>, <code>query_callbacks</code></p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
7770c92003-10-29Martin Stjernholm <span class='homogen--name'><b>set_read_callback</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_write_callback</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_read_oob_callback</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_write_oob_callback</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_close_callback</b></span><br>
54a60c2012-05-01Bill Welliver <span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_fs_event_callback</b></span><br>
e4e3f32002-04-06Martin Nilsson </dt>
7770c92003-10-29Martin Stjernholm <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_read_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code><b>)</b></code><br>
2326c02014-09-03Per Hedbor <code><code class='datatype'>void</code> <b><span class='method'>set_read_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code><b>)</b></code><br>
7770c92003-10-29Martin Stjernholm <code><code class='datatype'>void</code> <b><span class='method'>set_write_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code><b>)</b></code><br>
2326c02014-09-03Per Hedbor <code><code class='datatype'>void</code> <b><span class='method'>set_write_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code><b>)</b></code><br>
7770c92003-10-29Martin Stjernholm <code><code class='datatype'>void</code> <b><span class='method'>set_read_oob_callback</span>(</b><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_cb</code><b>)</b></code><br> <code><code class='datatype'>void</code> <b><span class='method'>set_write_oob_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code><b>)</b></code><br>
54a60c2012-05-01Bill Welliver <code><code class='datatype'>void</code> <b><span class='method'>set_close_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code><b>)</b></code><br> <code><code class='datatype'>void</code> <b><span class='method'>set_fs_event_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>int</code>:<code class='datatype'>int</code>) <code class='argument'>fs_event_cb</code>, <code class='datatype'>int</code> <code class='argument'>event_mask</code><b>)</b></code></p></dd>
c3fe742003-02-05Martin Nilsson  <dt class='head--doc'>Description</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>These functions set the various callbacks, which will be called when various events occur on the stream. A zero as argument will
ee845b2004-04-05Martin Stjernholm  remove the callback.</p>
7770c92003-10-29Martin Stjernholm <p> A <code>Pike.Backend</code> object is responsible for calling the callbacks. It requires a thread to be waiting in it to execute the calls. That means that only one of the callbacks will be running at a time, so you don't need mutexes between them.</p> <p> Unless you've specified otherwise with the <code>set_backend</code> function, the default backend <code>Pike.DefaultBackend</code> will be used. It's normally activated by returning <code class='expr'>-1</code> from the <tt>main</tt> function and will then execute in the main thread.</p> <ul> <li><p>When data arrives on the stream, <code>read_cb</code> will be called with some or all of that data as the second argument.</p>
2326c02014-09-03Per Hedbor <p> If the file is in buffer mode, the second argument will be an IOBuffer.</p> <p> This will always be the same buffer, so data you do not use in one read callback can be simply left in the buffer, when new data arrives it will be appended</p>
7770c92003-10-29Martin Stjernholm </li><li><p>When the stream has buffer space over for writing, <code>write_cb</code> will be called so that you can write more data to it.</p>
fc8e992005-01-26Martin Stjernholm <p> This callback is also called after the remote end of a socket
09a3a02005-01-26Martin Stjernholm  connection has closed the write direction. An attempt to write data to it in that case will generate a <code>System.EPIPE</code> errno. If the remote end has closed both directions simultaneously (the usual case), Pike will first attempt to call <code>close_cb</code>, then this callback (unless <code>close_cb</code> has closed the stream).</p>
2326c02014-09-03Per Hedbor <p> If the file is in buffer mode, the second argument will be an IOBuffer.</p> <p> You should add data to write to this buffer.</p>
7770c92003-10-29Martin Stjernholm </li><li><p>When out-of-band data arrives on the stream, <code>read_oob_cb</code> will be called with some or all of that data as the second argument.</p> </li><li><p>When the stream allows out-of-band data to be sent, <code>write_oob_cb</code> will be called so that you can write more out-of-band data to it.</p>
fc8e992005-01-26Martin Stjernholm <p> If the OS doesn't separate the write events for normal and out-of-band data, Pike will try to call <code>write_oob_cb</code> first. If it doesn't write anything, then <code>write_cb</code> will be tried. This also means that <code>write_oob_cb</code> might get called when the
09a3a02005-01-26Martin Stjernholm  remote end of a connection has closed the write direction.</p>
fc8e992005-01-26Martin Stjernholm </li><li><p>When an error or an end-of-stream in the read direction occurs, <code>close_cb</code> will be called. <code>errno</code> will return the error, or zero in the case of an end-of-stream.</p> <p> The name of this callback is rather unfortunate since it really has nothing to do with a close: The stream is still open when <code>close_cb</code> is called (you might not be able to read and/or write to it, but you can still use things like <code>query_address</code>, and the underlying file descriptor is still allocated). Also, this callback will not be called for a local close, neither by a call to <code>close</code> or by destructing this object.</p>
09a3a02005-01-26Martin Stjernholm <p> Also, <code>close_cb</code> will not be called if a remote close only occurs in the write direction; that is handled by <code>write_cb</code> (or possibly <code>write_oob_cb</code>).</p> <p> Events to <code>read_cb</code> and <code>close_cb</code> will be automatically deregistered if an end-of-stream occurs, and all events in the case of an error. I.e. there won't be any more calls to the callbacks unless they are reinstalled. This doesn't affect the
fc8e992005-01-26Martin Stjernholm  callback settings - <code>query_read_callback</code> et al will still return the installed callbacks.</p>
09a3a02005-01-26Martin Stjernholm </li></ul><p>If the stream is a socket performing a nonblocking connect (see <code>open_socket</code> and <code>connect</code>), a connection failure will call <code>close_cb</code>, and a successful connect will call either <code>read_cb</code> or <code>write_cb</code> as above.</p> <p> All callbacks will receive the <tt>id</tt> set by <code>set_id</code> as
7770c92003-10-29Martin Stjernholm  first argument.</p> <p> If a callback returns <code class='expr'>-1</code>, no other callback or call out will be called by the backend in that round. I.e. the caller of the backend will get control back right away. For the default backend that means it will immediately start another round and check files and call outs anew.</p>
c3fe742003-02-05Martin Nilsson </dd>
ac7a302012-05-02Bill Welliver <dt class='head--doc'><span id='p-event_mask'></span>Parameter <code class='parameter'>event_mask</code></dt> <dd></dd><dd class='body--doc'><p>An event mask specifing bitwise OR of one or more event types to monitor, selected from <code>Stdio.NOTE_WRITE</code> and friends.</p> </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Note</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>These functions do not set the file nonblocking.</p>
c3fe742003-02-05Martin Nilsson </dd>
0f4adf2003-07-22Henrik Grubbström (Grubba) <dt class='head--doc'>Note</dt>
f7261b2009-04-25Martin Stjernholm <dd class='body--doc'><p>Callbacks are also set by <code>set_callbacks</code> and <code>set_nonblocking()</code>.</p>
7770c92003-10-29Martin Stjernholm </dd> <dt class='head--doc'>Note</dt>
6369932004-04-05Martin Stjernholm <dd class='body--doc'><p>After a callback has been called, it's disabled until it has accessed the stream accordingly, i.e. the <code>write_cb</code> callback is disabled after it's been called until something has been written with <code>write</code>, and the <code>write_oob_cb</code> callback is likewise disabled until something has been written with <code>write_oob</code>. Since the data already has been read when the read callbacks are called, this effect is not noticeable for them.</p>
ee845b2004-04-05Martin Stjernholm </dd> <dt class='head--doc'>Note</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>Installing callbacks means that you will start doing I/O on the stream from the thread running the backend. If you are running these set functions from another thread you must be prepared that the callbacks can be called immediately by the backend thread, so it might not be safe to continue using the stream in this thread.</p> <p> Because of that, it's useful to talk about "callback mode" when any callback is installed. In callback mode the stream should be seen as "bound" to the backend thread. For instance, it's only the backend thread that reliably can end callback mode before the stream is "handed over" to another thread.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Callback mode has nothing to do with nonblocking mode - although the two often are used together they don't have to be.</p> </dd> <dt class='head--doc'>Note</dt>
ee845b2004-04-05Martin Stjernholm <dd class='body--doc'><p>The file object will stay referenced from the backend object as long as there are callbacks that can receive events.</p>
7770c92003-10-29Martin Stjernholm </dd> <dt class='head--doc'>Bugs</dt> <dd class='body--doc'><p>Setting a close callback without a read callback currently only works when there's no risk of getting more data on the stream. Otherwise the close callback will be silently deregistered if data arrives.</p>
0f4adf2003-07-22Henrik Grubbström (Grubba) </dd>
54a60c2012-05-01Bill Welliver <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>fs_event callbacks only trigger on systems that support these events. Currently, this includes systems that use kqueue, such as Mac OS X, and various flavours of BSD.</p> </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>See also</dt>
f7261b2009-04-25Martin Stjernholm <dd class='body--doc'><p><code>set_callbacks</code>, <code>set_nonblocking()</code>, <code>set_id()</code>, <code>set_backend</code>, <code>query_read_callback</code>, <code>query_write_callback</code>,
7770c92003-10-29Martin Stjernholm  <code>query_read_oob_callback</code>, <code>query_write_oob_callback</code>, <code>query_close_callback</code></p>
c3fe742003-02-05Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
f228872013-06-17Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_id</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <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>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function sets the <tt>id</tt> of this file. The <tt>id</tt> is mainly used as an identifier that is sent as the first argument to all
84ea4e2003-04-07Martin Nilsson  callbacks. The default <tt>id</tt> is <code class='expr'>0</code> (zero). Another possible
c3fe742003-02-05Martin Nilsson  use of the <tt>id</tt> is to hold all data related to this file in a mapping or array.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>query_id()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
f228872013-06-17Martin Nilsson <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>
45eff82002-06-11Johan Sundström <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_nonblocking</b></span>
45eff82002-06-11Johan Sundström </dt>
b34a222014-09-15Per Hedbor <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>
c3fe742003-02-05Martin Nilsson <code><code class='datatype'>void</code> <b><span class='method'>set_nonblocking</span>(</b><b>)</b></code></p></dd>
45eff82002-06-11Johan Sundström 
50af352002-07-15Martin Nilsson <dt class='head--doc'>Description</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>This function sets a stream to nonblocking mode and installs the specified callbacks. See the <code class='expr'>set_*_callback</code> functions for details about them. If no arguments are given, the callbacks will be cleared.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt>
7770c92003-10-29Martin Stjernholm <dd class='body--doc'><p>As opposed to calling the set callback functions separately, this function will set all the callbacks and nonblocking mode atomically so that no callback gets called in between. That avoids races in case the backend is executed by another thread.</p>
0f4adf2003-07-22Henrik Grubbström (Grubba) </dd> <dt class='head--doc'>Note</dt>
d052e62003-10-23Henrik Grubbström (Grubba) <dd class='body--doc'><p>Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the
0f4adf2003-07-22Henrik Grubbström (Grubba)  option <tt>'--without-oob'</tt>.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
f7261b2009-04-25Martin Stjernholm <dd class='body--doc'><p><code>set_blocking()</code>, <code>set_callbacks</code>, <code>set_read_callback()</code>,
7770c92003-10-29Martin Stjernholm  <code>set_write_callback()</code>, <code>set_read_oob_callback()</code>, <code>set_write_oob_callback()</code>, <code>set_close_callback()</code> <code>set_nonblocking_keep_callbacks()</code>, <code>set_blocking_keep_callbacks()</code></p>
c3fe742003-02-05Martin Nilsson </dd></dl>
45eff82002-06-11Johan Sundström 
f228872013-06-17Martin Nilsson <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>
c3fe742003-02-05Martin Nilsson <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> </dt>
f228872013-06-17Martin Nilsson <dd><p><code><code class='datatype'>mapping</code> <b><span class='method'>tcgetattr</span>(</b><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>tcsetattr</span>(</b><code class='datatype'>mapping</code> <code class='argument'>attr</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>tcsetattr</span>(</b><code class='datatype'>mapping</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>when</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Gets/sets term attributes. The returned value/the <code>attr</code> parameter is a mapping on the form</p> <table class='box'><tr><td><code><code class='key'>"ispeed"</code> : <code class='datatype'>int(-1..)</code></code></td><td><p>In baud rate.</p> </td></tr> <tr><td><code><code class='key'>"ospeed"</code> : <code class='datatype'>int(-1..)</code></code></td><td><p>Out baud rate.</p> </td></tr> <tr><td><code><code class='key'>"csize"</code> : <code class='datatype'>int(-1..-1)</code>|<code class='datatype'>int(5..8)</code></code></td><td><p>Character size in bits.</p> </td></tr> <tr><td><code><code class='key'>"rows"</code> : <code class='datatype'>int</code></code></td><td><p>Terminal rows.</p> </td></tr> <tr><td><code><code class='key'>"columns"</code> : <code class='datatype'>int</code></code></td><td><p>Terminal columns.</p> </td></tr> <tr><td><code><code class='key'>flag_name</code> : <code class='datatype'>bool</code></code></td><td><p>The value of a named flag. The flag name is the string describing the termios flags (IGNBRK, BRKINT, IGNPAR, PARMRK, INPCK, ISTRIP, INLCR, IGNCR, ICRNL, IUCLC, IXON, IXANY, IXOFF, IMAXBEL, OPOST, OLCUC, ONLCR, OCRNL, ONOCR, ONLRET, OFILL, OFDEL, OXTABS, ONOEOT, CSTOPB, CREAD, PARENB, PARODD, HUPCL, CLOCAL, CRTSCTS, ISIG, ICANON, XCASE, ECHO, ECHOE, ECHOK, ECHONL, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, NOFLSH, TOSTOP, PENDIN). See the manpage for termios or other documentation for more information. All flags are not available on all platforms.</p> </td></tr> <tr><td><code><code class='key'>character_name</code> : <code class='datatype'>int(8bit)</code></code></td><td><p>Sets the value of a control character (VINTR, VQUIT, VERASE, VKILL, VEOF, VTIME, VMIN, VSWTC, VSTART, VSTOP, VSUSP, VEOL, VREPRINT, VDISCARD, VWERASE, VLNEXT, VEOL2). All control characters are not available on all platforms.</p> </td></tr> </table><p>Negative values are not allowed as indata, but might appear in the result from <code>tcgetattr</code> when the actual value is unknown. <code>tcsetattr</code> returns 0 if failed.</p> <p> The argument <code>when</code> to <code>tcsetattr</code> describes when the changes are to take effect:</p> <table class='box'><tr><td><code><code class='key'>"TCSANOW"</code></code></td><td><p>The change occurs immediately (default).</p> </td></tr> <tr><td><code><code class='key'>"TCSADRAIN"</code></code></td><td><p>The change occurs after all output has been written.</p> </td></tr> <tr><td><code><code class='key'>"TCSAFLUSH"</code></code></td><td><p>The change occurs after all output has been written, and empties input buffers.</p> </td></tr> </table> </dd> <dt class='head--doc'>Example</dt> <dd class='example'><pre><p>// setting the terminal in raw mode: Stdio.stdin-&gt;tcsetattr((["ECHO":0,"ICANON":0,"VMIN":0,"VTIME":0]));</p> </pre></dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Unknown flags are ignored by <code>tcsetattr()</code>. <code>tcsetattr</code> always changes the attribute, so only include attributes that actually should be altered in the attribute mapping.</p> </dd> <dt class='head--doc'>Bugs</dt> <dd class='body--doc'><p>Terminal rows and columns setting by <code>tcsetattr()</code> is not currently supported.</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>
a7dba62014-07-12Henrik Grubbström (Grubba) <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>
f228872013-06-17Martin Nilsson <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>
b34a222014-09-15Per Hedbor <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> <dd><p><code><code class='datatype'>typedef</code> <code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>) Stdio.File.<code class='typedef'>write_callback_t</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>The various read_callback signatures.</p> <p> The void version is used when buffer mode (see <code>set_buffer_mode</code>) has not been enabled for writing.</p> <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>
f228872013-06-17Martin Nilsson <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>
c3fe742003-02-05Martin Nilsson  <dt class='head--doc'>Description</dt>
f228872013-06-17Martin Nilsson <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>
5465692008-06-13Martin Bähr </dd> <dt class='head--doc'>Note</dt>
f228872013-06-17Martin Nilsson <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>
5465692008-06-13Martin Bähr </dd>
f228872013-06-17Martin Nilsson <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>
5bfef52003-04-01Martin Nilsson </dd></dl>
c3fe742003-02-05Martin Nilsson </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.FILE</b></h2> </dt><dd><dl class='group--doc'>
45eff82002-06-11Johan Sundström <dt class='head--doc'>Description</dt>
0f4adf2003-07-22Henrik Grubbström (Grubba) <dd class='body--doc'><p><code>Stdio.FILE</code> is a buffered version of <code>Stdio.File</code>, it inherits <code>Stdio.File</code> and has most of the functionality of <code>Stdio.File</code>. However, it has an input buffer that allows line-by-line input.</p> <p> It also has support for automatic charset conversion for both input and output (see <code>Stdio.FILE()-&gt;set_charset()</code>).</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The output part of <code>Stdio.FILE</code> is currently not buffered.</p>
45eff82002-06-11Johan Sundström </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>_get_iterator</b></span>
45eff82002-06-11Johan Sundström </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='class'>Stdio.FILE</span> <span class='method'>a</span>;<br> foreach( a; index; value ) or<br></code><code><code class='modifier'>protected</code> <code class='datatype'>object</code> <b><span class='method'>_get_iterator</span>(</b><b>)</b></code></p></dd>
45eff82002-06-11Johan Sundström  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns an iterator that will loop over the lines in this file.</p>
50af352002-07-15Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>line_iterator()</code></p>
45eff82002-06-11Johan Sundström </dd></dl>
84d5df2002-09-16Johan Schön <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getchar</b></span>
84d5df2002-09-16Johan Schön </dt>
1403122012-04-07Arne Goedeke <dd><p><code><code class='modifier'>local</code> <code class='datatype'>int</code> <b><span class='method'>getchar</span>(</b><b>)</b></code></p></dd>
84d5df2002-09-16Johan Schön  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function returns one character from the input stream.</p>
84d5df2002-09-16Johan Schön </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Returns</dt>
0f4adf2003-07-22Henrik Grubbström (Grubba) <dd class='body--doc'><p>Returns the ISO-10646 (Unicode) value of the character.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>Returns an <code class='expr'>int</code> and not a <code class='expr'>string</code> of length 1.</p>
84d5df2002-09-16Johan Schön </dd></dl>
45eff82002-06-11Johan Sundström <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>gets</b></span>
45eff82002-06-11Johan Sundström </dt>
da06012008-12-09Henrik Grubbström (Grubba) <dd><p><code><code class='datatype'>string</code> <b><span class='method'>gets</span>(</b><code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code><b>)</b></code></p></dd>
45eff82002-06-11Johan Sundström  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Read one line of input with support for input conversion.</p> </dd>
da06012008-12-09Henrik Grubbström (Grubba) <dt class='head--doc'><span id='p-not_all'></span>Parameter <code class='parameter'>not_all</code></dt> <dd></dd><dd class='body--doc'><p>Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.</p> </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Returns</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>This function returns the line read if successful, and <code class='expr'>0</code> if
c3fe742003-02-05Martin Nilsson  no more lines are available.</p>
45eff82002-06-11Johan Sundström </dd>
50af352002-07-15Martin Nilsson <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>ngets()</code>, <code>read()</code>, <code>line_iterator()</code>, <code>set_charset()</code></p>
45eff82002-06-11Johan Sundström </dd></dl> <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>file</b></span>
45eff82002-06-11Johan Sundström </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='datatype'>inherit File</span> : <span class='inherit'>file</span></code></p></dd> </dl>
e4e3f32002-04-06Martin Nilsson 
50af352002-07-15Martin Nilsson 
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>line_iterator</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>object</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>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns an iterator that will loop over the lines in this file.
0f4adf2003-07-22Henrik Grubbström (Grubba)  If <code>trim</code> is true, all <tt>'\r'</tt> characters will be removed from the input.</p>
c3fe742003-02-05Martin Nilsson </dd>
abf4cb2005-02-02Per Hedbor <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>It's not supported to call this method more than once unless a call to <code>seek</code> is done in advance. Also note that it's not possible to intermingle calls to <code>read</code>, <code>gets</code> or other functions that read data with the line iterator, it will produce unexpected results since the internal buffer in the iterator will not contain sequential file-data in those cases.</p> </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>_get_iterator()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
ab1f522003-07-10Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>ngets</b></span> </dt>
da06012008-12-09Henrik Grubbström (Grubba) <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>ngets</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int(1..)</code> <code class='argument'>n</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code><b>)</b></code></p></dd>
ab1f522003-07-10Henrik Grubbström (Grubba)  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get <code>n</code> lines.</p> </dd> <dt class='head--doc'><span id='p-n'></span>Parameter <code class='parameter'>n</code></dt> <dd></dd><dd class='body--doc'><p>Number of lines to get, or all remaining if zero.</p>
da06012008-12-09Henrik Grubbström (Grubba) </dd> <dt class='head--doc'><span id='p-not_all'></span>Parameter <code class='parameter'>not_all</code></dt> <dd></dd><dd class='body--doc'><p>Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.</p>
ab1f522003-07-10Henrik Grubbström (Grubba) </dd></dl>
f7707e2008-03-07Henrik Grubbström (Grubba) <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> <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>, <code class='datatype'>int</code> <code class='argument'>mask</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt>
16892e2014-05-26Martin Nilsson <dd class='body--doc'><p>Same as <code>Stdio.File()-&gt;openat()</code>, but returns an <code>Stdio.FILE</code>
f7707e2008-03-07Henrik Grubbström (Grubba)  object.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Stdio.File()-&gt;openat()</code></p> </dd></dl>
0f4adf2003-07-22Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>pipe</b></span> </dt>
16892e2014-05-26Martin Nilsson <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'>flags</code><b>)</b></code></p></dd>
0f4adf2003-07-22Henrik Grubbström (Grubba)  <dt class='head--doc'>Description</dt>
16892e2014-05-26Martin Nilsson <dd class='body--doc'><p>Same as <code>Stdio.File()-&gt;pipe()</code>, but returns an <code>Stdio.FILE</code> object.</p>
0f4adf2003-07-22Henrik Grubbström (Grubba) </dd>
16892e2014-05-26Martin Nilsson <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Stdio.File()-&gt;pipe()</code></p>
0f4adf2003-07-22Henrik Grubbström (Grubba) </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>printf</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>printf</span>(</b><code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>data</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function does approximately the same as: <code class='expr'><code>write</code>(<code>sprintf</code>(<code>format</code>,@<code>data</code>))</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>write()</code>, <code>sprintf()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
1f918f2002-05-26Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>read</b></span>
1f918f2002-05-26Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>bytes</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>now</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson 
1f918f2002-05-26Martin Nilsson <dt class='head--doc'>Description</dt>
0f4adf2003-07-22Henrik Grubbström (Grubba) <dd class='body--doc'><p>Read <code>bytes</code> (wide-) characters with buffering and support for input conversion.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
b4418a2008-07-14Stephen R. van den Berg <dd class='body--doc'><p><code>Stdio.File()-&gt;read()</code>, <code>set_charset()</code>, <code>unread()</code></p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_charset</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
6b713f2010-10-11Per Hedbor <dd><p><code><code class='datatype'>void</code> <b><span class='method'>set_charset</span>(</b><code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>charset</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Sets the input and output charset of this file to the specified
6b713f2010-10-11Per Hedbor  <code>charset</code>. If <code>charset</code> is 0 or not specified the environment is used to try to detect a suitable charset.</p> <p> The default charset if this function is not called is <tt>"ISO-8859-1"</tt>.</p>
2e26a92008-04-28Henrik Grubbström (Grubba) </dd><dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Consider using one of
e1d7e42008-04-28Henrik Grubbström (Grubba)  ISO-IR-196 (<tt>"\e%G"</tt> - switch to UTF-8 with return) or ISO-IR-190 (<tt>"\e%/G"</tt> - switch to UTF-8 level 1 no return) or ISO-IR-191 (<tt>"\e%/H"</tt> - switch to UTF-8 level 2 no return) or ISO-IR-192 (<tt>"\e%/I"</tt> - switch to UTF-8 level 3 no return) or ISO-IR-193 (<tt>"\e%/J"</tt> - switch to UTF-16 level 1 no return) or ISO-IR-194 (<tt>"\e%/K"</tt> - switch to UTF-16 level 2 no return) or ISO-IR-195 (<tt>"\e%/L"</tt> - switch to UTF-16 level 3 no return)
2e26a92008-04-28Henrik Grubbström (Grubba)  or ISO-IR-162 (<tt>"\e%/@"</tt> - switch to UCS-2 level 1) or ISO-IR-163 (<tt>"\e%/A"</tt> - switch to UCS-4 level 1) or ISO-IR-174 (<tt>"\e%/C"</tt> - switch to UCS-2 level 2) or ISO-IR-175 (<tt>"\e%/D"</tt> - switch to UCS-4 level 2) or ISO-IR-176 (<tt>"\e%/E"</tt> - switch to UCS-2 level 3) or ISO-IR-177 (<tt>"\e%/F"</tt> - switch to UCS-4 level 3) or ISO-IR-178 (<tt>"\e%B"</tt> - switch to UTF-1) automatically to encode wide strings.</p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
429e502008-07-12Stephen R. van den Berg <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
b4418a2008-07-14Stephen R. van den Berg <span class='homogen--name'><b>ungets</b></span>
429e502008-07-12Stephen R. van den Berg </dt>
b4418a2008-07-14Stephen R. van den Berg <dd><p><code><code class='datatype'>void</code> <b><span class='method'>ungets</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd>
429e502008-07-12Stephen R. van den Berg  <dt class='head--doc'>Description</dt>
da06012008-12-09Henrik Grubbström (Grubba) <dd class='body--doc'><p>This function puts a line back in the input buffer. The line
429e502008-07-12Stephen R. van den Berg  can then be read with eg <code>read()</code>, <code>gets()</code> or <code>getchar()</code>.</p> </dd>
b4418a2008-07-14Stephen R. van den Berg <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The string is autoterminated by an extra line-feed.</p> </dd>
429e502008-07-12Stephen R. van den Berg <dt class='head--doc'>See also</dt>
b4418a2008-07-14Stephen R. van den Berg <dd class='body--doc'><p><code>read()</code>, <code>gets()</code>, <code>getchar()</code>, <code>unread()</code></p>
429e502008-07-12Stephen R. van den Berg </dd></dl>
1f918f2002-05-26Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
b4418a2008-07-14Stephen R. van den Berg <span class='homogen--name'><b>unread</b></span>
1f918f2002-05-26Martin Nilsson </dt>
b4418a2008-07-14Stephen R. van den Berg <dd><p><code><code class='datatype'>void</code> <b><span class='method'>unread</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson 
1f918f2002-05-26Martin Nilsson <dt class='head--doc'>Description</dt>
b4418a2008-07-14Stephen R. van den Berg <dd class='body--doc'><p>This function puts a string back in the input buffer. The string
c3fe742003-02-05Martin Nilsson  can then be read with eg <code>read()</code>, <code>gets()</code> or <code>getchar()</code>.</p>
1f918f2002-05-26Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
b4418a2008-07-14Stephen R. van den Berg <dd class='body--doc'><p><code>read()</code>, <code>gets()</code>, <code>getchar()</code>, <code>ungets()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>write</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><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='datatype'>string</code> <code class='argument'>what</code>, <code class='datatype'>mixed</code> ... <code class='argument'>fmt</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Write <code>what</code> with support for output_conversion.</p>
e4e3f32002-04-06Martin Nilsson </dd>
1f918f2002-05-26Martin Nilsson <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>Stdio.File()-&gt;write()</code></p> </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Port</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Handles listening to socket ports. Whenever you need a bound socket that is open and listens for connections you should use this program.</p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>accept</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>File</code> <b><span class='method'>accept</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function completes a connection made from a remote machine to this port. It returns a two-way stream in the form of a clone of
0f4adf2003-07-22Henrik Grubbström (Grubba)  <code>Stdio.File</code>. The new file is by initially set to blocking mode.</p>
50af352002-07-15Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>Stdio.File</code></p>
1f918f2002-05-26Martin Nilsson </dd></dl>
9699552002-03-12Martin Nilsson 
2d83192003-10-30Martin Stjernholm <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>accept</b></span> </dt> <dd><p><code><code class='object unresolved'>Stdio.File</code> <b><span class='method'>accept</span>(</b><b>)</b></code></p></dd>
388ed92005-02-01Martin Stjernholm  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the first connection request waiting for this port and return it as a connected socket.</p> <p> If no connection request is waiting and the port is in nonblocking mode (i.e. an accept callback is installed) then zero is returned. Otherwise this function waits until a connection has arrived.</p>
987bc52009-02-23Henrik Grubbström (Grubba) <p> In Pike 7.8 and later the returned object is created via <code>fd_factory()</code>.</p>
dd17692008-06-13Henrik Grubbström (Grubba) </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>In Pike 7.7 and later the resulting file object will be assigned to the same backend as the port object.</p>
388ed92005-02-01Martin Stjernholm </dd></dl>
2d83192003-10-30Martin Stjernholm 
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>bind</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
b24a442014-09-02Per Hedbor <dd><p><code><code class='datatype'>int</code> <b><span class='method'>bind</span>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>reuse_port</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p>Opens a socket and binds it to port number on the local machine. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument and should typically call <code>accept</code> to establish a connection.</p> <p> If the optional argument <code>ip</code> is given, <code>bind</code> will try to bind
4866bf2012-05-30Chris Angelico  to an interface with that host name or IP number. Omitting this will bind to all available IPv4 addresses; specifying "::" will bind to all IPv4 and IPv6 addresses.</p>
b157ef2014-08-26Per Hedbor <p> If the OS supports TCP_FASTOPEN it is enabled automatically.</p>
b24a442014-09-02Per Hedbor <p> If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true.</p>
388ed92005-02-01Martin Stjernholm </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>1 is returned on success, zero on failure. <code>errno</code> provides further details about the error in the latter case.</p>
50af352002-07-15Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p><code>accept</code>, <code>set_id</code></p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
4856ea2004-05-13H. William Welliver III <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>bind_unix</b></span> </dt>
06eb092004-05-13H. William Welliver III <dd><p><code><code class='datatype'>int</code> <b><span class='method'>bind_unix</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code><b>)</b></code></p></dd>
4856ea2004-05-13H. William Welliver III  <dt class='head--doc'>Description</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p>Opens a Unix domain socket at the given path in the file system. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument and should typically call <code>accept</code> to establish a connection.</p>
4856ea2004-05-13H. William Welliver III </dd> <dt class='head--doc'>Returns</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p>1 is returned on success, zero on failure. <code>errno</code> provides further details about the error in the latter case.</p>
4856ea2004-05-13H. William Welliver III </dd> <dt class='head--doc'>Note</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p>This function is only available on systems that support Unix domain
4856ea2004-05-13H. William Welliver III  sockets.</p> </dd>
8cdefe2009-07-23Henrik Grubbström (Grubba) <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>
4856ea2004-05-13H. William Welliver III <dt class='head--doc'>See also</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p><code>accept</code>, <code>set_id</code></p>
4856ea2004-05-13H. William Welliver III </dd></dl>
e0c2812004-04-04Martin Stjernholm <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'>void</code> <b><span class='method'>close</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Closes the socket.</p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>create</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><b>)</b></code><br>
b27ad92003-04-22Marcus Comstedt <code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code><b>)</b></code><br> <code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code><b>)</b></code><br> <code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>string</code> <code class='argument'>ip</code><b>)</b></code><br>
c3fe742003-02-05Martin Nilsson <code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='argument'>"stdin"</code><b>)</b></code><br> <code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='argument'>"stdin"</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>If the first argument is other than <code class='expr'>"stdin"</code> the arguments will
c3fe742003-02-05Martin Nilsson  be passed to <code>bind()</code>.</p>
84ea4e2003-04-07Martin Nilsson <p> When create is called with <code class='expr'>"stdin"</code> as the first argument, a socket is created out of the file descriptor <code class='expr'>0</code>. This is only
0f4adf2003-07-22Henrik Grubbström (Grubba)  useful if it actually is a socket to begin with.</p>
50af352002-07-15Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>bind</code></p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
388ed92005-02-01Martin Stjernholm <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.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code><b>)</b></code><br> <code><span class='object'>Stdio.Port</span> <span class='class'>Stdio.Port</span><b>(</b><code class='argument'>"stdin"</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>When called with an int or any string except <code class='expr'>"stdin"</code> as first argument, this function does the same as <code>bind()</code> would do with the same arguments.</p> <p> When called with <code class='expr'>"stdin"</code> as argument, a socket is created out of the file descriptor 0. This is only useful if that actually IS a socket to begin with.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>bind</code>, <code>listen_fd</code></p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>errno</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>errno</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p>If the last call done on this port failed, this function will return an integer describing what went wrong. Refer to your unix manual for further information.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
5af4c12009-02-24Henrik Grubbström (Grubba) <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='modifier'>protected</code> <code class='object unresolved'>Fd</code> <b><span class='method'>fd_factory</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Factory creating empty <code>Fd</code> objects.</p> <p> This function is called by <code>accept()</code> when it needs to create a new file.</p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>_port</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='datatype'>inherit _port</span> : <span class='inherit'>_port</span></code></p></dd> </dl>
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>listen_fd</b></span>
1f918f2002-05-26Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>listen_fd</span>(</b><code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
388ed92005-02-01Martin Stjernholm <dd class='body--doc'><p>This function does the same as <code>bind</code>, except that instead of creating a new socket and bind it to a port, it expects the file descriptor <code>fd</code> to be an already open port.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only for the advanced user, and is generally used when sockets are passed to Pike at exec time.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>bind</code>, <code>accept</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
c3fe742003-02-05Martin Nilsson 
e4e3f32002-04-06Martin Nilsson 
50af352002-07-15Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>query_address</b></span>
50af352002-07-15Martin Nilsson </dt>
7cd97e2008-05-12Martin Stjernholm <dd><p><code><code class='datatype'>string</code> <b><span class='method'>query_address</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the address and port of the local socket end-point.</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).</p> <p> If there is some error querying or formatting the address, <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 isn't bound.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
dea86c2004-04-05Martin Stjernholm <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 accept callback.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_backend</code></p> </dd></dl>
1f918f2002-05-26Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>query_id</b></span>
1f918f2002-05-26Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>query_id</span>(</b><b>)</b></code></p></dd>
1f918f2002-05-26Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>This function returns the id for this port. The id is normally the first argument to accept_callback.</p>
1f918f2002-05-26Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_id</code></p> </dd></dl>
e4e3f32002-04-06Martin Nilsson 
dea86c2004-04-05Martin Stjernholm <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 accept callback.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The backend keeps a reference to this object as long as the port is accepting connections, but 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></p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_id</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>set_id</span>(</b><code class='datatype'>mixed</code> <code class='argument'>id</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson 
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function sets the id used for accept_callback by this port. The default id is <code>this_object()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>query_id</code></p> </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.UDP</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>UDP (User Datagram Protocol) handling.</p> </dd></dl>
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>MSG_OOB</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_OOB</code></code></p></dd>
50af352002-07-15Martin Nilsson <dt class='head--fixme'>FIXME</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--fixme'><p>Document this constant.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
50af352002-07-15Martin Nilsson  <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>MSG_PEEK</b></span>
50af352002-07-15Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_PEEK</code></code></p></dd>
50af352002-07-15Martin Nilsson <dt class='head--fixme'>FIXME</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--fixme'><p>Document this constant.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
50af352002-07-15Martin Nilsson 
1f72bf2004-09-18Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>add_membership</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>add_membership</span>(</b><code class='datatype'>string</code> <code class='argument'>group</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>address</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt>
402d182013-07-04Henrik Grubbström (Grubba) <dd class='body--doc'><p>Join a multicast group.</p> </dd> <dt class='head--doc'><span id='p-group'></span>Parameter <code class='parameter'>group</code></dt> <dd></dd><dd class='body--doc'><p><code>group</code> contains the address of the multicast group the application wants to join. It must be a valid multicast address.</p> </dd> <dt class='head--doc'><span id='p-address'></span>Parameter <code class='parameter'>address</code></dt> <dd></dd><dd class='body--doc'><p><code>address</code> is the address of the local interface with which the system should join to the multicast group. If not provided the system will select an appropriate interface.</p> <p> See also the Unix man page for setsocketopt IPPROTO_IP IP_ADD_MEMBERSHIP
3683582013-07-06Jonas Walldén  and IPPROTO_IPV6 IPV6_JOIN_GROUP.</p>
402d182013-07-04Henrik Grubbström (Grubba) </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The <code>address</code> parameter is currently not supported for IPv6.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function did not support IPv6 in Pike 7.8 and earlier.</p>
8831a42004-09-18Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
402d182013-07-04Henrik Grubbström (Grubba) <dd class='body--doc'><p><code>drop_membership()</code></p>
1f72bf2004-09-18Martin Nilsson </dd></dl>
1f918f2002-05-26Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>bind</b></span>
1f918f2002-05-26Martin Nilsson </dt>
ced3352013-09-03Tobias S. Josefowitz <dd><p><code><code class='object unresolved'>UDP</code> <b><span class='method'>bind</span>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>address</code>, <code class='datatype'>string</code>|<code class='datatype'>bool</code> <code class='argument'>no_reuseaddr</code><b>)</b></code></p></dd>
c3fe742003-02-05Martin Nilsson 
1f918f2002-05-26Martin Nilsson <dt class='head--doc'>Description</dt>
97fa202008-05-30Martin Stjernholm <dd class='body--doc'><p>Binds a port for receiving or transmitting UDP.</p>
1f72bf2004-09-18Martin Nilsson </dd>
ced3352013-09-03Tobias S. Josefowitz <dt class='head--doc'><span id='p-no_reuseaddr'></span>Parameter <code class='parameter'>no_reuseaddr</code></dt> <dd></dd><dd class='body--doc'><p>If set to <code class='expr'>1</code>, Pike will not set the <code class='expr'>SO_REUSEADDR</code> option on the UDP port.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p><code class='expr'>SO_REUSEADDR</code> is never applied when binding a random port (<code class='expr'>bind(0)</code>).</p> <p> In general, <code class='expr'>SO_REUSEADDR</code> is not desirable on UDP ports. Unless used for receiving multicast, be sure to never bind a non-random port without setting <code class='expr'>no_reuseaddr</code> to <code class='expr'>1</code>.</p> </dd>
1f72bf2004-09-18Martin Nilsson <dt class='head--doc'>Throws</dt> <dd class='body--doc'><p>Throws error when unable to bind port.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
c3fe742003-02-05Martin Nilsson 
8ae0032003-10-29Henrik Grubbström (Grubba) <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'>bool</code> <b><span class='method'>close</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Closes an open UDP port.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This method was introduced in Pike 7.5.</p> </dd></dl>
c628122002-10-19Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>connect</b></span>
c628122002-10-19Martin Nilsson </dt>
b27ad92003-04-22Marcus Comstedt <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>connect</span>(</b><code class='datatype'>string</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code><b>)</b></code></p></dd>
c628122002-10-19Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Establish an UDP connection.</p> <p> This function connects an UDP socket previously created with <code>Stdio.UDP()</code> to a remote socket. The <code>address</code> is the IP name or number for the remote machine.</p> </dd> <dt class='head--doc'>Returns</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>If the socket is in nonblocking mode, you have to wait for a write or close callback before you know if the connection failed or not.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>bind()</code>, <code>query_address()</code></p>
c628122002-10-19Martin Nilsson </dd></dl>
8831a42004-09-18Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>drop_membership</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>drop_membership</span>(</b><code class='datatype'>string</code> <code class='argument'>group</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>address</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Leave a multicast group.</p> </dd>
402d182013-07-04Henrik Grubbström (Grubba) <dt class='head--doc'><span id='p-group'></span>Parameter <code class='parameter'>group</code></dt> <dd></dd><dd class='body--doc'><p><code>group</code> contains the address of the multicast group the application wants to join. It must be a valid multicast address.</p> </dd> <dt class='head--doc'><span id='p-address'></span>Parameter <code class='parameter'>address</code></dt> <dd></dd><dd class='body--doc'><p><code>address</code> is the address of the local interface with which the system should join to the multicast group. If not provided the system will select an appropriate interface.</p> <p> See also the Unix man page for setsocketopt IPPROTO_IP IP_DROP_MEMBERSHIP
3683582013-07-06Jonas Walldén  and IPPROTO_IPV6 IPV6_LEAVE_GROUP.</p>
402d182013-07-04Henrik Grubbström (Grubba) </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The <code>address</code> parameter is currently not supported for IPv6.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function did not support IPv6 in Pike 7.8 and earlier.</p> </dd>
8831a42004-09-18Martin Nilsson <dt class='head--doc'>See also</dt>
402d182013-07-04Henrik Grubbström (Grubba) <dd class='body--doc'><p><code>add_membership()</code></p>
8831a42004-09-18Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>enable_broadcast</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>enable_broadcast</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Set the broadcast flag. If enabled then sockets receive packets sent to a broadcast address and they are allowed to send packets to a broadcast address.</p> </dd> <dt class='head--doc'>Returns</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This is normally only avalable to root users.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
1f72bf2004-09-18Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>enable_multicast</b></span> </dt> <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>enable_multicast</span>(</b><code class='datatype'>string</code> <code class='argument'>reply_address</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt>
402d182013-07-04Henrik Grubbström (Grubba) <dd class='body--doc'><p>Set the local device for a multicast socket.</p> </dd> <dt class='head--doc'><span id='p-reply_address'></span>Parameter <code class='parameter'>reply_address</code></dt> <dd></dd><dd class='body--doc'><p>Local address that should appear in the multicast packets.</p> <p> See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF and IPPROTO_IPV6 IPV6_MULTICAST_IF.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function did not support IPv6 in Pike 7.8.</p>
1f72bf2004-09-18Martin Nilsson </dd></dl>
c628122002-10-19Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>errno</b></span>
c628122002-10-19Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>errno</span>(</b><b>)</b></code></p></dd>
c628122002-10-19Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns the error code for the last command on this object. Error code is normally cleared when a command is successful.</p>
c628122002-10-19Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>get_type</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) <b><span class='method'>get_type</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns socket type and protocol family.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
50af352002-07-15Martin Nilsson 
c3fe742003-02-05Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>UDP</b></span> </dt>
634a9a2013-06-11Martin Nilsson <dd><p><code><span class='datatype'>inherit _Stdio.UDP</span> : <span class='inherit'>UDP</span></code></p></dd>
c3fe742003-02-05Martin Nilsson </dl>
c628122002-10-19Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>query_address</b></span>
c628122002-10-19Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>string</code> <b><span class='method'>query_address</span>(</b><b>)</b></code></p></dd>
c628122002-10-19Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns the local address of a socket on the form "x.x.x.x port". If this file is not a socket, not connected or some other error occurs, zero is returned.</p>
c628122002-10-19Martin Nilsson </dd></dl>
dea86c2004-04-05Martin Stjernholm <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 read callback.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>set_backend</code></p> </dd></dl>
ac9c552013-12-06Henrik Grubbström (Grubba) <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>Gets the file descriptor for this UDP port.</p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>read</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) <b><span class='method'>read</span>(</b><b>)</b></code><br> <code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>flag</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Read from the UDP socket.</p> <p> Flag <code>flag</code> is a bitfield, 1 for out of band data and 2 for peek</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>mapping(string:int|string) in the form ([
70becb2003-03-12Marcus Agehall  "data" : string received data "ip" : string received from this ip
c3fe742003-02-05Martin Nilsson  "port" : int ...and this port ])</p> </dd> <dt class='head--doc'>See also</dt>
9c49d82009-02-10Henrik Grubbström (Grubba) <dd class='body--doc'><p><code>set_read_callback()</code>, <code>MSG_OOB</code>, <code>MSG_PEEK</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>send</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
b27ad92003-04-22Marcus Comstedt <dd><p><code><code class='datatype'>int</code> <b><span class='method'>send</span>(</b><code class='datatype'>string</code> <code class='argument'>to</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>message</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>send</span>(</b><code class='datatype'>string</code> <code class='argument'>to</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>message</code>, <code class='datatype'>int</code> <code class='argument'>flags</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
5819482006-11-10Martin Stjernholm <dd class='body--doc'><p>Send data to a UDP socket. The recipient address will be <code>to</code>
c3fe742003-02-05Martin Nilsson  and port will be <code>port</code>.</p> <p> Flag <code>flag</code> is a bitfield, 1 for out of band data and 2 for don't route flag.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The number of bytes that were actually written.</p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
dea86c2004-04-05Martin Stjernholm <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 read callback.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The backend keeps a reference to this object as long as there can be calls to the read callback, but 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></p> </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_blocking</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>object</code> <b><span class='method'>set_blocking</span>(</b><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Sets this object to be blocking.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
9699552002-03-12Martin Nilsson 
e4e3f32002-04-06Martin Nilsson 
670ccc2013-03-19Kevin O'Rourke <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>
ac9c552013-12-06Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_fd</b></span> </dt> <dd><p><code><code class='object unresolved'>UDP</code> <b><span class='method'>set_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>Use the file descriptor <code>fd</code> for UDP.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>bind</code></p> </dd></dl>
1f72bf2004-09-18Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_multicast_ttl</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>set_multicast_ttl</span>(</b><code class='datatype'>int</code> <code class='argument'>ttl</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt>
402d182013-07-04Henrik Grubbström (Grubba) <dd class='body--doc'><p>Set the time-to-live value of outgoing multicast packets for this socket.</p> </dd> <dt class='head--doc'><span id='p-ttl'></span>Parameter <code class='parameter'>ttl</code></dt> <dd></dd><dd class='body--doc'><p>The number of router hops sent multicast packets should survive.</p> <p> It is very important for multicast packets to set the smallest TTL possible. The default before calling this function is 1 which means that multicast packets don't leak from the local network unless the user program explicitly requests it.</p> <p> See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL and IPPROTO_IPV6 IPV6_MULTICAST_HOPS.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function did not support IPv6 in Pike 7.8 and earlier.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>add_membership()</code></p>
1f72bf2004-09-18Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_nonblocking</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>UDP</code> <b><span class='method'>set_nonblocking</span>(</b><b>)</b></code><br> <code><code class='object unresolved'>UDP</code> <b><span class='method'>set_nonblocking</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>), <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>read_cb</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Set this object to nonblocking mode.</p> <p> If <code>read_cb</code> and <code>extra_args</code> are specified, they will be passed on to <code>set_read_callback()</code>.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The called object.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
1f918f2002-05-26Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_read_callback</b></span>
1f918f2002-05-26Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>UDP</code> <b><span class='method'>set_read_callback</span>(</b><code class='datatype'>function</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>), <code class='datatype'>mixed</code> ... :<code class='datatype void'>void</code>) <code class='argument'>read_cb</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code><b>)</b></code></p></dd>
1f918f2002-05-26Martin Nilsson 
e4e3f32002-04-06Martin Nilsson <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>The <code>read_cb</code> function will receive a mapping similar to the mapping returned by <code>read()</code>:</p> <table class='box'><tr><td><code><code class='key'>"data"</code> : <code class='datatype'>string</code></code></td><td><p>Received data.</p> </td></tr> <tr><td><code><code class='key'>"ip"</code> : <code class='datatype'>string</code></code></td><td><p>Data was sent from this IP.</p> </td></tr> <tr><td><code><code class='key'>"port"</code> : <code class='datatype'>int</code></code></td><td><p>Data was sent from this port.</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The called object.</p>
c628122002-10-19Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p><code>read()</code></p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
1f918f2002-05-26Martin Nilsson 
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>set_type</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
1f72bf2004-09-18Martin Nilsson <dd><p><code><code class='object unresolved'>UDP</code> <b><span class='method'>set_type</span>(</b><code class='datatype'>int</code> <code class='argument'>sock_type</code><b>)</b></code><br> <code><code class='object unresolved'>UDP</code> <b><span class='method'>set_type</span>(</b><code class='datatype'>int</code> <code class='argument'>sock_type</code>, <code class='datatype'>int</code> <code class='argument'>family</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Sets socket type and protocol family.</p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
c628122002-10-19Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>wait</b></span>
c628122002-10-19Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>wait</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code><b>)</b></code></p></dd>
c628122002-10-19Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Check for data and wait max. <code>timeout</code> seconds.</p>
c628122002-10-19Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Returns</dt>
84ea4e2003-04-07Martin Nilsson <dd class='body--doc'><p>Returns <code class='expr'>1</code> if data are ready, <code class='expr'>0</code> (zero) otherwise.</p>
c628122002-10-19Martin Nilsson </dd></dl>
c3fe742003-02-05Martin Nilsson </dd></dl><dl><dt><h2 class='header'>Module <b class='ms datatype'>Stdio.Terminfo</b></h2> </dt><dd>
c628122002-10-19Martin Nilsson 
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getFallbackTerm</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='modifier'>protected</code> <code class='object unresolved'>Termcap</code> <b><span class='method'>getFallbackTerm</span>(</b><code class='datatype'>string</code> <code class='argument'>term</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns an object describing the fallback terminal for the terminal <code>term</code>. This is usually equvivalent to <code>Stdio.Terminfo.getTerm("dumb")</code>.</p>
c628122002-10-19Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Stdio.Terminfo.getTerm</p>
c628122002-10-19Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getTerm</b></span>
c628122002-10-19Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>Termcap</code> <b><span class='method'>getTerm</span>(</b><code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>term</code><b>)</b></code></p></dd>
c628122002-10-19Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns an object describing the terminal term. If term is not specified, it will default to <code>getenv("TERM")</code> or if that fails to "dumb".</p> <p> Lookup of terminal information will first be done in the systems terminfo database, and if that fails in the termcap database. If neither database exists, a hardcoded entry for "dumb" will be used.</p>
c628122002-10-19Martin Nilsson </dd> <dt class='head--doc'>See also</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Stdio.Terminfo.getTerminfo, Stdio.Terminfo.getTermcap, Stdio.getFallbackTerm</p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
c3fe742003-02-05Martin Nilsson 
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getTermcap</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>Termcap</code> <b><span class='method'>getTermcap</span>(</b><code class='datatype'>string</code> <code class='argument'>term</code><b>)</b></code></p></dd>
932a632002-10-25Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns the terminal description object for <code>term</code> from the systems termcap database. Returns 0 if not found.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p>Stdio.Terminfo.getTerm, Stdio.Terminfo.getTerminfo</p>
932a632002-10-25Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getTerminfo</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>Terminfo</code> <b><span class='method'>getTerminfo</span>(</b><code class='datatype'>string</code> <code class='argument'>term</code><b>)</b></code></p></dd>
932a632002-10-25Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Returns the terminal description object for <code>term</code> from the systems terminfo database. Returns 0 if not found.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p>Stdio.Terminfo.getTerm, Stdio.Terminfo.getTermcap</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
6f7a292003-06-02Martin Stjernholm  <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>is_tty</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>is_tty</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns 1 if <code>Stdio.stdin</code> is connected to an interactive terminal that can handle backspacing, carriage return without linefeed, and the like.</p> </dd></dl>
b361662010-06-05Henrik Grubbström (Grubba) <dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Terminfo.MetaTerminfoDB</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p><code>TerminfoDB</code> that merges several directorys.</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.Terminfo.MetaTerminfoDB</span> <span class='class'>Stdio.Terminfo.MetaTerminfoDB</span><b>(</b><code class='datatype'>array</code>(<code class='object unresolved'>TerminfoDB</code>|<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>dbs</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Create a new Meta <code>TerminfoDB</code>.</p> </dd> <dt class='head--doc'><span id='p-dbs'></span>Parameter <code class='parameter'>dbs</code></dt> <dd></dd><dd class='body--doc'><p>Array with elements in priority order. Elements may be either</p> <table class='box'><tr><td><code><code class='object unresolved'>TerminfoDB</code></code></td><td><p>An active <code>TerminfoDB</code>.</p> </td></tr> <tr><td><code><code class='datatype'>string</code></code></td><td><p>A directory that may exist and contain a terminfo database.</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>If the resulting set of <code>TerminfoDB</code>'s is empty, the object will be destructed.</p> </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Terminfo.Termcap</b></h2>
c3fe742003-02-05Martin Nilsson </dt><dd><dl class='group--doc'>
1f918f2002-05-26Martin Nilsson <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Termcap terminal description object.</p>
1f918f2002-05-26Martin Nilsson </dd></dl>
e4e3f32002-04-06Martin Nilsson 
1f918f2002-05-26Martin Nilsson <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Variable</span> <span class='homogen--name'><b>aliases</b></span>
1f918f2002-05-26Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) Stdio.Terminfo.Termcap.<b><span class='variable'>aliases</span></b></code></p></dd> </dl>
9699552002-03-12Martin Nilsson  <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>create</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='object'>Stdio.Terminfo.Termcap</span> <span class='class'>Stdio.Terminfo.Termcap</span><b>(</b><code class='datatype'>string</code> <code class='argument'>cap</code>, <code class='object unresolved'>TermcapDB</code>|<code class='datatype'>void</code> <code class='argument'>tcdb</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>maxrecurse</code><b>)</b></code></p></dd> </dl>
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>TermMachine</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='datatype'>inherit TermMachine</span> : <span class='inherit'>TermMachine</span></code></p></dd> </dl>
9699552002-03-12Martin Nilsson  <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>tputs</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>string</code> <b><span class='method'>tputs</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd>
9699552002-03-12Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Put termcap string</p>
50af352002-07-15Martin Nilsson </dd></dl>
b361662010-06-05Henrik Grubbström (Grubba) </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Terminfo.TermcapDB</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Termcap database</p> </dd></dl></dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Terminfo.Terminfo</b></h2>
50af352002-07-15Martin Nilsson </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Terminfo terminal description object</p>
e4e3f32002-04-06Martin Nilsson </dd></dl>
9699552002-03-12Martin Nilsson  <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Variable</span> <span class='homogen--name'><b>aliases</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) Stdio.Terminfo.Terminfo.<b><span class='variable'>aliases</span></b></code></p></dd> </dl>
9699552002-03-12Martin Nilsson  <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>create</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='object'>Stdio.Terminfo.Terminfo</span> <span class='class'>Stdio.Terminfo.Terminfo</span><b>(</b><code class='datatype'>string</code> <code class='argument'>filename</code><b>)</b></code></p></dd> </dl>
e4e3f32002-04-06Martin Nilsson  <hr /> <dl class='group--doc'>
c3fe742003-02-05Martin Nilsson <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>TermMachine</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='datatype'>inherit TermMachine</span> : <span class='inherit'>TermMachine</span></code></p></dd> </dl>
9699552002-03-12Martin Nilsson  <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>tputs</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>string</code> <b><span class='method'>tputs</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
9699552002-03-12Martin Nilsson </dd></dl>
b361662010-06-05Henrik Grubbström (Grubba) </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Terminfo.TerminfoDB</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Terminfo database for a single directory.</p> </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.Readline</b></h2>
c3fe742003-02-05Martin Nilsson </dt><dd>
9699552002-03-12Martin Nilsson  <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>add_to_kill_ring</b></span>
9699552002-03-12Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>add_to_kill_ring</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>create</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><span class='object'>Stdio.Readline</span> <span class='class'>Stdio.Readline</span><b>(</b><code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>infd</code>, <code class='datatype'>object</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>interm</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>outfd</code>, <code class='datatype'>object</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>outterm</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Creates a Readline object, that takes input from <code>infd</code> and has output on <code>outfd</code>.</p>
50af352002-07-15Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'><span id='p-infd'></span>Parameter <code class='parameter'>infd</code></dt>
d5f90f2003-06-27Martin Nilsson <dd></dd><dd class='body--doc'><p>Defaults to <code>Stdio.stdin</code>.</p>
c3fe742003-02-05Martin Nilsson </dd> <dt class='head--doc'><span id='p-interm'></span>Parameter <code class='parameter'>interm</code></dt> <dd></dd><dd class='body--doc'><p>Defaults to <code>Stdio.Terminfo.getTerm()</code>.</p> </dd> <dt class='head--doc'><span id='p-outfd'></span>Parameter <code class='parameter'>outfd</code></dt> <dd></dd><dd class='body--doc'><p>Defaults to <code>infd</code>, unless <code>infd</code> is 0, in which case <code>outfd</code> defaults to <code>Stdio.stdout</code>.</p> </dd> <dt class='head--doc'><span id='p-outterm'></span>Parameter <code class='parameter'>outterm</code></dt> <dd></dd><dd class='body--doc'><p>Defaults to <code>interm</code>.</p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>delete</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>delete</span>(</b><code class='datatype'>int</code> <code class='argument'>p1</code>, <code class='datatype'>int</code> <code class='argument'>p2</code><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
e4e3f32002-04-06Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'>
50af352002-07-15Martin Nilsson <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>delta_history</b></span>
e4e3f32002-04-06Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>delta_history</span>(</b><code class='datatype'>int</code> <code class='argument'>d</code><b>)</b></code></p></dd>
e4e3f32002-04-06Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Changes the line to a line from the history <code>d</code> steps from the current entry (0 being the current line, negative values older, and positive values newer).</p>
50af352002-07-15Martin Nilsson </dd>
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Only effective if you have a history object.</p>
78c3e22003-01-03Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>edit</b></span>
78c3e22003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>string</code> <b><span class='method'>edit</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>local_prompt</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>attrs</code><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
78c3e22003-01-03Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>enable_history</b></span>
78c3e22003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>enable_history</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='object unresolved'>History</code>|<code class='datatype'>int</code> <code class='argument'>hist</code><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
78c3e22003-01-03Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>eof</b></span>
78c3e22003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>void</code> <b><span class='method'>eof</span>(</b><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
78c3e22003-01-03Martin Nilsson </dd></dl>
3a44ef2003-01-03Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>get_history</b></span>
3a44ef2003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>History</code> <b><span class='method'>get_history</span>(</b><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
3a44ef2003-01-03Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>get_input_controller</b></span>
3a44ef2003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>InputController</code> <b><span class='method'>get_input_controller</span>(</b><b>)</b></code></p></dd>
3a44ef2003-01-03Martin Nilsson 
c3fe742003-02-05Martin Nilsson <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>get current input control object</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Terminal input controller object</p>
3a44ef2003-01-03Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>get_output_controller</b></span>
3a44ef2003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='object unresolved'>OutputController</code> <b><span class='method'>get_output_controller</span>(</b><b>)</b></code></p></dd>
3a44ef2003-01-03Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>get current output control object</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Terminal output controller object</p>
3a44ef2003-01-03Martin Nilsson </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>get_prompt</b></span>
3a44ef2003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>string</code> <b><span class='method'>get_prompt</span>(</b><b>)</b></code></p></dd>
3a44ef2003-01-03Martin Nilsson  <dt class='head--doc'>Description</dt>
c3fe742003-02-05Martin Nilsson <dd class='body--doc'><p>Return the current prompt string.</p>
3a44ef2003-01-03Martin Nilsson </dd></dl>
c3fe742003-02-05Martin Nilsson 
7867992003-01-03Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getcursorpos</b></span>
7867992003-01-03Martin Nilsson </dt>
c3fe742003-02-05Martin Nilsson <dd><p><code><code class='datatype'>int</code> <b><span class='method'>getcursorpos</span>(</b><b>)</b></code></p></dd> <dt class='head--fixme'>FIXME</dt> <dd class='body--fixme'><p>Document this function</p>
7867992003-01-03Martin Nilsson </dd></dl>
3a44ef2003-01-03Martin Nilsson <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
c3fe742003-02-05Martin Nilsson <span class='homogen--name'><b>getmark</b></span>
3a44ef2003-01-03Martin Nilsson </dt>