Log of autodoc.git/traditional_manual/chapter

2020-05-13

2020-05-13 13:27:50 by Henrik Grubbström (Grubba) <grubba@grubba.org>

bf9cb30d7c536816b899b70d862e74cd7ebc02a0 (6677 lines) (+1277/-5400) ^{[

Show
| Annotate

]}
Branch: master

Documentation [Stdio]: Document low-level classes.

1760: <hr /> <dl class='group--doc'> <dt class='head--type'>Method - accept - </dt> - <dd><code><code class='object unresolved'>Stdio.File</code> accept()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the first connection request waiting for this port and return - it as a connected socket. - 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. - In Pike 7.8 and later the returned object is created via <code>fd_factory()</code>. - </dd> - <dt class='head--doc'>Note</dt> - <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 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> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - bind_unix - </dt> - <dd><code><code class='datatype'>int</code> bind_unix(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - </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'>Note</dt> - <dd class='body--doc'>This function is only available on systems that support Unix domain - sockets. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code>path</code> had a quite restrictive length limit (~100 characters) - prior to Pike 7.8.334. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>accept</code>, <code>set_id</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - close - </dt> - <dd><code><code class='datatype'>void</code> close()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Closes the socket. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method + create </dt> <dd><code>Stdio.Port Stdio.Port()</code> 
1880: <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.Port Stdio.Port(<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> - <code>Stdio.Port Stdio.Port(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - 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, and is equivalent to creating a port and - initializing it with <code>listen_fd</code>(0). - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code>, <code>listen_fd</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - errno - </dt> - <dd><code><code class='datatype'>int</code> errno()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method + fd_factory </dt> <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>Fd</code> fd_factory()</code></dd>
1939: </dt> <dd><code>inherit _port : _port</code></dd> </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - listen_fd - </dt> - <dd><code><code class='datatype'>int</code> listen_fd(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function is only for the advanced user, and is generally used - when sockets are passed to Pike at exec time. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code>, <code>accept</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_address - </dt> - <dd><code><code class='datatype'>string</code> query_address()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the address and port of the local socket end-point. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns the address and port of a socket end-point - on the form <code class='expr'>"x.x.x.x port"</code> (IPv4) or - <code class='expr'>"x:x:x:x:x:x:x:x port"</code> (IPv6). - 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. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error is thrown if the socket isn't bound. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_backend - </dt> - <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the backend used for the accept callback. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_backend</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_fd - </dt> - <dd><code><code class='datatype'>int</code> query_fd()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the file descriptor number associated with this object. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_id - </dt> - <dd><code><code class='datatype'>mixed</code> query_id()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function returns the id for this port. The id is normally the - first argument to accept_callback. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_id</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_backend - </dt> - <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the backend used for the accept callback. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>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. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_backend</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_id - </dt> - <dd><code><code class='datatype'>mixed</code> set_id(<code class='datatype'>mixed</code> <code class='argument'>id</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function sets the id used for accept_callback by this port. - The default id is <code>this_object()</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In Pike 8.0 and earlier the default value was <code class='expr'>0</code> (zero) - (even though it was documented as above). - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_id</code> - </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.UDP</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>
2074: <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - MSG_OOB - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_OOB</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Flag to specify to <code>read()</code> to read out of band packets. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - MSG_PEEK - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_PEEK</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Flag to specify to <code>read()</code> to cause it to not remove the packet - from the input buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Variable - _fd - </dt> - <dd><code><code class='object unresolved'>UDP</code> Stdio.UDP._fd</code></dd> - - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Read only - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_membership - </dt> - <dd><code><code class='datatype'>int</code> add_membership(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Join a multicast group. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>group</code></dt> - <dd></dd><dd class='body--doc'><code>group</code> contains the address of the multicast group the - application wants to join. It must be a valid multicast address. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'><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. - See also the Unix man page for setsocketopt IPPROTO_IP IP_ADD_MEMBERSHIP - and IPPROTO_IPV6 IPV6_JOIN_GROUP. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The <code>address</code> parameter is currently not supported for IPv6. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>drop_membership()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - bind - </dt> - <dd><code><code class='object unresolved'>UDP</code> bind(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Binds a port for receiving or transmitting UDP. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> - <dd></dd><dd class='body--doc'>Either a port number or the name of a service as listed in - <tt>/etc/services</tt>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'>Local address to bind to. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>no_reuseaddr</code></dt> - <dd></dd><dd class='body--doc'>If set to <code class='expr'>1</code>, Pike will not set the <code class='expr'>SO_REUSEADDR</code> option - on the UDP port. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code class='expr'>SO_REUSEADDR</code> is never applied when binding a random port - (<code class='expr'>bind(0)</code>). - 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>. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws error when unable to bind port. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - close - </dt> - <dd><code><code class='datatype'>bool</code> close()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Closes an open UDP port. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This method was introduced in Pike 7.5. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - connect - </dt> - <dd><code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Establish an UDP connection. - 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. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>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. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind()</code>, <code>query_address()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - drop_membership - </dt> - <dd><code><code class='datatype'>int</code> drop_membership(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Leave a multicast group. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>group</code></dt> - <dd></dd><dd class='body--doc'><code>group</code> contains the address of the multicast group the - application wants to join. It must be a valid multicast address. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'><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. - See also the Unix man page for setsocketopt IPPROTO_IP IP_DROP_MEMBERSHIP - and IPPROTO_IPV6 IPV6_LEAVE_GROUP. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The <code>address</code> parameter is currently not supported for IPv6. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>add_membership()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - dup - </dt> - <dd><code><code class='object unresolved'>Stdio.UDP</code> dup()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Duplicate the udp socket. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>fd_factory()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - enable_broadcast - </dt> - <dd><code><code class='datatype'>bool</code> enable_broadcast()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is normally only avalable to root users. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - enable_multicast - </dt> - <dd><code><code class='datatype'>bool</code> enable_multicast(<code class='datatype'>string</code> <code class='argument'>reply_address</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the local device for a multicast socket. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>reply_address</code></dt> - <dd></dd><dd class='body--doc'>Local address that should appear in the multicast packets. - See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF - and IPPROTO_IPV6 IPV6_MULTICAST_IF. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - errno - </dt> - <dd><code><code class='datatype'>int</code> errno()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the error code for the last command on this object. - Error code is normally cleared when a command is successful. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - fd_factory - </dt> - <dd><code><code class='object unresolved'>UDP</code> fd_factory()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Factory creating <code>Stdio.UDP</code> objects. - This function is called by <code>dup()</code> - and other functions creating new UDP objects. - The default implementation calls <code class='expr'>object_program(this_object())()</code> - to create the new object, and returns the <code>UDP</code> inherit in it. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Note that this function must return the <code>UDP</code> inherit in the object. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>dup()</code>, <code>Stdio.File()->fd_factory()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - get_type - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_type()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns socket type and protocol family. - </dd></dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Inherit UDP </dt>
2362: <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_address - </dt> - <dd><code><code class='datatype'>string</code> query_address()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_backend - </dt> - <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the backend used for the read callback. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_backend</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_fd - </dt> - <dd><code><code class='datatype'>int</code> query_fd()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Gets the file descriptor for this UDP port. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_mtu - </dt> - <dd><code><code class='datatype'>int</code> query_mtu()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the Max Transfer Unit for the object (if any). - </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>Returns <code class='expr'>-1</code> if the object is not a socket or - if the mtu is unknown. - </td></tr> - <tr><td><code><code class='key'>(1..)</code></code></td><td>Returns a positive value with the mtu on success. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The returned value is adjusted to take account for the - IP and UDP headers, so that it should be usable without - further adjustment unless further IP options are in use. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) read()</code> - <code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) read(<code class='datatype'>int</code> <code class='argument'>flag</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read from the UDP socket. - Flag <code>flag</code> is a bitfield, 1 for out of band data and 2 for peek - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>mapping(string:int|string) in the form - ([ - "data" : string received data - "ip" : string received from this ip - "port" : int ...and this port - ]) - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_read_callback()</code>, <code>MSG_OOB</code>, <code>MSG_PEEK</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - send - </dt> - <dd><code><code class='datatype'>int</code> send(<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> - <code><code class='datatype'>int</code> send(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Send data to a UDP socket. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>to</code></dt> - <dd></dd><dd class='body--doc'>The recipient address. For <code>connect()</code>ed objects specifying a - recipient of either <code>UNDEFINED</code> or <code class='expr'>""</code> causes the default - recipient to be used. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> - <dd></dd><dd class='body--doc'>The recipient port number. For <code>connect()</code>ed objects specifying - port number <code class='expr'>0</code> casues the default recipient port to be used. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>flag</code></dt> - <dd></dd><dd class='body--doc'>A flag bitfield with <code class='expr'>1</code> for out of band data and - <code class='expr'>2</code> for don't route flag. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>(0..)</code></code></td><td>The number of bytes that were actually written. - </td></tr> - <tr><td><code><code class='key'>(..-1)</code></code></td><td>Failed to send the <code>message</code>. Check <code>errno()</code> for - the cause. Common causes are: - <table class='box'><tr><td><code><code class='key'>System.EMSGSIZE</code></code></td><td>The <code>message</code> is too large to send unfragmented. - </td></tr> - <tr><td><code><code class='key'>System.EWOULDBLOCK</code></code></td><td>The send buffers are full. - </td></tr> - </table></td></tr> - </table> - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws errors on invalid arguments and uninitialized object. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Versions of Pike prior to 8.1.5 threw errors also on EMSGSIZE - (<code class='expr'>"Too big message"</code>) and EWOULDBLOCK - (<code class='expr'>"Message would block."</code>). These versions of Pike also - did not update the object errno on this function failing. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Versions of Pike prior to 8.1.13 did not support the default - recipient for <code>connect()</code>ed objects. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>connect()</code>, <code>errno()</code>, <code>query_mtu()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_backend - </dt> - <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the backend used for the read callback. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>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. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_backend</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_blocking - </dt> - <dd><code><code class='datatype'>object</code> set_blocking()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets this object to be blocking. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_buffer - </dt> - <dd><code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set internal socket buffer. - This function sets the internal buffer size of a socket or stream. - The second argument allows you to set the read or write buffer by - specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It is not guaranteed that this function actually does anything, - but it certainly helps to increase data transfer speed when it does. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open_socket()</code>, <code>accept()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_fd - </dt> - <dd><code><code class='object unresolved'>UDP</code> set_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Use the file descriptor <code>fd</code> for UDP. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_multicast_ttl - </dt> - <dd><code><code class='datatype'>int</code> set_multicast_ttl(<code class='datatype'>int</code> <code class='argument'>ttl</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the time-to-live value of outgoing multicast packets - for this socket. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>ttl</code></dt> - <dd></dd><dd class='body--doc'>The number of router hops sent multicast packets should - survive. - 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. - See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL - and IPPROTO_IPV6 IPV6_MULTICAST_HOPS. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>add_membership()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method + set_nonblocking </dt> <dd><code><code class='object unresolved'>UDP</code> set_nonblocking()</code> 
2625: <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_nonblocking - </dt> - <dd><code><code class='datatype'>object</code> set_nonblocking(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>void</code> <code class='argument'>rcb</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>void</code> <code class='argument'>wcb</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets this object to be nonblocking and the read and write callbacks. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method + set_read_callback </dt> <dd><code><code class='object unresolved'>UDP</code> set_read_callback(<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>)</code></dd>
2658: <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>read()</code> </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_type - </dt> - <dd><code><code class='object unresolved'>UDP</code> set_type(<code class='datatype'>int</code> <code class='argument'>sock_type</code>)</code> - <code><code class='object unresolved'>UDP</code> set_type(<code class='datatype'>int</code> <code class='argument'>sock_type</code>, <code class='datatype'>int</code> <code class='argument'>family</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets socket type and protocol family. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - wait - </dt> - <dd><code><code class='datatype'>bool</code> wait(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Check for data and wait max. <code>timeout</code> seconds. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> if data are ready, <code class='expr'>0</code> (zero) otherwise. - </dd></dl> + </dd></dl></dd> <dt><a name='9.7'></a> <h2 class='header'>9.7. Terminal I/O</h2></dt>
4060: <hr /> <dl class='group--doc'> <dt class='head--type'>Constant - IPPROTO_IP - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>IPPROTO_IP</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set IP-level options - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - IPPROTO_TCP - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>IPPROTO_TCP</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set TCP-level options - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - IP_TOS - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>IP_TOS</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set Type Of Service - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_ATTRIB - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_ATTRIB</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for attribute changes on a file. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_DELETE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_DELETE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for deletion of a file. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_EXTEND - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_EXTEND</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for extension events on a file. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_LINK - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_LINK</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for changes to a file's link count. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_RENAME - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_RENAME</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for move or rename events on a file. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_REVOKE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_REVOKE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for access revokation (unmount, etc). - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - NOTE_WRITE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>NOTE_WRITE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used with <code>Stdio.File()->set_fs_event_callback()</code> to monitor - for writes to a file. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Available on systems that use kqueue. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_BIDIRECTIONAL - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BIDIRECTIONAL</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The file is bi-directional. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_BUFFERED - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BUFFERED</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The file is buffered (usually 4KB). - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_IPC - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_IPC</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The file may be used for inter process communication. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_NONBLOCK - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_NONBLOCK</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The file supports nonblocking I/O. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_REVERSE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_REVERSE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Request reversed operation. - Used as argument to <code>Stdio.File()->pipe()</code>, when - <code>PROP_BIDIRECTIONAL</code> hasn't been specified, to - request the direction of the resulting pipe to - reversed. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_SEND_FD - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SEND_FD</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The <code>Stdio.File</code> object might support the <code>Stdio.File()->send_fd()</code> - operation. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code>, <code>Stdio.File()->send_fd()</code>, - <code>Stdio.File()->receive_fd()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_SHUTDOWN - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SHUTDOWN</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The file supports shutting down transmission in either - direction. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->close()</code>, <code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_TTY - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_TTY</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The <code>Stdio.File</code> object supports tty operations. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This constant is only present on platforms where pseudo tty - (aka pty) operations are available, and may thus be used to - detect whether such operations should be attempted. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - SOL_SOCKET - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>SOL_SOCKET</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used in <code>File.setsockopt()</code> to set socket-level options - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - SO_KEEPALIVE - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>SO_KEEPALIVE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used in <code>File.setsockopt()</code> to control TCP/IP keep-alive packets. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - TCP_NODELAY - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>TCP_NODELAY</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used in <code>File.setsockopt()</code> to control Nagle's Algorithm. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant + TCSADRAIN </dt> <dd><code><code class='datatype'>constant</code> <code class='datatype'>string</code> Stdio.<code class='constant'>TCSADRAIN</code></code></dd>
4415: <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - XATTR_CREATE - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>XATTR_CREATE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used by <code>setxattr</code> function and method to signify a pure - create, which will fail if the attribute already exists. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - XATTR_REPLACE - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>XATTR_REPLACE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Used by <code>setxattr</code> function and method to signify a replace, - which will fail the the attribute does not already exists. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - __HAVE_OOB__ - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>__HAVE_OOB__</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Exists and has the value 1 if OOB operations are available. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In Pike 7.5 and later OOB operations are always present. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - __HAVE_SEND_FD__ - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>__HAVE_SEND_FD__</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Support for sending of file descriptors over - <code>Stdio.File()->pipe()</code> objects with <code>PROP_SEND_FD</code> - capability is supported. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->send_fd()</code>, <code>Stdio.File()->receive_fd()</code>, - <code>Stdio.File()->read()</code>, <code>Stdio.File()->write()</code>, - <code>Stdio.File()->pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - __OOB__ - </dt> - <dd><code><code class='datatype'>constant</code> Stdio.<code class='constant'>__OOB__</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Implementation level of nonblocking I/O OOB support. - <table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Nonblocking OOB support is not supported. - </td></tr> - <tr><td><code><code class='key'>1</code></code></td><td>Nonblocking OOB works a little. - </td></tr> - <tr><td><code><code class='key'>2</code></code></td><td>Nonblocking OOB almost works. - </td></tr> - <tr><td><code><code class='key'>3</code></code></td><td>Nonblocking OOB works as intended. - </td></tr> - <tr><td><code><code class='key'>-1</code></code></td><td>Unknown level of nonblocking OOB support. - </td></tr> - </table>This constant only exists when OOB operations are - available, i.e. when <code>__HAVE_OOB__</code> is 1. - </dd></dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Method append_file </dt>
4693: <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - get_all_active_fd - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_all_active_fd()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the id of all the active file descriptors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - gethostip - </dt> - <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mapping</code>) gethostip()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the IP addresses of the host. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns a mapping that maps interface name to a mapping with - more information about that interface. That information mapping - looks as follows. - <table class='box'><tr><td><code><code class='key'>"ips"</code> : <code class='datatype'>array</code>(<code class='datatype'>string</code>)</code></td><td>A list of all IP addresses bound to this interface. - </td></tr> - </table></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - getprotobyname - </dt> - <dd><code><code class='datatype'>int</code> getprotobyname(<code class='datatype'>string(8bit)</code> <code class='argument'>name</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the protocol number of the protocol <code class='expr'>name</code>. - This calls the POSIX function getprotobyname. - If the protocol cannot be found an error is thrown. - </dd></dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Inherit _Stdio </dt>
5122: <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>append_file()</code>, <code>read_bytes()</code>, <code>Stdio.File()->open()</code> </dd></dl> - <dl><dt><h2 class='header'>Enum Stdio.FileModeFlags</h2> + <dl><dt><h2 class='header'>Class Stdio.BlockFile</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File mode flags returned by <code>Fd()->mode()</code>. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_APPEND - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_APPEND</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File open for appending. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_CREATE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_CREATE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create a new file if it didn't exist earlier. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_EXCLUSIVE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_EXCLUSIVE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Exclusive access to the file. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_NONBLOCKING - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_NONBLOCKING</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File opened in nonblocking mode. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_READ - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_READ</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File open for reading. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_TRUNC - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_TRUNC</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Truncate the file on open. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - FILE_WRITE - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>FILE_WRITE</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File open for writing. - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Enum Stdio.FilePropertyFlags</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File properties for use with eg <code>Fd()->pipe()</code>, - and returned by eg <code>Fd()->mode()</code>. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_BIDIRECTIONAL - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BIDIRECTIONAL</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File supports both sending and receiving. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_BUFFERED - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_BUFFERED</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File has internal buffering. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_IPC - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_IPC</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File can be used for interprocess communication. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_NONBLOCK - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_NONBLOCK</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File supports nonblocking operation. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_SEND_FD - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SEND_FD</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File is capable of sending open file descriptors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_SHUTDOWN - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_SHUTDOWN</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File supports unidirectional close. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Constant - PROP_TTY - </dt> - <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> Stdio.<code class='constant'>PROP_TTY</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>File supports tty operations. - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.BlockFile</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The Stdio.BlockFile API. This class exists purely for typing reasons. Use in types in place of <code>Stdio.File</code> where only blocking
5336: </dt> <dd><code><code class='datatype'>int</code> tell()</code></dd> </dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Buffer</h2> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.FakeFile</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. - The class maintains two separate offsets, one for reading and one - for writing. The functions that add data all do so at the write - offset (the end of the buffer), and reading is done from the read - offset (the start of the buffer). - The class can also be used to directly read from and write to - filedescriptors if so desired. This eliminates at least one memory - copy. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The "avoid copy" part means that a Buffer will never shrink - unless you call the <code>trim</code> function. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - __set_on_write - </dt> - <dd><code><code class='datatype'>void</code> __set_on_write(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>write_callback</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This tells the buffer to trigger the write callback for the - specified file descriptor when data is added to the buffer. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is used internally by <code>Stdio.File</code> and <code>SSL.File</code> to - handle nonblocking buffered mode, and is not necessarily - intended to be used directly by anything but implementations - of File or Stream like programs. Do not use this yourself - on buffers with Files or Streams in buffer modes. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _encode - Method - _decode - </dt> - <dd><code>string(8bit) encode_value(Stdio.Buffer data)</code> - <code>Stdio.Buffer decode_value(string(8bit) data)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Encode and decode Stdio.Buffer objects. - Only the buffer data is kept, no other state is saved. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _search - </dt> - <dd><code><code class='datatype'>int(-1..)</code> search(Stdio.Buffer from, <code class='datatype'>int(8bit)</code> <code class='argument'>character</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Search forward from the indicated <code>start</code> position for the specified - <code>character</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>character</code></dt> - <dd></dd><dd class='body--doc'>Character to search for. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>start</code></dt> - <dd></dd><dd class='body--doc'>Start position relative to the current read position of the buffer. - Negative <code>start</code> values are supported and indicate positions - prior to the current read position. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>end</code></dt> - <dd></dd><dd class='body--doc'>Don't search past this position of the buffer. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the first found position of <code>character</code> relative to the - current read position of the buffer on success, and <code>UNDEFINED</code> - on not found. The read position is not advanced. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_cstring()</code>, <code>search()</code>, <code>lfun::_search()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _search - </dt> - <dd><code><code class='datatype'>int(-1..)</code> search(Stdio.Buffer from, <code class='datatype'>string(8bit)</code> <code class='argument'>substring</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Search forward from the indicated <code>start</code> position for the specified - <code>substring</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>substring</code></dt> - <dd></dd><dd class='body--doc'>Substring to search for. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>start</code></dt> - <dd></dd><dd class='body--doc'>Start position relative to the current read position of the buffer. - Negative <code>start</code> values are supported and indicate positions - prior to the current read position. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>end</code></dt> - <dd></dd><dd class='body--doc'>Don't search past this position of the buffer. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the first found position of <code>substring</code> relative to the - current read position of the buffer on success, and <code>UNDEFINED</code> - on not found. The read position is not advanced. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_cstring()</code>, <code>search()</code>, <code>lfun::_search()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _sizeof - </dt> - <dd><code><code class='datatype'>int</code> sizeof( Stdio.Buffer 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(-1..255)</code> res = <code class='class'>Stdio.Buffer()</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> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the character at offset <code>off</code> on success, - and <code class='expr'>-1</code> otherwise. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[]= - </dt> - <dd><code><code class='class'>Stdio.Buffer()</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='object unresolved'>Buffer</code> add(<code class='object unresolved'>AddArgument</code> ... <code class='argument'>data</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><pre><code>private typedef System.Memory|Stdio.Buffer|String.Buffer BufferObject; - private typedef BufferObject|string(8bit)|int(8bit)|array(AddArgument) AddArgument;</code></pre>Add the items in data to the end of the buffer. - The supported argument types are: - <table class='box'><tr><td><code><code class='datatype'>string(8bit)</code></code></td><td>An eight bit string. - </td></tr> - <tr><td><code><code class='datatype'>int(8bit)</code></code></td><td>A single byte - </td></tr> - <tr><td><code><code class='object unresolved'>System.Memory</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>Stdio.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>String.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='datatype'>array</code>(<code class='object unresolved'>AddArgument</code>)</code></td><td>Add all elements in the array individually. Each element may be - any one of the types listed here. - </td></tr> - </table> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sprintf</code>, <code>add_int8</code>, <code>add_int16</code>, <code>add_int32</code>, <code>add_int</code> - and - <code>add_hstring</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_hint - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_hint(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>size_width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>First add the size of the integer when encoded to base 256 as a - <code>size_width</code> integer, then add the integer to the buffer, both - in network byte order. - <code>size_width</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_hstring - </dt> - <dd><code><code class='object unresolved'>Buffer</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> - <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='object unresolved'>Stdio.Buffer</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='object unresolved'>System.Memory</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='object unresolved'>String.Buffer</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='datatype'>int(8bit)</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='datatype'>array</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='datatype'>int</code>|<code class='datatype'>string(8bit)</code>|<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>System.Memory</code>|<code class='datatype'>array</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>, <code class='datatype'>int</code> <code class='argument'>offset</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds length of data followed by <code>data</code> to the buffer. - This is identical to - <tt>sprintf("%"+size_size+"H",(string)Stdio.Buffer(data))</tt> but - significantly faster. - <code>size_size</code> is the number of bytes used to represent the length of the data. - It must be less than Int.NATIVE_MAX. - <code>offset</code> is added to the length of the data prior to writing out - the length. Typical usage involves adding <code>size_size</code> to account - for the room used by the size. - The supported <code>data</code> argument types are - <table class='box'><tr><td><code><code class='datatype'>int(8bit)</code></code></td><td>An eight bit character. - </td></tr> - <tr><td><code><code class='datatype'>string(8bit)</code></code></td><td>An eight bit string. - </td></tr> - <tr><td><code><code class='object unresolved'>System.Memory</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>Stdio.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>String.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='datatype'>array</code></code></td><td>Add all elements in the array individually. Each element may be - any one of the types listed here. - </td></tr> - </table></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int - </dt> - <dd><code><code class='object unresolved'>Buffer</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 - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_int16(<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_int16 - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_int16(<code class='argument'>Gmp.mpz</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='object unresolved'>Buffer</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 - add_int32 - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_int32(<code class='object unresolved'>Gmp.mpz</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 - add_int8 - </dt> - <dd><code><code class='object unresolved'>Buffer</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_int8 - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_int8(<code class='argument'>Gmp.mpz</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_ints - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_ints(<code class='datatype'>array</code>(<code class='datatype'>int</code>) <code class='argument'>integers</code>, <code class='datatype'>int(8bit)</code> <code class='argument'>len</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add the integers in the specified array, <code>len</code> bytes per int. - Equivalent to calling <code>add_int</code> for each integer, but faster, - and if an error occurs the buffer will contain no new - data. Either all or none of the integers will be added. - Errors can occur if one of the elements in <code>integers</code> is not - actually an integer, if sizeof(integers)*len is bigger than can - be represented in a size_t, or if the buffer cannot grow due to - an out of memory condition. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_padding - </dt> - <dd><code><code class='object unresolved'>Buffer</code> add_padding(<code class='datatype'>int(0..)</code> <code class='argument'>nbytes</code>, <code class='datatype'>int(8bit)</code>|<code class='datatype'>void</code> <code class='argument'>byte</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add <code>nbytes</code> bytes of padding, if <code>byte</code> is not specified the - area will be filled with 0's, otherwise the specified byte will - be repeated. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - allocate - </dt> - <dd><code><code class='datatype'>void</code> allocate(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Make sure that at least <code>n</code> bytes of space are available in this buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - cast - </dt> - <dd><code>(<code class='datatype'>string(8bit)</code>)Stdio.Buffer()</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 - Returns -1 on error and the amount of space still left otherwise. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.Buffer Stdio.Buffer(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>len</code>)</code> - <code>Stdio.Buffer Stdio.Buffer(<code class='datatype'>string(8bit)</code> <code class='argument'>contents</code>)</code> - <code>Stdio.Buffer Stdio.Buffer(<code class='object unresolved'>System.Memory</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>contents</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>If passed an integer or no argument, create a buffer of that - size, or if no argument is given, 226 bytes. - If <code>contents</code> are specified a new buffer with the contents of - the given string/System.Memory or String.Buffer will be created. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In the <code>String.Buffer</code> case the data has to be copied unless - there is only one reference to the String.Buffer object, since - modifications of the String.Buffer would cause the Buffer to - point into invalid memory. - In all other cases this will not copy the string data, instead - data will be read from the source until it needs to be modified, - so the buffer creation is fast regardless of the length of the - string. - However, as an example, if the buffer is created with a 100Gb - <code>System.Memory</code> mmap:ed file as the <code>contents</code> and you later on - try to modify the buffer using one of the <code>add</code> functions (or - <code>sprintf</code> and similar) the old contents will be copied. - You can use <code>read_only()</code> to avoid accidents. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - input_from - </dt> - <dd><code><code class='datatype'>int(-1..)</code> input_from(<code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read data from <code>f</code> into this buffer. If <code>nbytes</code> is not - specified, read until there is no more data to read (currently). - Returns the amount of data that was read, or <code class='expr'>-1</code> on - read error. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Please note that this funcition will read all data from the - filedescriptor unless it's set to be non-blocking. - </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 - output_to - </dt> - <dd><code><code class='datatype'>int(-1..)</code> output_to(<code class='object unresolved'>Stdio.Stream</code>|<code class='datatype'>function</code>(<code class='datatype'>string(8bit)</code>:<code class='datatype'>int</code>) <code class='argument'>fun</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write data from the buffer to the indicated file. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>fun</code></dt> - <dd></dd><dd class='body--doc'>Write function. Either one of: - <table class='box'><tr><td><code><code class='object unresolved'>Stdio.Stream</code></code></td><td>A file object in which the function <code class='expr'>write()</code> will - be called. - </td></tr> - <tr><td><code><code class='datatype'>function</code>(<code class='datatype'>string(8bit)</code>:<code class='datatype'>int</code>)</code></td><td>A function which will be called with a <code class='expr'>string(8bit)</code> - to write and is expected to return an <code class='expr'>int</code> indicating - the number of bytes successfully written or <code class='expr'>-1</code> on - failure. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>nbytes</code></dt> - <dd></dd><dd class='body--doc'>If <code>nbytes</code> is not specified the whole buffer will be written - if possible. Otherwise at most <code>nbytes</code> will be written. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Will return the number of bytes that have been written successfully. - If no bytes have been written successfully and <code class='expr'>fun()</code> failed - with an error, <code class='expr'>-1</code> will be returned. - </dd> - <dt class='head--doc'>Deprecated</dt> - <dd class='body--doc'>This function is going to get deprecated. In case you want to use - it against an <code>Stdio.File</code> like object, please consider using - the <code class='expr'>f->write(buf)</code> API. If you want to use it against a custom - write function, please consider supporting the <code class='expr'>f->write(buf)</code> - API in it. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - range_error - </dt> - <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>bool</code> range_error(<code class='datatype'>int</code> <code class='argument'>howmuch</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function is called when an attempt is made to read out of bounds. - The default implementation simply returns <code class='expr'>0</code> (zero). - Override this function to change the behavior. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>howmuch</code></dt> - <dd></dd><dd class='body--doc'>The argument <code>howmuch</code> indicates how much data is needed: - <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td>Need <code>howmuch</code> bytes more - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td>The amount of data needed is not certain. - This most often happens when <code>sscanf</code> or <code>read_json</code> is used - </td></tr> - <tr><td><code><code class='key'>(..-1)</code></code></td><td>Tried to <code>unread</code> -<code>howmuch</code> bytes. There is usually no way to satisfy - the requested range. - The only supported way is to extract the data from the buffer, - add the requested amount of "go backbuffer", add the data - back, and forward -<code>howmuch</code> bytes. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><code>true</code> if the operation should be retried, <code>false</code> otherwise. - Do not return true unless you have added data to the buffer, - doing so could result in an infinite loop (since no data is - added, the range_error will be called again immediately). - </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> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>try_read()</code> - </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>n</code> bytes of data from the buffer. - If there is not enough data available this returns 0. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>try_read()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_buffer - </dt> - <dd><code><code class='object unresolved'>Buffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>Buffer</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 Buffer. - 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_cstring - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read_cstring(<code class='datatype'>void</code>|<code class='datatype'>int(8bit)</code> <code class='argument'>sentinel</code>, <code class='datatype'>void</code>|<code class='datatype'>int(8bit)</code> <code class='argument'>escape</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads a \0 terminated C-string and returns the - string excluding the terminating \0. - If there is not enough data available return UNDEFINED. - Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>sentinel</code></dt> - <dd></dd><dd class='body--doc'>A different character can be used as end sentinel of the string. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>escape</code></dt> - <dd></dd><dd class='body--doc'>An optional character used as a prefix to quote the following - character. UNDEFINED and the same value as <code>sentinel</code> mean - that there is no escape character. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Escape characters (if any) are left untouched in the returned string. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>_search()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hbuffer - </dt> - <dd><code><code class='object unresolved'>Buffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>Buffer</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 Buffer. - 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_hint - </dt> - <dd><code><code class='datatype'>int</code> read_hint(<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 byte order unsigned number of size n*8 bits, then - read another network byte order number of the size indicated by - the first size. - 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_hstring - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read_hstring(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>offset</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. - <code>offset</code> is substracted from the specified length prior to reading the - string. Typical usage involves substracting <code>n</code> to account - for the room used by the size. - 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 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> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_le_int</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int16 - </dt> - <dd><code><code class='datatype'>int(16bit)</code> read_int16()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int24 - </dt> - <dd><code><code class='datatype'>int(24bit)</code> read_int24()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int32 - </dt> - <dd><code><code class='datatype'>int(32bit)</code> read_int32()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int8 - </dt> - <dd><code><code class='datatype'>int(8bit)</code> read_int8()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_ints - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) read_ints(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>int</code> <code class='argument'>width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a list of <code>n</code> network byte order unsigned numbers each of - size <code>width</code>*8 bits, then return it. - Will return 0 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 - read_le_int - </dt> - <dd><code><code class='datatype'>int</code> read_le_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 big endian 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> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_int</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_only - </dt> - <dd><code><code class='datatype'>void</code> read_only()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Make the buffer permanently read only. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>You can use lock() to do this temporarily. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_sint - </dt> - <dd><code><code class='datatype'>int</code> read_sint(<code class='datatype'>int</code> <code class='argument'>size</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a network byte order two:s complement signed number of size - n*8 bits, then return it. - Will return UNDEFINED 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 - rewind_on_error - Method - rewind_key - </dt> - <dd><code><code class='object unresolved'>RewindKey</code> rewind_on_error()</code> - <code><code class='object unresolved'>RewindKey</code> rewind_key()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>These functions are very similar. The <code>rewind_on_error</code> variant - will create an object that, when it goes out of scope without - having been destructed explicitly, will cause the buffer to - rewind to the location it had when this function is called. - This will happen if you throw an error or otherwise let the - object fall out of scope. - Use <code>destruct(RewindKey)</code> or <code>RewindKey.release</code> to stop the - buffer from being rewound. - The second version (<code>rewind_key</code>) requires you to explicitly - call <code>RewindKey.rewind</code> to do the rewind. - Take some care with these objects, if you create multiple ones - at once the results might be somewhat confusing if you do not - release them in the reverse order they were created in (then - again, you almost certainly really only need one) - You can call <code>RewindKey.update</code> in the generated object to - change where it will be rewound to. - The typical use-case of this functionality is when parsing a - packet protocol with variable length packets where the length is - not immediately known. It saves you from keeping track of how - much to rewind if you had not actually gotten the whole packet - yet. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>void parse_packet( Stdio.Buffer b ) - { - Stdio.Buffer.RewindKey rewind = b->rewind_on_error(); - b->set_error_mode(1); - - switch( b->read_int8() ) // packet type - { - case DATA: - int channel = b->read_int8(); - Stdio.Buffer data = b->read_hbuffer( 4 ); - // we have read the whole packet, so no longer rewind on error. - rewind->release(); - return handle_data_packet( channel, data ); - } - } - </code></pre></pre></dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Just calling <code>rewind_on_error</code> without assigning the return - value to something will not do anything. You need to keep the - object around while the rewind-to position is still valid. - Keeping the object around forbids the buffer from moving data - inside itself, this means that it can only grow. So do not keep - the rewind key when it is not needed. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_error_mode - </dt> - <dd><code><code class='object unresolved'>Buffer</code> set_error_mode(<code class='datatype'>int</code> <code class='argument'>m</code>)</code> - <code><code class='object unresolved'>Buffer</code> set_error_mode(<code class='datatype'>program</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 throw an error. If <code>m</code> is a program - a clone of it will be thrown on 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(8bit) new_data) - { - inbuffer->add( new_data ); - - while( Buffer 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( Buffer 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 - set_max_waste - </dt> - <dd><code><code class='datatype'>void</code> set_max_waste(<code class='datatype'>float</code> <code class='argument'>factor</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Configure how much free space should be allowed, at most, as a - factor of the current buffer size. - The default is 0.5, leaving at most half the buffer as waste. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sprintf - </dt> - <dd><code><code class='object unresolved'>Buffer</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 - truncate - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> truncate(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Truncates the buffer to a length of <code>n</code> bytes. - Returns -1 on error and the number of bytes removed otherwise. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - try_read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> try_read(<code class='datatype'>int</code> <code class='argument'>len</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Attempt to read some data from the buffer. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>len</code></dt> - <dd></dd><dd class='body--doc'>Read at most <code>len</code> bytes from the buffer. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>If the buffer contains less than <code>len</code> bytes - of data, the entire buffer contents are returned. - Otherwise the first <code>len</code> bytes are returned. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code> - </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>unread(0)</code> to see how much. - </dd></dl> - <dl><dt><h2 class='header'>Class Stdio.Buffer.RewindKey</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The return value of <code>Buffer.rewind_on_error()</code> and - <code>Buffer.rewind_key()</code> - This object will cause the buffer to unwind to the position it was - at when the object was created either when it is released (when it - falls out of scope, explicit destruct does not count) or when - <code>rewind</code> is called, depending on which function was used to - create it. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - release - </dt> - <dd><code><code class='datatype'>void</code> release()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Do not rewind if the object is released. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is equivalent to calling destruct() on the object - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - rewind - </dt> - <dd><code><code class='datatype'>void</code> rewind()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Rewinds the buffer explicitly. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Destructs this <code>RewindKey</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - update - </dt> - <dd><code><code class='datatype'>void</code> update()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Update the location the buffer will be rewound to to the current - position of the buffer. - </dd></dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.FakeFile</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> + <dd class='body--doc'>A string wrapper that pretends to be a <code>Stdio.File</code> object in addition to some features of a <code>Stdio.FILE</code> object. </dd></dl>
7197: <dd><code><code class='datatype'>int</code> write(<code class='object unresolved'>sprintf_format</code>|<code class='datatype'>array</code>(<code class='datatype'>string(8bit)</code>) <code class='argument'>data</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code>)</code></dd> </dl> </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.Fd</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Low level I/O operations. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is not the class you want. Use <code>Stdio.File</code> and friends instead. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File</code>, <code>Stdio.FILE</code>, <code>_Stdio.Fd_ref</code> - </dd></dl> + </dt><dd> <hr /> <dl class='group--doc'> - <dt class='head--type'>Variable - _errno - </dt> - <dd><code><code class='modifier'>protected</code> <code class='datatype'>int(0..)</code> Stdio.Fd._errno</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Variable containing the internal value returned by <code>errno()</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>errno()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Variable - _fd - </dt> - <dd><code><code class='object unresolved'>Fd</code> Stdio.Fd._fd</code></dd> - - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Read only - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Variable - _read_callback - Variable - _write_callback - Variable - _read_oob_callback - Variable - _write_oob_callback - Variable - _fs_event_callback - </dt> - <dd><code><code class='datatype'>mixed</code> Stdio.Fd._read_callback</code> - <code><code class='datatype'>mixed</code> Stdio.Fd._write_callback</code> - <code><code class='datatype'>mixed</code> Stdio.Fd._read_oob_callback</code> - <code><code class='datatype'>mixed</code> Stdio.Fd._write_oob_callback</code> - <code><code class='datatype'>mixed</code> Stdio.Fd._fs_event_callback</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Callback functions installed by <code>Stdio.File()->set_callbacks()</code> et al. - </dd></dl> - - - <hr /> - <dl class='group--doc'> + <dt class='head--type'>Method - close - </dt> - <dd><code><code class='datatype'>int</code> close()</code> - <code><code class='datatype'>int</code> close(<code class='datatype'>string</code> <code class='argument'>direction</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Close a file or stream. - If direction is not specified, both the read and the write - direction are closed. Otherwise only the directions specified is - closed. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> if the file or stream now is closed in - all directions, and <code class='expr'>0</code> otherwise. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An exception is thrown if an I/O error occurs. - The default behaviour for sockets is typically to flush buffered - data in the background, but this can be changed with <code>linger()</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code>close()</code> has no effect if this file object has been associated - with an already opened file, i.e. if <code>open()</code> was given an - integer as the first argument. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>linger()</code>, <code>open()</code>, <code>open_socket()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - connect - </dt> - <dd><code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>)</code> - <code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code> <code class='argument'>src_port</code>)</code> - <code><code class='datatype'>string(8bit)</code>|<code class='datatype'>int(0..0)</code> connect(<code class='datatype'>string</code> <code class='argument'>dest_addr</code>, <code class='datatype'>int</code> <code class='argument'>dest_port</code>, <code class='datatype'>string</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_addr</code>, <code class='datatype'>int</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>src_port</code>, <code class='datatype'>string(8bit)</code> <code class='argument'>data</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a TCP/IP connection to the specified destination. - In nonblocking mode, success is indicated with the write-callback, - and failure with the close-callback or the read_oob-callback. - If the <code>data</code> argument is included the socket will use - TCP_FAST_OPEN if available, if not the data will not be - sent. In the data case the function either returns the data - that has not been sent (only one packet can be sent with this - option) or 0 if the connection failed immediately. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> or the remaining <code class='expr'>data</code> on success, and - <code class='expr'>0</code> on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set - to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded - as a connection failure. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - connect_unix - </dt> - <dd><code><code class='datatype'>bool</code> connect_unix(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a UNIX domain socket connection to the specified destination. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>filename</code></dt> - <dd></dd><dd class='body--doc'>Filename to create. - In nonblocking mode, success is indicated with the write-callback, - and failure with the close-callback or the read_oob-callback. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and <code>errno()</code> set - to <tt>EWOULDBLOCK</tt> or <tt>WSAEWOULDBLOCK</tt>. This should not be regarded - as a connection failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code>path</code> had a quite restrictive length limit (~100 characters) - prior to Pike 7.8.334. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.Fd Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> - <code>Stdio.Fd Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code>Stdio.Fd Stdio.Fd(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code>)</code> - <code>Stdio.Fd Stdio.Fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code> - <code>Stdio.Fd Stdio.Fd(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>See <code>open()</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - dup - </dt> - <dd><code><code class='object unresolved'>Stdio.Fd</code> dup()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Duplicate the file. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>dup2()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - dup2 - </dt> - <dd><code><code class='datatype'>int</code> dup2(<code class='object unresolved'>Stdio.File</code> <code class='argument'>to</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Duplicate a file over another. - This function works similarly to <code>assign()</code>, but instead of making - the argument a reference to the same file, it creates a new file - with the same properties and places it in the argument. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success and <code class='expr'>0</code> (zero) on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code>to</code> need not be open, in which - case a new fd is allocated. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Note also that <code>to</code> is also assigned to the same backend (if any) - as this object. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>assign()</code>, <code>dup()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - errno - </dt> - <dd><code><code class='datatype'>int</code> errno()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the errno for the latest failed file operation. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - fd_factory - </dt> - <dd><code><code class='object unresolved'>Fd</code> fd_factory()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Factory creating <code>Stdio.Fd</code> objects. - This function is called by <code>openat()</code>, <code>pipe()</code>, <code>dup()</code> - and other functions creating new file objects. - The default implementation calls <code class='expr'>object_program(this_object())()</code> - to create the new object, and returns the <code>Fd</code> inherit in it. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Note that this function must return the <code>Fd</code> inherit in the object. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.Port()->fd_factory()</code>, <code>openat()</code>, <code>pipe()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - get_dir - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) get_dir(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>path</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get directory contents relative to an open directory. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>path</code></dt> - <dd></dd><dd class='body--doc'>Path relative to the open directory. Defaults to the - directory itself. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns an array of filenames. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Not available on all architectures. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>predef::get_dir()</code>, <code>statat()</code>, <code>openat()</code>, <code>unlinkat()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - getxattr - </dt> - <dd><code><code class='datatype'>string</code> getxattr(<code class='datatype'>string</code> <code class='argument'>attr</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the value of a specified attribute, or 0 if it does not exist - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - grantpt - </dt> - <dd><code><code class='datatype'>string</code> grantpt()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>If this file has been created by calling <code>openpt()</code>, return the - filename of the associated pts-file. This function should only be - called once. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the filename of the corresponding pts. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function is only available on some platforms. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - is_open - </dt> - <dd><code><code class='datatype'>int</code> is_open()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns true if the file is open. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>If the file is a socket that has been closed from the remote side, - this function might still return true. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Most methods can't be called for a file descriptor that isn't - open. Notable exceptions <code>errno</code>, <code>mode</code>, and the set and query - functions for callbacks and backend. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - linger - </dt> - <dd><code><code class='datatype'>bool</code> linger(<code class='datatype'>int(-1..65535)</code>|<code class='datatype'>void</code> <code class='argument'>seconds</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the socket linger behaviour on <code>close()</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>seconds</code></dt> - <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>-1</code></code></td><td>Reset to default behaviour. This typically means that - <code>close()</code> will return immediately, but any buffered - data will still be sent if possible. - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td>Terminate the connection immediately on <code>close()</code>, - and discard any buffered data. - </td></tr> - <tr><td><code><code class='key'>(1..65535)</code></code></td><td>Have <code>close()</code> wait for at most <code>seconds</code> seconds - for any buffered data to be sent after which the - connection is terminated. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This operation is only valid on sockets. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function was not available in Pike 7.8.775 and earlier. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>close()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - listxattr - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) listxattr()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return an array of all extended attributes set on the file - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - lock - </dt> - <dd><code><code class='object unresolved'>Stdio.FileLockKey</code> lock()</code> - <code><code class='object unresolved'>Stdio.FileLockKey</code> lock(<code class='datatype'>bool</code> <code class='argument'>is_recursive</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Makes an exclusive file lock on this file. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>trylock()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - mode - </dt> - <dd><code><code class='object unresolved'>FileModeFlags</code>|<code class='object unresolved'>FilePropertyFlags</code> mode()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the open mode and capabilities for the file. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns an <code>`|()</code> of the following flags: - <table class='box'><tr><td><code><code class='key'>0x1000</code></code></td><td><code>FILE_READ</code> - </td></tr> - <tr><td><code><code class='key'>0x2000</code></code></td><td><code>FILE_WRITE</code> - </td></tr> - <tr><td><code><code class='key'>0x4000</code></code></td><td><code>FILE_APPEND</code> - </td></tr> - <tr><td><code><code class='key'>0x8000</code></code></td><td><code>FILE_CREATE</code> - </td></tr> - <tr><td><code><code class='key'>0x0100</code></code></td><td><code>FILE_TRUNC</code> - </td></tr> - <tr><td><code><code class='key'>0x0200</code></code></td><td><code>FILE_EXCLUSIVE</code> - </td></tr> - <tr><td><code><code class='key'>0x0400</code></code></td><td><code>FILE_NONBLOCKING</code> - </td></tr> - <tr><td><code><code class='key'>0x0080</code></code></td><td><code>PROP_TTY</code> - </td></tr> - <tr><td><code><code class='key'>0x0040</code></code></td><td><code>PROP_SEND_FD</code> - </td></tr> - <tr><td><code><code class='key'>0x0010</code></code></td><td><code>PROP_BIDIRECTIONAL</code> - </td></tr> - <tr><td><code><code class='key'>0x0008</code></code></td><td><code>PROP_BUFFERED</code> - </td></tr> - <tr><td><code><code class='key'>0x0004</code></code></td><td><code>PROP_SHUTDOWN</code> - </td></tr> - <tr><td><code><code class='key'>0x0002</code></code></td><td><code>PROP_NONBLOCK</code> - </td></tr> - <tr><td><code><code class='key'>0x0001</code></code></td><td><code>PROP_IPC</code> - </td></tr> - </table> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In some versions of Pike 7.8 the <tt>PROP_</tt> flags were - filtered from the result. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - open - </dt> - <dd><code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code>)</code> - <code><code class='datatype'>int</code> open(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a file, or use an existing fd. - If <code>filename</code> is given, attempt to open the named file. If <code>fd</code> - is given instead, it should be the file descriptor for an already - opened file, which will then be used by this object. - <code>mode</code> describes how the file is opened. It's a case-insensitive - string consisting of one or more of the following letters: - <dl class='group--doc'><dt>"r"</dt> - <dd>Open for reading. - </dd> - <dt>"w"</dt> - <dd>Open for writing. - </dd> - <dt>"a"</dt> - <dd>Append new data to the end. - </dd> - <dt>"c"</dt> - <dd>Create the file if it doesn't exist already. - </dd> - <dt>"t"</dt> - <dd>Truncate the file to zero length if it already contains data. - Use only together with <code class='expr'>"w"</code>. - </dd> - <dt>"x"</dt> - <dd>Open exclusively - the open fails if the file already exists. - Use only together with <code class='expr'>"c"</code>. Note that it's not safe to - assume that this is atomic on some systems. - </dd> - </dl><code>access</code> specifies the permissions to use if a new file is - created. It is a UNIX style permission bitfield: - <dl class='group--doc'><dt>0400</dt> - <dd>User has read permission. - </dd> - <dt>0200</dt> - <dd>User has write permission. - </dd> - <dt>0100</dt> - <dd>User has execute permission. - </dd> - <dt>0040</dt> - <dd>Group has read permission. - </dd> - <dt>0020</dt> - <dd>Group has write permission. - </dd> - <dt>0010</dt> - <dd>Group has execute permission. - </dd> - <dt>0004</dt> - <dd>Others have read permission. - </dd> - <dt>0002</dt> - <dd>Others have write permission. - </dd> - <dt>0001</dt> - <dd>Others have execute permission. - </dd> - </dl>It's system dependent on which of these bits that are actually - heeded. If <code>access</code> is not specified, it defaults to - <code class='expr'>00666</code>, but note that on UNIX systems it's masked with the - process umask before use. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns nonzero on success and <code class='expr'>0</code> (zero) on failure. If - there is a failure then <code>errno</code> returns the error code. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>close()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - open_socket - </dt> - <dd><code><code class='datatype'>bool</code> open_socket(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>addr</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code>)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - openat - </dt> - <dd><code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> - <code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='object unresolved'>Stdio.File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>access</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a file relative to an opened directory. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns a new file object on success, and <code class='expr'>0</code> (zero) on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Not available on all architectures. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open()</code>, <code>statat()</code>, <code>unlinkat()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - openpt - </dt> - <dd><code><code class='datatype'>int</code> openpt(<code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open the master end of a pseudo-terminal pair. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>grantpt()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - peek - </dt> - <dd><code><code class='datatype'>int(-1..1)</code> peek()</code> - <code><code class='datatype'>int(-1..1)</code> peek(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>)</code> - <code><code class='datatype'>int(-1..1)</code> peek(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>, <code class='datatype'>int</code> <code class='argument'>not_eof</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Check if there is data available to read, - or wait some time for available data to read. - More specifically, a later call to <code>read()</code> will return - immediately, either due to data being present, or due to - some error (eg if a socket has been closed). - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>timeout</code></dt> - <dd></dd><dd class='body--doc'>Timeout in seconds. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>not_eof</code></dt> - <dd></dd><dd class='body--doc'>Flag for specifying handling of end of file. - The following values are currently defined: - <table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Traditional (and default) behaviour. Return <code class='expr'>1</code> - at EOF. - </td></tr> - <tr><td><code><code class='key'>1</code></code></td><td>Regard EOF as an error. Return <code class='expr'>-1</code> and set <code>errno()</code> - to return <code class='expr'>EPIPE</code> at EOF. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>1</code></code></td><td>There is data available to <code>read()</code>, or <code>not_eof</code> is - <code class='expr'>0</code> (zero) and we're at EOF. A later call to - <code>read()</code> will not block. - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td>There is no data available (ie timeout). - </td></tr> - <tr><td><code><code class='key'>-1</code></code></td><td>Error condition. The error code returned by <code>errno()</code> - has been updated. - </td></tr> - </table> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>errno()</code>, <code>read()</code> - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The function may be interrupted prematurely - of the timeout (due to signals); - check the timing manually if this is imporant. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - pipe - </dt> - <dd><code><code class='object unresolved'>Stdio.File</code> pipe()</code> - <code><code class='object unresolved'>Stdio.File</code> pipe(<code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - proxy - </dt> - <dd><code><code class='datatype'>void</code> proxy(<code class='object unresolved'>Stdio.File</code> <code class='argument'>from</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Starts a thread that asynchronously copies data from <code>from</code> - to this file. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.sendfile()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_address - </dt> - <dd><code><code class='datatype'>string</code> query_address()</code> - <code><code class='datatype'>string</code> query_address(<code class='datatype'>bool</code> <code class='argument'>local</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get address and port of a socket end-point. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>local</code></dt> - <dd></dd><dd class='body--doc'>If the argument <code>local</code> is not specified, or is <code class='expr'>0</code> - (zero), the remote end-point is returned. Otherwise, if <code>local</code> - is <code class='expr'>1</code>, the local end-point is returned. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns the address and port of a socket end-point - on the form <code class='expr'>"x.x.x.x port"</code> (IPv4) or - <code class='expr'>"x:x:x:x:x:x:x:x port"</code> (IPv6). IPv6 addresses - may use the contracted syntax. - If this file is not a socket, is not connected, or some other - error occurs, <code class='expr'>0</code> (zero) is returned and <code>errno()</code> will - return the error code. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error is thrown if the socket (or file) isn't open. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>connect()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_backend - </dt> - <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the backend used for the callbacks. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_backend</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_fd - </dt> - <dd><code><code class='datatype'>int</code> query_fd()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the file descriptor number associated with this object. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - query_mtu - </dt> - <dd><code><code class='datatype'>int</code> query_mtu()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the Max Transfer Unit for the object (if any). - </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>Returns <code class='expr'>-1</code> if the object is not a socket or - if the mtu is unknown. - </td></tr> - <tr><td><code><code class='key'>(1..)</code></code></td><td>Returns a positive value with the mtu on success. - </td></tr> - </table></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string</code> read()</code> - <code><code class='datatype'>string</code> read(<code class='datatype'>int</code> <code class='argument'>len</code>)</code> - <code><code class='datatype'>string</code> read(<code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read data from a file or a stream. - Attempts to read <code>len</code> bytes from the file, and return it as a - string. Less than <code>len</code> bytes can be returned if: - <ul> - <li>end-of-file is encountered for a normal file, or - </li><li>it's a stream that has been closed from the other end, or - </li><li>it's a stream in nonblocking mode, or - </li><li>it's a stream and <code>not_all</code> is set, or - </li><li><code>not_all</code> isn't set and an error occurred (see below). - </li></ul>If <code>not_all</code> is nonzero, <code>read()</code> does not try its best to read - as many bytes as you have asked for, but merely returns as much as - the system read function returns. This is mainly useful with - stream devices which can return exactly one row or packet at a - time. If <code>not_all</code> is used in blocking mode, <code>read()</code> only - blocks if there's no data at all available. - If something goes wrong and <code>not_all</code> is set, zero is returned. - If something goes wrong and <code>not_all</code> is zero or left out, then - either zero or a string shorter than <code>len</code> is returned. If the - problem persists then a later call to <code>read()</code> fails and returns - zero, however. - If everything went fine, a call to <code>errno()</code> directly afterwards - returns zero. That includes an end due to end-of-file or remote - close. - If no arguments are given, <code>read()</code> reads to the end of the file - or stream. - If any file descriptors have been sent by the other side of the - stream, <code>receive_fd()</code> will be called once for every sent file - descriptor. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It's not necessary to set <code>not_all</code> to avoid blocking reading - when nonblocking mode is used. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>When at the end of a file or stream, repeated calls to <code>read()</code> - will return the empty string since it's not considered an error. - The empty string is never returned in other cases, unless nonblocking - mode is used or <code>len</code> is zero. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_oob()</code>, <code>write()</code>, <code>receive_fd()</code>, <code>send_fd()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>int</code> read(<code class='object unresolved'>System.Memory</code> <code class='argument'>dst</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..)</code> <code class='argument'>offset</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from a file or stream into the buffer <code>dst</code> at offset - <code>offset</code>. Tries to read as many bytes as buffer space available. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The number of bytes read. Returns <code class='expr'>-1</code> on error and - <code>errno()</code> will return the corresponding error code. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>int</code> read(<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>dst</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from a file or stream into the buffer <code>dst</code>. Tries to - read as many bytes as buffer space available. - Will advance the write position in <code>dst</code> by the number of bytes - read. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The number of bytes read. Returns <code class='expr'>-1</code> on error and - <code>errno()</code> will return the corresponding error code. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_oob - </dt> - <dd><code><code class='datatype'>string</code> read_oob()</code> - <code><code class='datatype'>string</code> read_oob(<code class='datatype'>int</code> <code class='argument'>len</code>)</code> - <code><code class='datatype'>string</code> read_oob(<code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Attempts to read <code>len</code> bytes of out-of-band data from the stream, - and returns it as a string. Less than <code>len</code> bytes can be returned - if: - <ul> - <li>the stream has been closed from the other end, or - </li><li>nonblocking mode is used, or - </li><li><code>not_all</code> is set, or - </li><li><code>not_all</code> isn't set and an error occurred (see below). - </li></ul>If <code>not_all</code> is nonzero, <code>read_oob()</code> only returns as many bytes - of out-of-band data as are currently available. - If something goes wrong and <code>not_all</code> is set, zero is returned. - If something goes wrong and <code>not_all</code> is zero or left out, then - either zero or a string shorter than <code>len</code> is returned. If the - problem persists then a later call to <code>read_oob()</code> fails and - returns zero, however. - If everything went fine, a call to <code>errno()</code> directly afterwards - returns zero. That includes an end due to remote close. - If no arguments are given, <code>read_oob()</code> reads to the end of the - stream. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It is not guaranteed that all out-of-band data sent from the - other end is received. Most streams only allow for a single byte - of out-of-band data at a time. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It's not necessary to set <code>not_all</code> to avoid blocking reading - when nonblocking mode is used. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>When at the end of a file or stream, repeated calls to <code>read()</code> - returns the empty string since it's not considered an error. The - empty string is never returned in other cases, unless nonblocking - mode is used or <code>len</code> is zero. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code>, <code>write_oob()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - receive_fd - </dt> - <dd><code><code class='datatype'>void</code> receive_fd(<code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remote file descriptor reception handler. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>fd</code></dt> - <dd></dd><dd class='body--doc'>File descriptor received from the remote end of a <code>pipe()</code>. - This object has been created by <code>fd_factory()</code>. - This function is called from <code>read()</code> when a remote file - descriptor has been received over a <code>PROP_SEND_FD</code> - capable <code>pipe()</code>. - The default implementation is just a prototype. - Overload this function to enable reception of - remote file descriptors. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The capability of sending and receiving remote file - descriptors is only available on some operating systems. - This capability is indicated by the precence of <code>__HAVE_SEND_FD__</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>send_fd()</code>, <code>read()</code>, <code>fd_factory()</code>, <code>__HAVE_SEND_FD__</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - release_fd - </dt> - <dd><code><code class='datatype'>int</code> release_fd()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the file descriptor number associated with this object, in - addition to releasing it so that this object behaves as if closed. - Other settings like callbacks and backend remain intact. - <code>take_fd</code> can later be used to reinstate the file descriptor so - that the state is restored. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_fd()</code>, <code>take_fd()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - removexattr - </dt> - <dd><code><code class='datatype'>void</code> removexattr(<code class='datatype'>string</code> <code class='argument'>attr</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove the specified extended attribute. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - seek - </dt> - <dd><code><code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>offset</code>)</code> - <code><code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>offset</code>, <code class='datatype'>string</code> <code class='argument'>whence</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The seek() function repositions the offset of the open file - associated with the file descriptor fd to the argument <code>offset</code> - according to the directive <code>whence</code> as follows: - <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_SET</code></code></td><td>The offset is set to <code>offset</code> bytes. - </td></tr> - <tr><td><code><code class='key'>Stdio.SEEK_CUR</code></code></td><td>The offset is set to its current location plus <code>offset</code> bytes. - </td></tr> - <tr><td><code><code class='key'>Stdio.SEEK_END</code></code></td><td>The offset is set to the size of the file plus <code>offset</code> bytes. - </td></tr> - </table>If <code>whence</code> is not specified it is SEEK_SET if <code>offset</code> is - positive, and if <code>offset</code> is negative SEEK_END. - The seek() function on most operating systems allows the file - offset to be set beyond the end of the file (but this does not - change the size of the file). If data is later written at this - point, subsequent reads of the data in the gap (a "hole") return - null bytes ('\0') until data is actually written into the gap. - Seeking file data and holes - Stdio.SEEK_DATA and Stdio.SEEK_HOLE are nonstandard extensions - present in Linux, Solaris, FreeBSD, and DragonFly BSD; they are - proposed for inclusion in the next POSIX revision. - <table class='box'><tr><td><code><code class='key'>Stdio.SEEK_DATA</code></code></td><td>Adjust the file offset to the next location in the file greater - than or equal to offset containing data. If offset points to - data, then the file offset is set to offset. - </td></tr> - <tr><td><code><code class='key'>Stdio.SEEK_HOLE</code></code></td><td>Adjust the file offset to the next hole in the file greater than - or equal to offset. If offset points into the middle of a hole, - then the file offset is set to offset. If there is no hole past - offset, then the file offset is adjusted to the end of the file - (i.e., there is an implicit hole at the end of any file). - </td></tr> - </table>In both of the above cases, seek() fails if offset points past the - end of the file. - These operations allow applications to map holes in a sparsely - allocated file. This can be useful for applications such as file - backup tools, which can save space when creating backups and - preserve holes, if they have a mechanism for discovering holes. - For the purposes of these operations, a hole is a sequence of - zeros that (normally) has not been allocated in the underlying - file storage. However, a filesystem is not obliged to report - holes, so these operations are not a guaranteed mechanism for - mapping the storage space actually allocated to a file. - (Furthermore, a sequence of zeros that actually has been written - to the underlying storage may or may not be reported as a hole.) - In the simplest implementation, a filesystem can support the - operations by making SEEK_HOLE always return the offset of the end - of the file, and making SEEK_DATA always return offset (i.e., even - if the location referred to by offset is a hole, it can be - considered to consist of data that is a sequence of zeros). - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Upon successful completion, seek() returns the resulting offset - location as measured in bytes from the beginning of the file. On - error, the value (off_t) -1 is returned and <code>errno</code> is set to - indicate the error. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>tell()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - seek - </dt> - <dd><code><code class='modifier'>variant</code> <code class='deprecated'>__deprecated__</code> <code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>unit</code>, <code class='datatype'>int</code> <code class='argument'>mult</code>)</code> - <code><code class='modifier'>variant</code> <code class='deprecated'>__deprecated__</code> <code class='datatype'>int</code> seek(<code class='datatype'>int</code> <code class='argument'>unit</code>, <code class='datatype'>int</code> <code class='argument'>mult</code>, <code class='datatype'>int</code> <code class='argument'>add</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Seek to a specified offset in a file. - If <code>mult</code> or <code>add</code> are specified, <code>pos</code> is calculated as - <code class='expr'><code>pos</code> = <code>unit</code>*<code>mult</code> + <code>add</code></code>. - If <code>pos</code> is negative then it is relative to the end of the file, - otherwise it's an absolute offset from the start of the file. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the new offset, or <code class='expr'>-1</code> on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The arguments <code>mult</code> and <code>add</code> are considered obsolete, and - should not be used. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>tell()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - send_fd - </dt> - <dd><code><code class='datatype'>void</code> send_fd(<code class='object unresolved'>Stdio.Fd</code> <code class='argument'>fd</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Queues an open file descriptor for sending to the other end of a stream. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The actual sending is performed at the next successful call - to <code>write()</code>, this is due to limitations in the system calls. - This means that it isn't possible to send a file descriptor - without also sending some in-band data. - This operation is only supported on <code>pipe()</code>'s created with - <code>PROP_SEND_FD</code>. - This function is not available on all operating systems, check - for <code>__HAVE_SEND_FD__</code>. - The queue is emptied on successful <code>write()</code> and when the - write direction is <code>close()</code>'d. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>receive_fd()</code>, <code>write()</code>, <code>pipe()</code>, <code>read()</code>, <code>__HAVE_SEND_FD__</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_backend - </dt> - <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the backend used for the callbacks. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The backend keeps a reference to this object only when it is in - callback mode. So if this object hasn't got any active callbacks - and it runs out of other references, it will still be destructed - quickly (after closing, if necessary). - Also, this object does not keep a reference to the backend. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_backend</code>, <code>set_nonblocking</code>, <code>set_read_callback</code>, <code>set_write_callback</code>, <code>set_fs_event_callback</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_blocking - </dt> - <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets this file to blocking operation. - This is the inverse operation of <code>set_nonblocking()</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_nonblocking()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_buffer - </dt> - <dd><code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set internal socket buffer. - This function sets the internal buffer size of a socket or stream. - The second argument allows you to set the read or write buffer by - specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It is not guaranteed that this function actually does anything, - but it certainly helps to increase data transfer speed when it does. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open_socket()</code>, <code>accept()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_close_on_exec - </dt> - <dd><code><code class='datatype'>void</code> set_close_on_exec(<code class='datatype'>bool</code> <code class='argument'>yes_no</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Marks the file as to be closed in spawned processes. - This function determines whether this file will be closed when - calling exec(). - Default is that the file WILL be closed on exec except for - stdin, stdout and stderr. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Process.create_process()</code>, <code>exec()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_keepalive - </dt> - <dd><code><code class='datatype'>bool</code> set_keepalive(<code class='datatype'>bool</code> <code class='argument'>on_off</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Equivalent to setsockopt(Stdio.SO_KEEPALIVE, on_off), but will set errno - if SO_KEEPALIVE is not supported, rather than issuing a compilation error - for the missing constant. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_nodelay - </dt> - <dd><code><code class='datatype'>bool</code> set_nodelay(<code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>state</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Control Nagle's Algorithm (RFC 896) - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>state</code></dt> - <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='key'>0</code></code></td><td>Return to the normal state of using Nagle's Algorithm - </td></tr> - <tr><td><code><code class='key'>1</code></code></td><td>(default) Disable Nagling - small writes will not be queued. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This operation is only valid on sockets. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'>setsockopt() - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_nonblocking - </dt> - <dd><code><code class='datatype'>void</code> set_nonblocking()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets this file to nonblocking operation. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Nonblocking operation is not supported on all Stdio.File objects. - Notably it is not guaranteed to be supported on objects returned - by <code>pipe()</code> unless <code>PROP_NONBLOCK</code> was specified in the call - to <code>pipe()</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_blocking()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - setsockopt - </dt> - <dd><code><code class='datatype'>bool</code> setsockopt(<code class='datatype'>int</code> <code class='argument'>level</code>, <code class='datatype'>int</code> <code class='argument'>opt</code>, <code class='datatype'>int</code> <code class='argument'>state</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set socket options like Stdio.SO_KEEPALIVE. This function is always - available; the presence or absence of the option constants indicates - availability of those features. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>1 if successful, 0 if not (and sets errno()) - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_keepalive()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - setxattr - </dt> - <dd><code><code class='datatype'>void</code> setxattr(<code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the attribute <code>attr</code> to the value <code>value</code>. - The flags parameter can be used to refine the semantics of the operation. - <code>Stdio.XATTR_CREATE</code> specifies a pure create, which - fails if the named attribute exists already. - <code>Stdio.XATTR_REPLACE</code> specifies a pure replace operation, which - fails if the named attribute does not already exist. - By default (no flags), the extended attribute will be created if need be, - or will simply replace the value if the attribute exists. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>1 if successful, 0 otherwise, setting errno. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - stat - </dt> - <dd><code><code class='object unresolved'>Stat</code> stat()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get status for an open file. - This function returns the same information as the function - <code>file_stat()</code>, but for the file it is called in. If file is not - an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned - if file is a pipe or socket. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>See <code>file_stat()</code> for a description of the return value. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>file_stat()</code>, <code>statat()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - statat - </dt> - <dd><code><code class='object unresolved'>Stat</code> statat(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get status for a file relative an open directory. - This function returns the same information as the function - <code>file_stat()</code>, but relative to the file it is called in. If file is not - an open file, <code class='expr'>0</code> (zero) is returned. Zero is also returned - if file is a pipe or socket. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>See <code>file_stat()</code> for a description of the return value. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Not available on all architectures. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>file_stat()</code>, <code>stat()</code>, <code>openat()</code>, <code>unlinkat()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sync - </dt> - <dd><code><code class='datatype'>bool</code> sync()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Flush buffers to disk. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>0</code> (zero) and sets errno on failure. - Returns <code class='expr'>1</code> on success. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - take_fd - </dt> - <dd><code><code class='datatype'>void</code> take_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Rehooks the given file descriptor number to be associated with - this object. As opposed to using <code>open</code> with a file descriptor - number, it will be closed by this object upon destruct or when - <code>close</code> is called. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>release_fd()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method + tcdrain </dt> <dd><code><code class='datatype'>bool</code> tcdrain()</code></dd>
8686: <dt class='head--doc'>See also</dt> <dd class='body--doc'><code>tcgetattr()</code>, <code>tcsetattr()</code> </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - tell - </dt> - <dd><code><code class='datatype'>int</code> tell()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the current offset in the file. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>seek()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - truncate - </dt> - <dd><code><code class='datatype'>bool</code> truncate(<code class='datatype'>int</code> <code class='argument'>length</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Truncate a file. - Truncates the file to the specified length <code>length</code>. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> (zero) on failure. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - trylock - </dt> - <dd><code><code class='object unresolved'>Stdio.FileLockKey</code> trylock()</code> - <code><code class='object unresolved'>Stdio.FileLockKey</code> trylock(<code class='datatype'>bool</code> <code class='argument'>is_recursive</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Attempts to place a file lock on this file. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>lock()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - unlinkat - </dt> - <dd><code><code class='datatype'>int</code> unlinkat(<code class='datatype'>string</code> <code class='argument'>f</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Remove a file or directory relative to an open file. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>0</code> (zero) on failure, <code class='expr'>1</code> otherwise. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>rm()</code>, <code>openat()</code>, <code>statat()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - write - </dt> - <dd><code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>data</code>)</code> - <code><code class='datatype'>int</code> write(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code> - <code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>data</code>)</code> - <code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code> - <code><code class='datatype'>int</code> write(<code class='object unresolved'>Stdio.Buffer</code>|<code class='object unresolved'>String.Buffer</code>|<code class='object unresolved'>System.Memory</code> <code class='argument'>data</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..)</code> <code class='argument'>offset</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write data to a file or a stream. - If there are any file descriptors that have been queued for sending - (with <code>send_fd()</code>), they will be sent. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>data</code></dt> - <dd></dd><dd class='body--doc'>Data to write. - If <code>data</code> is an array of strings, they are written in sequence. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>format</code></dt> - <dd></dd> - <dt class='head--doc'>Parameter <code class='parameter'>extras</code></dt> - <dd></dd><dd class='body--doc'>If more than one argument is given, <code>sprintf()</code> is used to format - them using <code>format</code>. If <code>format</code> is an array, the strings in it - are concatenated and the result is used as format string. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>offset</code></dt> - <dd></dd><dd class='body--doc'>The offset in data to start writing from. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Writes <code>data</code> and returns the number of bytes that were - actually written. - <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td>The number of bytes successfully written to the OS buffers. - This can be less than the size of the given data if eg: - <ul> - <li>Some data was written successfully and then something went - wrong. - If only some data was written due to an error and that error - persists, then a later call to <code>write()</code> will fail and return - <code class='expr'>-1</code>. - </li><li>Nonblocking mode is used and not all data could be written - without blocking. - </li></ul> - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td>No bytes were written. This may be due to - <ul> - <li><code>data</code> or the formatted data being the empty string. - </li><li>Nonblocking mode is used and no data could be written - without blocking. - </li></ul> - </td></tr> - <tr><td><code><code class='key'>-1</code></code></td><td>Something went wrong and no bytes were written. - </td></tr> - </table>If everything went fine, a call to <code>errno()</code> directly afterwards - returns zero. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Writing of wide strings is not supported. You have to encode the - data somehow, e.g. with <code>string_to_utf8</code> or with one of the - charsets supported by <code>Charset.encoder</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The variant of this function using a buffer object does not release - the interpreter lock. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code>, <code>write_oob()</code>, <code>send_fd()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - write_oob - </dt> - <dd><code><code class='datatype'>int</code> write_oob(<code class='datatype'>string</code> <code class='argument'>data</code>)</code> - <code><code class='datatype'>int</code> write_oob(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write out-of-band data to a stream. - Writes out-of-band data to a stream and returns how many bytes - that were actually written. It can be less than the size of the - given data if some data was written successfully and then - something went wrong. - -1 is returned if something went wrong and no bytes were written. - If only some data was written due to an error and that error - persists, then a later call to <code>write_oob()</code> fails and returns - -1. - If everything went fine, a call to <code>errno()</code> directly afterwards - returns zero. - If more than one argument is given, <code>sprintf()</code> is used to format - them. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It is not guaranteed that all out-of-band data sent from the - other end is received. Most streams only allow for a single byte - of out-of-band data at a time. Some streams sends the rest of - the data as ordinary data. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_oob()</code>, <code>write()</code> - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Fd_ref</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Proxy class that contains stub functions - that call the corresponding functions in - <code>Fd</code>. - Used by <code>Stdio.File</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is not the class you want. Use <code>Stdio.File</code> and friends instead. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File</code>, <code>Stdio.FILE</code>, <code>_Stdio.Fd</code> - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Variable - _fd - </dt> - <dd><code><code class='object unresolved'>Fd</code> Stdio.Fd_ref._fd</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Object to which called functions are relayed. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Inherit - Fd - </dt> - <dd><code>inherit Fd : Fd</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Fake inherit to propagate the documentation - from <code>_Stdio.Fd</code>. - </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>

autodoc.git/ traditional_manual/ chapter_9.html

2020-05-13

2020-05-13 13:27:50 by Henrik Grubbström (Grubba) <grubba@grubba.org>