mfischer Wed May 1 12:55:23 2002 EDT
Modified files:
/phpdoc/en/reference/sockets/functions socket-write.xml
Log:
- Update docs.
Index: phpdoc/en/reference/sockets/functions/socket-write.xml
diff -u phpdoc/en/reference/sockets/functions/socket-write.xml:1.2
phpdoc/en/reference/sockets/functions/socket-write.xml:1.3
--- phpdoc/en/reference/sockets/functions/socket-write.xml:1.2 Wed Apr 17 02:44:11
2002
+++ phpdoc/en/reference/sockets/functions/socket-write.xml Wed May 1 12:55:21
+2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.27 -->
<refentry id="function.socket-write">
<refnamediv>
@@ -10,24 +10,53 @@
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>socket_write</methodname>
-
<methodparam><type>resource</type><parameter>socket_des</parameter></methodparam>
- <methodparam><type>string</type><parameter>&buffer</parameter></methodparam>
- <methodparam><type>int</type><parameter>length</parameter></methodparam>
+ <methodparam><type>resource</type><parameter>socket</parameter></methodparam>
+ <methodparam><type>string</type><parameter>buffer</parameter></methodparam>
+ <methodparam
+choice="opt"><type>int</type><parameter>length</parameter></methodparam>
</methodsynopsis>
- &warn.experimental.func;
+ &warn.experimental.func;
<para>
The function <function>socket_write</function> writes to the socket
- <parameter>socket_des</parameter> from
- <parameter>&buffer</parameter> the number of bytes set by
- <parameter>length</parameter>.
+ <parameter>socket</parameter> from
+ <parameter>buffer</parameter>.
</para>
<para>
+ The optional parameter <parameter>length</parameter> can specify an
+ alternate length of bytes written to the socket. If this length is
+ greater then the buffer length, it is silently truncated to the length of
+ the buffer.
+ </para>
+ <para>
+ Returns the number of bytes successfully written to the socket or &false;
+ one error. The error code can be retrieved with
+ <function>socket_last_error</function>. This code may be passed to
+ <function>socket_strerror</function> to get a textual explanation of the
+ error.
+ </para>
+ <note>
+ <para>
+ <function>socket_write</function> does not necessarily write all bytes
+ from the given buffer. It's valid that, depending on the network
+ buffers etc., only a certain amount of data, even one byte, is written
+ though your buffer is greater. You have to watch out so you don't
+ unintentionally forget to transmit the rest of your data.
+ </para>
+ </note>
+ <note>
+ <para>
+ It is perfectly valid for <function>socket_write</function> to
+ return zero which means no bytes have been written. Be sure to use the
+ <literal>===</literal> operator to check for &false; in case of an
+ error.
+ </para>
+ </note>
+ <para>
See also
<function>socket_accept</function>,
<function>socket_bind</function>,
<function>socket_connect</function>,
<function>socket_listen</function>,
- <function>socket_read</function>, and
+ <function>socket_read</function> and
<function>socket_strerror</function>.
</para>
</refsect1>
