autodoc.git/ traditional_manual/ chapter_9.html

Branch: Tag:

2014-07-12

2014-07-12 09:11:55 by Henrik Grubbström (Grubba) <grubba@grubba.org>

Stdio.File: Improved documentation of write().

Restructured and more details about behaviour in nonblocking mode.

2035:      <dt class='head--doc'>Description</dt>   <dd class='body--doc'><p>Write data to a file or a stream.</p> - <p> Writes <code>data</code> and returns the number of bytes that were -  actually written. It can be less than the size of the given data if</p> + <p> If there are any file descriptors that have been queued for sending +  (with <code>send_fd()</code>), they will be sent.</p> + </dd> + <dt class='head--doc'><span id='p-data'></span>Parameter <code class='parameter'>data</code></dt> + <dd></dd><dd class='body--doc'><p>Data to write.</p> + <p> If <code>data</code> is an array of strings, they are written in sequence.</p> + </dd> + <dt class='head--doc'><span id='p-format'></span>Parameter <code class='parameter'>format</code></dt> + <dd></dd> + <dt class='head--doc'><span id='p-extras'></span>Parameter <code class='parameter'>extras</code></dt> + <dd></dd><dd class='body--doc'><p>If more than one argument is given, <code>sprintf()</code> is used to format +  them using <code>format</code>. If <code>format</code> is an array, the strings in it +  are concatenated and the result is used as format string.</p> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>Writes <code>data</code> and returns the number of bytes that were +  actually written.</p> + <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td><p>The number of bytes successfully written to the OS buffers.</p> + <p> This can be less than the size of the given data if eg:</p>   <ul> - <li><p>some data was written successfully and then something went -  wrong, or</p> - </li><li><p>nonblocking mode is used and not all data could be written + <li><p>Some data was written successfully and then something went +  wrong.</p> + <p> If only some data was written due to an error and that error +  persists, then a later call to <code>write()</code> will fail and return +  <code class='expr'>-1</code>.</p> + </li><li><p>Nonblocking mode is used and not all data could be written    without blocking.</p> - </li></ul><p>-1 is returned if something went wrong and no bytes were written. -  If only some data was written due to an error and that error -  persists, then a later call to <code>write()</code> fails and returns -1.</p> - <p> If everything went fine, a call to <code>errno()</code> directly afterwards + </li></ul> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td><p>No bytes were written. This may be due to</p> + <ul> + <li><p><code>data</code> or the formatted data being the empty string.</p> + </li><li><p>Nonblocking mode is used and no data could be written +  without blocking.</p> + </li></ul> + </td></tr> + <tr><td><code><code class='key'>-1</code></code></td><td><p>Something went wrong and no bytes were written.</p> + </td></tr> + </table><p>If everything went fine, a call to <code>errno()</code> directly afterwards    returns zero.</p> - <p> If <code>data</code> is an array of strings, they are written in sequence.</p> - <p> If more than one argument is given, <code>sprintf()</code> is used to format -  them using <code>format</code>. If <code>format</code> is an array, the strings in it -  are concatenated and the result is used as format string.</p> - <p> If there are any file descriptors that have been queued for sending -  (with <code>send_fd()</code>), they will be sent.</p> +    </dd>   <dt class='head--doc'>Note</dt>   <dd class='body--doc'><p>Writing of wide strings is not supported. You have to encode the