autodoc.git/ traditional_manual/ chapter_9.html

Branch: Tag:

2003-10-15

2003-10-15 17:07:00 by Martin Stjernholm <mast@lysator.liu.se>

And some more..

Rev: src/modules/files/file.c:1.297

889:   <ul>   <li><p>end-of-file is encountered for a normal file, or</p>   </li><li><p>it's a socket or pipe that has been closed from the other end, or</p> - </li><li><p>nonblocking mode is used.</p> + </li><li><p>nonblocking mode is used, or</p> + </li><li><p><code>not_all</code> isn't set and an error occurred (see below).</p>   </li></ul><p>If <code>not_all</code> is nonzero, <code>read()</code> will not try its best to read    as many bytes as you have asked for, but will merely return as    much as the system read function will return. This mainly useful    with stream devices which can return exactly one row or packet at    a time.</p>   <p> If something goes wrong and <code>not_all</code> is set, zero will be -  returned. If something goes wrong and <code>not_all</code> is not set, -  either zero or a string shorter than <code>len</code> is returned. If the -  problem persists then a later call to <code>read()</code> will fail and -  return zero, however.</p> +  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> will fail +  and return zero, however.</p>   <p> If everything went fine, a call to <code>errno()</code> directly afterwards    will return zero. That includes an end due to end-of-file or    remote close.</p>
946:   <code><code class='datatype'>string</code> <b><span class='method'>read_oob</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Read out-of-band data from a stream.</p> - <p> Attempts to read <code>len</code> bytes of out-of-band data from the stream, -  and returns it as a string. If something goes wrong, zero is returned.</p> - <p> If a one is given as the second argument to <code>read_oob()</code>, only -  as many bytes of out-of-band data as are currently available will be -  returned.</p> + <dd class='body--doc'><p>Attempts to read <code>len</code> bytes of out-of-band data from the stream, +  and returns it as a string. Less than <code>len</code> bytes can be returned if</p> + <ul> + <li><p>the stream has been closed from the other end, or</p> + </li><li><p>nonblocking mode is used, or</p> + </li><li><p><code>not_all</code> isn't set and an error occurred (see below).</p> + </li></ul><p>If <code>not_all</code> is nonzero, <code>read_oob()</code> will only return as many +  bytes of out-of-band data as are currently available.</p> + <p> If something goes wrong and <code>not_all</code> is set, zero will be +  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> will fail +  and return zero, however.</p> + <p> If everything went fine, a call to <code>errno()</code> directly afterwards +  will return zero. That includes an end due to remote close.</p>   <p> If no arguments are given, <code>read_oob()</code> will read to the end of    the stream.</p>   </dd>   <dt class='head--doc'>Note</dt>   <dd class='body--doc'><p>This function is only available if the option <tt>'--without-oob'</tt>    was not specified when the Pike runtime was compiled.</p> - <p> It is not guaranteed that all out-of-band data sent from the other end + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It is not guaranteed that all out-of-band data sent from the other end    will be received. Most streams only allow for a single byte of    out-of-band data at a time.</p>   </dd> -  + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It's not necessary to set <code>not_all</code> to avoid blocking reading +  when nonblocking mode is used.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>When at the end of a file or stream, repeated calls to <code>read()</code> +  will return the empty string since it's not considered an error. +  The empty string is never returned in other cases, unless +  nonblocking mode is used or <code>len</code> is zero.</p> + </dd>   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code></p>   </dd></dl>
1494:   <dt class='head--doc'>Note</dt>   <dd class='body--doc'><p>This function is only available if the option <tt>'--without-oob'</tt>    was not specified when the Pike runtime was compiled.</p> - <p> It is not guaranteed that all out-of-band data sent from the other end + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It is not guaranteed that all out-of-band data sent from the other end    will be received. Most streams only allow for a single byte of    out-of-band data at a time. Some streams will send the rest of the data    as ordinary data.</p>