sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 08:58:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added socket_get_status() and some formating.

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@32587 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Egon Schmid 2000-09-12 19:58:00 +00:00
parent 5bd85e3e17
commit b2d6dfc580
1 changed files with 111 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

205
functions/sockets.xml
View file

@ -1,33 +1,30 @@
<reference id="ref.sockets">
<title>Socket functions</title>
<titleabbrev>Sockets</titleabbrev>
<partintro>
<simpara>
The socket extension implements a low-level interface to the
socket communication functions, providing the possibility to act
as a socket server as well as a client.
</simpara>
<para>
The socket functions described here are part of an extension to
PHP which must be enabled at compile time by giving the <option
role="configure">--enable-sockets</option> option to
<command>configure</command>.
</para>
<para>
For a more generic client-side socket interface, see
<function>fsockopen</function> and
<function>pfsockopen</function>.
</para>
<para>
When using these functions, it is important to remember that while
many of them have identical names to their C counterparts, they
often have different declarations. Please be sure to read the
descriptions to avoid confusion.
</para>
<para>
That said, those unfamiliar with socket programming can still find
a lot of useful material in the appropriate Unix man pages, and
@ -35,7 +32,6 @@
programming in C on the web, much of which can be applied, with
slight modifications, to socket programming in PHP.
</para>
<para>
<example>
<title>Socket example: Simple TCP/IP server</title>
@ -48,61 +44,60 @@
setup). Anything you type will then be output on the server
side, and echoed back to you. To disconnect, enter 'quit'.
</para>
<programlisting>
<programlisting role="php">
&lt;?php
error_reporting(E_ALL);
error_reporting (E_ALL);
/* Allow the script to hang around waiting for connections. */
set_time_limit(0);
set_time_limit (0);
$address = '192.168.1.53';
$port = 10000;
if (($sock = socket(AF_INET, SOCK_STREAM, 0)) &lt; 0) {
echo "socket() failed: reason: " . strerror($sock) . "\n";
if (($sock = socket (AF_INET, SOCK_STREAM, 0)) &lt; 0) {
echo "socket() failed: reason: " . strerror ($sock) . "\n";
}
if (($ret = bind($sock, $address, $port)) &lt; 0) {
echo "bind() failed: reason: " . strerror($ret) . "\n";
if (($ret = bind ($sock, $address, $port)) &lt; 0) {
echo "bind() failed: reason: " . strerror ($ret) . "\n";
}
if (($ret = listen($sock, 5)) &lt; 0) {
echo "listen() failed: reason: " . strerror($ret) . "\n";
if (($ret = listen ($sock, 5)) &lt; 0) {
echo "listen() failed: reason: " . strerror ($ret) . "\n";
}
do {
if (($msgsock = accept_connect($sock)) &lt; 0) {
echo "accept_connect() failed: reason: " . strerror($msgsock) . "\n";
echo "accept_connect() failed: reason: " . strerror ($msgsock) . "\n";
break;
}
do {
$buf = '';
$ret = read($msgsock, $buf, 2048);
$ret = read ($msgsock, $buf, 2048);
if ($ret &lt; 0) {
echo "read() failed: reason: " . strerror($ret) . "\n";
echo "read() failed: reason: " . strerror ($ret) . "\n";
break 2;
}
if ($ret == 0) {
break 2;
}
$buf = trim($buf);
$buf = trim ($buf);
if ($buf == 'quit') {
close($msgsock);
close ($msgsock);
break 2;
}
$talkback = "PHP: You said '$buf'.\n";
write($msgsock, $talkback, strlen($talkback));
write ($msgsock, $talkback, strlen ($talkback));
echo "$buf\n";
} while (true);
close($msgsock);
close ($msgsock);
} while (true);
close($sock);
close ($sock);
?>
</programlisting>
</example>
</para>
<para>
<example>
<title>Socket example: Simple TCP/IP client</title>
@ -113,26 +108,26 @@ close($sock);
</para>
<programlisting>
&lt;?php
error_reporting(E_ALL);
error_reporting (E_ALL);
echo "&lt;h2>TCP/IP Connection&lt;/h2>\n";
/* Get the port for the WWW service. */
$service_port = getservbyname('www', 'tcp');
$service_port = getservbyname ('www', 'tcp');
/* Get the IP address for the target host. */
$address = gethostbyname('www.php.net');
$address = gethostbyname ('www.php.net');
/* Create a TCP/IP socket. */
$socket = socket(AF_INET, SOCK_STREAM, 0);
$socket = socket (AF_INET, SOCK_STREAM, 0);
if ($socket &lt; 0) {
echo "socket() failed: reason: " . strerror($socket) . "\n";
echo "socket() failed: reason: " . strerror ($socket) . "\n";
} else {
"socket() successful: " . strerror($socket) . "\n";
"socket() successful: " . strerror ($socket) . "\n";
}
echo "Attempting to connect to '$address' on port '$service_port'...";
$result = connect($socket, $address, $service_port);
$result = connect ($socket, $address, $service_port);
if ($result &lt; 0) {
echo "connect() failed.\nReason: ($result) " . strerror($result) . "\n";
} else {
@ -143,28 +138,27 @@ $in = "HEAD / HTTP/1.0\r\n\r\n";
$out = '';
echo "Sending HTTP HEAD request...";
write($socket, $in, strlen($in));
write ($socket, $in, strlen ($in));
echo "OK.\n";
echo "Reading response:\n\n";
while (read($socket, $out, 2048)) {
while (read ($socket, $out, 2048)) {
echo $out;
}
echo "Closing socket...";
close($socket);
close ($socket);
echo "OK.\n\n";
?>
</programlisting>
</example>
</para>
</partintro>
<refentry id="function.accept-connect">
<refnamediv>
<refname>accept_connect</refname>
<refpurpose>Accepts a connection on a socket.</refpurpose>
<refpurpose>Accepts a connection on a socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -174,7 +168,6 @@ echo "OK.\n\n";
<paramdef>int <parameter>socket</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
After the socket <parameter>socket</parameter> has been created
using <function>socket</function>, bound to a name with
@ -191,7 +184,6 @@ echo "OK.\n\n";
<function>set_nonblock</function>, an error code will be
returned.
</para>
<para>
The socket descriptor returned by
<function>accept_connect</function> may not be used to accept new
@ -199,30 +191,28 @@ echo "OK.\n\n";
<parameter>socket</parameter>, however, remains open and may be
reused.
</para>
<para>
Returns a new socket descriptor on success, or a negative error
code on failure. This code may be passed to
<function>strerror</function> to get a textual explanation of the
error.
</para>
<para>
See also
<function>bind</function>,
<function>connect</function>,
<function>listen</function>,
<function>socket</function>, and
<function>socket</function>,
<function>socket_get_status</function>, and
<function>strerror</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.bind">
<refnamediv>
<refname>bind</refname>
<refpurpose>Binds a name to a socket.</refpurpose>
<refpurpose>Binds a name to a socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -236,14 +226,12 @@ echo "OK.\n\n";
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>bind</function> binds the name given in
<parameter>address</parameter> to the socket described by
<parameter>socket</parameter>, which must be a valid socket
descriptor created with <function>socket</function>.
</para>
<para>
The <parameter>address</parameter> parameter is either an IP
address in dotted-quad notation
@ -252,36 +240,33 @@ echo "OK.\n\n";
Unix-domain socket, if the socket family is
<constant>AF_UNIX</constant>.
</para>
<para>
The <parameter>port</parameter> parameter is only used when
connecting to an <constant>AF_INET</constant> socket, and
designates the port on the remote host to which a connection
should be made.
</para>
<para>
Returns zero on success, or a negative error code on
failure. This code may be passed to <function>strerror</function>
to get a textual explanation of the error.
</para>
<para>
See also
<function>accept_connect</function>,
<function>connect</function>,
<function>listen</function>,
<function>socket</function>, and
<function>socket</function>,
<function>socket_get_status</function>, and
<function>strerror</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.close">
<refnamediv>
<refname>close</refname>
<refpurpose>Closes a file descriptor.</refpurpose>
<refpurpose>Closes a file descriptor</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -291,12 +276,10 @@ echo "OK.\n\n";
<paramdef>int <parameter>socket</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>close</function> closes the file (or socket) descriptor
given by <parameter>socket</parameter>.
</para>
<para>
Note that <function>close</function> should not be used on PHP
file descriptors created with <function>fopen</function>,
@ -305,24 +288,23 @@ echo "OK.\n\n";
with <function>socket</function> or
<function>accept_connect</function>.
</para>
<para>
Returns true on success, or false if an error occurs (i.e.,
<parameter>socket</parameter> is invalid).
</para>
<para>
See also <function>bind</function>, <function>listen</function>,
<function>socket</function>, and <function>strerror</function>.
<function>socket</function>,
<function>socket_get_status</function>, and
<function>strerror</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.connect">
<refnamediv>
<refname>connect</refname>
<refpurpose>Initiates a connection on a socket.</refpurpose>
<refpurpose>Initiates a connection on a socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -336,13 +318,11 @@ echo "OK.\n\n";
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Initiates a connection using the socket descriptor
<parameter>socket</parameter>, which must be a valid socket
descriptor created with <function>socket</function>.
</para>
<para>
The <parameter>address</parameter> parameter is either an IP
address in dotted-quad notation
@ -351,35 +331,32 @@ echo "OK.\n\n";
Unix-domain socket, if the socket family is
<constant>AF_UNIX</constant>.
</para>
<para>
The <parameter>port</parameter> parameter is only used when
connecting to an <constant>AF_INET</constant> socket, and
designates the port on the remote host to which a connection
should be made.
</para>
<para>
Returns zero on success, or a negative error code on
failure. This code may be passed to <function>strerror</function>
to get a textual explanation of the error.
</para>
<para>
See also
<function>bind</function>,
<function>listen</function>,
<function>socket</function>, and
<function>socket</function>,
<function>socket_get_status</function>, and
<function>strerror</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.listen">
<refnamediv>
<refname>listen</refname>
<refpurpose>Listens for a connection on a socket.</refpurpose>
<refpurpose>Listens for a connection on a socket</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -390,7 +367,6 @@ echo "OK.\n\n";
<paramdef>int <parameter>backlog</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
After the socket <parameter>socket</parameter> has been created
using <function>socket</function> and bound to a name with
@ -399,35 +375,32 @@ echo "OK.\n\n";
<parameter>backlog</parameter> incoming connections will be
queued for processing.
</para>
<para>
<function>listen</function> is applicable only to sockets with
type <literal>SOCK_STREAM</literal> or
<literal>SOCK_SEQPACKET</literal>.
</para>
<para>
Returns zero on success, or a negative error code on
failure. This code may be passed to <function>strerror</function>
to get a textual explanation of the error.
</para>
<para>
See also
<function>accept_connect</function>,
<function>bind</function>,
<function>connect</function>,
<function>socket</function>, and
<function>socket</function>,
<function>socket_get_status</function>, and
<function>strerror</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.socket">
<refnamediv>
<refname>socket</refname>
<refpurpose>Create a socket (endpoint for communication).</refpurpose>
<refpurpose>Create a socket (endpoint for communication)</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -439,18 +412,15 @@ echo "OK.\n\n";
<paramdef>int <parameter>protocol</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Creates a communication endpoint (a socket), and returns a
descriptor to the socket.
</para>
<para>
The <parameter>domain</parameter> parameter sets the
domain. Currently, <constant>AF_INET</constant> and
<constant>AF_UNIX</constant> are understood.
</para>
<para>
The <parameter>type</parameter> parameter selects the socket
type. This is one of <constant>SOCK_STREAM</constant>,
@ -459,24 +429,77 @@ echo "OK.\n\n";
<constant>SOCK_RAW</constant>, <constant>SOCK_RDM</constant>, or
<constant>SOCK_PACKET</constant>.
</para>
<para>
<parameter>protocol</parameter> sets the protocol.
</para>
<para>
Returns a valid socket descriptor on success, or a negative error
code on failure. This code may be passed to
<function>strerror</function> to get a textual explanation of the
error.
</para>
<para>
For more information on the usage of <function>socket</function>,
as well as on the meanings of the various parameters, see the
Unix man page <filename>socket (2)</filename>.
Unix man page socket (2).
</para>
<para>
See also
<function>accept_connect</function>,
<function>bind</function>,
<function>connect</function>,
<function>listen</function>,
<function>strerror</function>, and
<function>socket_get_status</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.socket-get-status">
<refnamediv>
<refname>socket_get_status</refname>
<refpurpose>
Returns information about existing socket resource
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>socket_get_status</function></funcdef>
<paramdef>resource
<parameter>socket_get_status</parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns information about existing socket resource. Currently
returns 4 entries in the result array:
</para>
<itemizedlist>
<listitem>
<para>
<parameter>timed_out</parameter> (bool) - The socket timed out
waiting for data
</para>
</listitem>
<listitem>
<para>
<parameter>blocked</parameter> (bool) - The socket was blocked
</para>
</listitem>
<listitem>
<para>
<parameter>eof</parameter> (bool) - Indicates EOF event
</para>
</listitem>
<listitem>
<para>
<parameter>unread_bytes</parameter> (bool) - Number of bytes
left in the socket buffer
</para>
</listitem>
</itemizedlist>
<para>
See also
<function>accept_connect</function>,
@ -485,14 +508,13 @@ echo "OK.\n\n";
<function>listen</function>, and
<function>strerror</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.strerror">
<refnamediv>
<refname>strerror</refname>
<refpurpose>Return a string describing a socket error.</refpurpose>
<refpurpose>Return a string describing a socket error</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@ -502,7 +524,6 @@ echo "OK.\n\n";
<paramdef>int <parameter>errno</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>strerror</function> takes as its
<parameter>errno</parameter> parameter the return value of one of
@ -513,22 +534,20 @@ echo "OK.\n\n";
just pass it to <function>strerror</function>, and it tells you
what happened.
</para>
<para>
<example>
<title><function>strerror</function> example</title>
<programlisting>
<programlisting role="php">
&lt;?php
if (($socket = socket(AF_INET, SOCK_STREAM, 0)) &lt; 0) {
echo "socket() failed: reason: " . strerror($socket) . "\n";
if (($socket = socket (AF_INET, SOCK_STREAM, 0)) &lt; 0) {
echo "socket() failed: reason: " . strerror ($socket) . "\n";
}
if (($ret = bind($socket, '127.0.0.1', 80)) &lt; 0) {
echo "bind() failed: reason: " . strerror($ret) . "\n";
if (($ret = bind ($socket, '127.0.0.1', 80)) &lt; 0) {
echo "bind() failed: reason: " . strerror ($ret) . "\n";
}
?>
</programlisting>
<para>
The expected output from the above example (assuming the script
is not run with root privileges):
@ -536,19 +555,17 @@ if (($ret = bind($socket, '127.0.0.1', 80)) &lt; 0) {
bind() failed: reason: Permission denied
</screen>
</para>
</example>
</para>
<para>
See also
<function>accept_connect</function>,
<function>bind</function>,
<function>connect</function>,
<function>listen</function>, and
<function>socket</function>.
<function>listen</function>,
<function>socket</function>, and
<function>socket_get_status</function>.
</para>
</refsect1>
</refentry>