autodoc.git
/
traditional_manual
/
chapter_9.html
version
»
Context lines:
10
20
40
80
file
none
3
autodoc.git/traditional_manual/chapter_9.html:2028:
<dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>write</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>data</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>write</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extras</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Write data to a file or a stream.</p>
-
<p> 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 data somehow, e.g. with <code>string_to_utf8</code> or with one of the charsets supported by <code>Charset.encoder</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code>, <code>send_fd()</code></p> </dd></dl>