Diff of autodoc.git/traditional_manual/chapter_9.html (3ad5d54e2741fe3379b19b0002235702869d2a1a » b24a44e332583999ceefb2a2c51e94d67ba9d477)

autodoc.git/traditional_manual/chapter_9.html:2458: <dd class='body--doc'>In Pike 7.7 and later the resulting file object will be assigned to the same backend as the port object. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method bind </dt> - <dd><code><code class='datatype'>int</code> bind(<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></dd> + <dd><code><code class='datatype'>int</code> bind(<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>)</code></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'>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. If the optional argument <code>ip</code> is given, <code>bind</code> will try to bind 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. If the OS supports TCP_FASTOPEN it is enabled automatically. - + If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true. </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'>1 is returned on success, zero on failure. <code>errno</code> provides further details about the error in the latter case. </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>accept</code>, <code>set_id</code> </dd></dl>
autodoc.git/traditional_manual/chapter_9.html:6080: <dl class='group--doc'> <dt class='head--type'>Inherit Fd </dt> <dd><code>inherit Fd : Fd</code></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'>Fake inherit to propagate the documentation from <code>_Stdio.Fd</code>. </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.IOBuffer</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>A buffer to use as input or buffering when doing I/O. It is - similar to <code>String.Buffer</code>, but can only contain 8bit data and is - designed for protocol parsing. It is optimized for reading from - the beginning and adding to the end, and will try to minimize the - amount of data copying that is done. - It can also directly read from and write to filedescriptors if so - desired. This eliminates at least one memory copy. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _sizeof - </dt> - <dd><code><code class='datatype'>int</code> sizeof( Stdio.IOBuffer arg )</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the buffer size, in bytes. - This is how much you can read from the buffer until it runs out of data. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[] - </dt> - <dd><code><code class='datatype'>int</code> res = <code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ]</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the character at the specified offset. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[]= - </dt> - <dd><code><code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ] = <code class='class'>char</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the character at the specified offset to <code>char</code>. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add - </dt> - <dd><code><code class='datatype'>void</code> add(<code class='datatype'>string(8bit)</code>|<code class='datatype'>int(8bit)</code> ... <code class='argument'>data</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add the items in data one at a time. - Integers are assumed to be 8bit numbers (characters) - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_byte - Method - add_int8 - </dt> - <dd><code><code class='datatype'>int</code> add_byte(<code class='datatype'>int(8bit)</code>)</code> - <code><code class='datatype'>int</code> add_int8(<code class='datatype'>int(8bit)</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a single byte to the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_hstring - </dt> - <dd><code><code class='datatype'>void</code> add_hstring(<code class='datatype'>string(8bit)</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds length/data for <code>data</code> to the buffer. - This is identical to <code>sprintf("%"+size_size+"H",data)</code> but - significantly faster. - <code>size_size</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int - </dt> - <dd><code><code class='datatype'>int</code> add_int(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a generic integer to the buffer as an (width*8)bit - network byteorder number. - <code>width</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int16 - Method - add_short - </dt> - <dd><code><code class='datatype'>int</code> add_int16(<code class='datatype'>int(16bit)</code>)</code> - <code><code class='datatype'>int</code> add_short(<code class='datatype'>int(16bit)</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add a 16-bit network byte order value to the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int32 - </dt> - <dd><code><code class='datatype'>int</code> add_int32(<code class='datatype'>int</code> <code class='argument'>i</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a 32 bit network byte order value to the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - cast - </dt> - <dd><code>(<code class='datatype'>string</code>)Stdio.IOBuffer()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert the buffer to a string. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This only works for buffers whose length is less than 0x7fffffff. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - clear - </dt> - <dd><code><code class='datatype'>void</code> clear()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Clear the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - consume - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> consume(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Discard the first <code>n</code> bytes from the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.IOBuffer Stdio.IOBuffer(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>len</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create a new buffer of the given size. - The buffer will grow if needed, so the length is only the - initial size. - The default initial size is 4K - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.IOBuffer Stdio.IOBuffer(<code class='datatype'>string(8bit)</code> <code class='argument'>x</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create a new buffer with the contents of the given - string. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This will not copy the string data, instead data will - be read from the string until it needs to be modified, so the - buffer creation is fast regardless of the length of the - string. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - lock - </dt> - <dd><code><code class='datatype'>object</code> lock()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Makes this buffer read only until the returned object is released. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This currently simply returns a 0-length subbuffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - match - </dt> - <dd><code><code class='datatype'>mixed</code> match(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from the beginning of the buffer to match the - specifed format, then return the match. - The non-matching data will be left in the buffer. - This function is very similar to <code>sscanf</code>, but the - result is the sum of the matches. Most useful to match - a single value. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>// get the next whitespace separated word from the buffer. - buffer->match("%*[ \t\r\n]%*[^ \t\r\n]"); - </code></pre></pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read all data from the buffer. - If there is not enough data available this returns 0. - This is basically equivalent to (string)buffer, but it also - removes the data from the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read <code>bytes</code> bytes of data from the buffer. - If there is not enough data available this returns 0. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_buffer - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>read</code>, but returns the result as an IOBuffer. - No data is copied unless <code>copy</code> is specified and true, the new buffer - points into the old one. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As long as the subbuffer exists no data can be added to the main buffer. - Usually this is OK, since it often represents something that - should be parsed before the next whatever is extracted from - the buffer, but do take care. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hbuffer - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>read_hstring</code>, but returns the result as an IOBuffer. - No data is copied unless <code>copy</code> is specified and true, the new - buffer points into the old one. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As long as the subbuffer exists no data can be added to the - main buffer. - Usually this is OK, since it often represents something that - should be parsed before the next whatever is extracted from - the buffer, but do take care. - If you need to unlink the new buffer after it has been - created, call <code>trim</code> in it. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hstring - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read_hstring(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Identical in functionality to <code>read</code>(<code>read_number</code>(<code>n</code>)) but - faster. - Read a network byte order number of size n*8 bits, then return the - indicated number of bytes as a string. - If there is not enough data available return 0. - Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int - </dt> - <dd><code><code class='datatype'>int</code> read_int(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a network (if n is positive) or little endian (if n is - negative) byte order unsigned number of size n*8 bits, then - return it. - Will return -1 if there is not enough buffer space available - unless error mode is set to throw errors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_json - </dt> - <dd><code><code class='datatype'>mixed</code> read_json(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>require_whitespace_separator</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a single JSON expression from the buffer and return it. - If <code>require_whitespace_separator</code> is true there must be a whitespace - after each json value (as an example, newline or space). - The JSON is assumed to be utf-8 encoded. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>UNDEFINED if no data is available to read. - The read value otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unless whitespaces are required this function only really work correctly - with objects, arrays and strings. - There is really no way to see where one value starts and the other ends - for most other cases - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_error_mode - </dt> - <dd><code><code class='datatype'>void</code> set_error_mode(<code class='datatype'>int</code> <code class='argument'>m</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the error mode of this buffer to <code>m</code>. - If true operations that would normally return 0 (like trying to read too much) - will instead thrown an error. - This is useful when parsing received data, you do not have to - verify that each and every read operation suceeds. - However, the non-error mode is more useful when checking to see - if a packet/segment/whatever has arrived. - The thrown error object will have the constant buffer_error set - to a non-false value. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>void read_callback(int i, string new_data) - { - inbuffer->add( new_data ); - - while( IOBuffer packet = inbuffer->read_hbuffer(2) ) - { - packet->set_error_mode(Buffer.THROW_ERROR); - if( mixed e = catch( handle_packet( packet ) ) ) - if( e->buffer_error ) - protocol_error(); // illegal data in packet - else - throw(e); // the other code did something bad - } - } - - void handle_packet( IOBuffer pack ) - { - switch( pack->read_int8() ) - { - ... - case HEADER_FRAME: - int num_headers = pack->read_int32(); - for( int i = 0; i<num_headers; i++ ) - headers[pack->read_hstring(2)] = pack->read_hstring(2); - ... - } - } - </code></pre></pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sprintf - </dt> - <dd><code><code class='datatype'>int</code> sprintf(<code class='object unresolved'>strict_sprintf_format</code> <code class='argument'>format</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Appends the output from <code>sprintf</code> at the end of the buffer. - This is somewhat faster than add(sprintf(...)) since no - intermediate string is created. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sscanf - </dt> - <dd><code><code class='datatype'>array</code> sscanf(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from the beginning of the buffer to match the - specifed format, then return an array with the matches. - The non-matching data will be left in the buffer. - See <code>array_sscanf</code> for more information. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - trim - </dt> - <dd><code><code class='datatype'>void</code> trim()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Frees unused memory. - Note that calling this function excessively will slow things - down, since the data often has to be copied. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function could possibly throw an out-of-memory error - if the realloc fails to find a new (smaller) memory area. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - unread - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> unread(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Rewind the buffer <code>n</code> bytes. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns how many more bytes of buffer is - available to rewind, or -1 on error. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unless you add new data to the buffer using any of the add - functions you can always rewind. - You can call <code>undread(0)</code> to see how much. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - write_to - </dt> - <dd><code><code class='datatype'>void</code> write_to(<code class='object unresolved'>Stdio.Strem</code> <code class='argument'>f</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write data from the buffer to the indicated file. - Will return the number of bytes that were successfully written. - </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'>The Stdio.NonblockingStream API. This class exists purely for typing reasons. Use in types in place of <code>Stdio.File</code> where nonblocking and/or blocking stream-oriented I/O is done with the object. </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>Stream</code>, <code>BlockFile</code>, <code>File</code>, <code>FILE</code>

autodoc.git / traditional_manual / chapter_9.html