MFB: Upgrade to the new-reference-structure

- Split reference.xml into book.xml, setup.xml, errors.xml and examples.xml
- Moved from reference.xml to book.xml:
  - The intro text (partintro), and link to various pages
- Moved from reference.xml to setup.xml:
  - The rest: requirements, installation, configuration, and resources
- Changed the constants section to be an <appendix>
- Changed the intro ID from <extname>.intro to intro.<extname>


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@248675 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2007-12-21 20:13:30 +00:00
parent 308201a109
commit 3f15ebba99
6 changed files with 361 additions and 246 deletions

View file

@ -0,0 +1,74 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: bundled -->
<book xml:id="book.sockets" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Sockets</title>
<!-- {{{ preface -->
<preface xml:id="intro.sockets">
&reftitle.intro;
<para>
The socket extension implements a low-level interface to the socket
communication functions based on the popular BSD sockets, providing the
possibility to act as a socket server as well as a client.
</para>
<para>
For a more generic client-side socket interface, see
<function>stream_socket_client</function>,
<function>stream_socket_server</function>,
<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>
Those unfamiliar with socket programming can find a lot
of useful material in the appropriate Unix man pages, and there is a great
deal of tutorial information on socket programming in C on the web, much
of which can be applied, with slight modifications, to socket programming
in PHP. The <link xlink:href="&url.socket.faq;">Unix Socket
FAQ</link> might be a good start.
</para>
<note>
<para>
&pecl.moved-ver;5.3.0.
</para>
</note>
</preface>
<!-- }}} -->
&reference.sockets.setup;
&reference.sockets.constants;
&reference.sockets.examples;
&reference.sockets.errors;
&reference.sockets.reference;
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -1,6 +1,6 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<section xml:id="sockets.constants" xmlns="http://docbook.org/ns/docbook">
<!-- $Revision: 1.8 $ -->
<appendix xml:id="sockets.constants" xmlns="http://docbook.org/ns/docbook">
&reftitle.constants;
&extension.constants;
<variablelist>
@ -379,7 +379,7 @@
</listitem>
</varlistentry>
</variablelist>
</section>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:

View file

@ -0,0 +1,55 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="sockets.errors" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Socket Errors</title>
<para>
The socket extension was written to provide a usable interface to the
powerful BSD sockets. Care has been taken that the functions work equally
well on Win32 and Unix implementations. Almost all of the sockets
functions may fail under certain conditions and therefore emit an
<constant>E_WARNING</constant> message describing the error. Sometimes this
doesn't happen to the desire of the developer. For example the function
<function>socket_read</function> may suddenly emit an
<constant>E_WARNING</constant> message because the connection broke
unexpectedly. It's common to suppress the warning with the
<literal>@</literal>-operator and catch the error code within the
application with the <function>socket_last_error</function> function. You
may call the <function>socket_strerror</function> function with this error
code to retrieve a string describing the error. See their description for
more information.
</para>
<note>
<para>
The <constant>E_WARNING</constant> messages generated by the socket
extension are in English though the retrieved error message will appear
depending on the current locale (<constant>LC_MESSAGES</constant>):
<programlisting role="php">
<![CDATA[
Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet
]]>
</programlisting>
</para>
</note>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,165 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="sockets.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.examples;
<para>
<example>
<title>Socket example: Simple TCP/IP server</title>
<para>
This example shows a simple talkback server. Change the
<varname>address</varname> and <varname>port</varname> variables
to suit your setup and execute. You may then connect to the
server with a command similar to: <command>telnet 192.168.1.53
10000</command> (where the address and port match your
setup). Anything you type will then be output on the server
side, and echoed back to you. To disconnect, enter 'quit'.
</para>
<programlisting role="php">
<![CDATA[
#!/usr/local/bin/php -q
<?php
error_reporting(E_ALL);
/* Allow the script to hang around waiting for connections. */
set_time_limit(0);
/* Turn on implicit output flushing so we see what we're getting
* as it comes in. */
ob_implicit_flush();
$address = '192.168.1.53';
$port = 10000;
if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}
if (socket_bind($sock, $address, $port) === false) {
echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}
if (socket_listen($sock, 5) === false) {
echo "socket_listen() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}
do {
if (($msgsock = socket_accept($sock)) === false) {
echo "socket_accept() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
break;
}
/* Send instructions. */
$msg = "\nWelcome to the PHP Test Server. \n" .
"To quit, type 'quit'. To shut down the server type 'shutdown'.\n";
socket_write($msgsock, $msg, strlen($msg));
do {
if (false === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) {
echo "socket_read() failed: reason: " . socket_strerror(socket_last_error($msgsock)) . "\n";
break 2;
}
if (!$buf = trim($buf)) {
continue;
}
if ($buf == 'quit') {
break;
}
if ($buf == 'shutdown') {
socket_close($msgsock);
break 2;
}
$talkback = "PHP: You said '$buf'.\n";
socket_write($msgsock, $talkback, strlen($talkback));
echo "$buf\n";
} while (true);
socket_close($msgsock);
} while (true);
socket_close($sock);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Socket example: Simple TCP/IP client</title>
<para>
This example shows a simple, one-shot HTTP client. It simply
connects to a page, submits a HEAD request, echoes the reply,
and exits.
</para>
<programlisting role="php">
<![CDATA[
<?php
error_reporting(E_ALL);
echo "<h2>TCP/IP Connection</h2>\n";
/* Get the port for the WWW service. */
$service_port = getservbyname('www', 'tcp');
/* Get the IP address for the target host. */
$address = gethostbyname('www.example.com');
/* Create a TCP/IP socket. */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
echo "OK.\n";
}
echo "Attempting to connect to '$address' on port '$service_port'...";
$result = socket_connect($socket, $address, $service_port);
if ($result === false) {
echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
echo "OK.\n";
}
$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: www.example.com\r\n";
$in .= "Connection: Close\r\n\r\n";
$out = '';
echo "Sending HTTP HEAD request...";
socket_write($socket, $in, strlen($in));
echo "OK.\n";
echo "Reading response:\n\n";
while ($out = socket_read($socket, 2048)) {
echo $out;
}
echo "Closing socket...";
socket_close($socket);
echo "OK.\n\n";
?>
]]>
</programlisting>
</example>
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -1,249 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
<!-- Purpose: remote.other -->
<!-- Membership: bundled -->
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.28 $ -->
<reference xml:id="ref.sockets" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Socket &Functions;</title>
<reference xml:id="ref.sockets" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Socket Functions</title>
<titleabbrev>Sockets</titleabbrev>
&reference.sockets.entities.functions;
<partintro>
</reference>
<section xml:id="sockets.intro">
&reftitle.intro;
<para>
The socket extension implements a low-level interface to the socket
communication functions based on the popular BSD sockets, providing the
possibility to act as a socket server as well as a client.
</para>
<para>
For a more generic client-side socket interface, see
<function>stream_socket_client</function>,
<function>stream_socket_server</function>,
<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>
Those unfamiliar with socket programming can find a lot
of useful material in the appropriate Unix man pages, and there is a great
deal of tutorial information on socket programming in C on the web, much
of which can be applied, with slight modifications, to socket programming
in PHP. The <link xlink:href="&url.socket.faq;">Unix Socket
FAQ</link> might be a good start.
</para>
<note>
<para>
&pecl.moved-ver;5.3.0.
</para>
</note>
</section>
<section xml:id="sockets.requirements">
&reftitle.required;
&no.requirement;
</section>
&reference.sockets.configure;
<section xml:id="sockets.configuration">
&reftitle.runtime;
&no.config;
</section>
<section xml:id="sockets.resources">
&reftitle.resources;
<para>
<function>socket_accept</function>,
<function>socket_create_listen</function> and
<function>socket_create</function> return socket recources.
</para>
</section>
&reference.sockets.constants;
<section xml:id="sockets.errors">
<title>Socket Errors</title>
<para>
The socket extension was written to provide a usable interface to the
powerful BSD sockets. Care has been taken that the functions work equally
well on Win32 and Unix implementations. Almost all of the sockets
functions may fail under certain conditions and therefore emit an
<constant>E_WARNING</constant> message describing the error. Sometimes this
doesn't happen to the desire of the developer. For example the function
<function>socket_read</function> may suddenly emit an
<constant>E_WARNING</constant> message because the connection broke
unexpectedly. It's common to suppress the warning with the
<literal>@</literal>-operator and catch the error code within the
application with the <function>socket_last_error</function> function. You
may call the <function>socket_strerror</function> function with this error
code to retrieve a string describing the error. See their description for
more information.
</para>
<note>
<para>
The <constant>E_WARNING</constant> messages generated by the socket
extension are in English though the retrieved error message will appear
depending on the current locale (<constant>LC_MESSAGES</constant>):
<programlisting role="php">
<![CDATA[
Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet
]]>
</programlisting>
</para>
</note>
</section>
<section xml:id="sockets.examples">
&reftitle.examples;
<para>
<example>
<title>Socket example: Simple TCP/IP server</title>
<para>
This example shows a simple talkback server. Change the
<varname>address</varname> and <varname>port</varname> variables
to suit your setup and execute. You may then connect to the
server with a command similar to: <command>telnet 192.168.1.53
10000</command> (where the address and port match your
setup). Anything you type will then be output on the server
side, and echoed back to you. To disconnect, enter 'quit'.
</para>
<programlisting role="php">
<![CDATA[
#!/usr/local/bin/php -q
<?php
error_reporting(E_ALL);
/* Allow the script to hang around waiting for connections. */
set_time_limit(0);
/* Turn on implicit output flushing so we see what we're getting
* as it comes in. */
ob_implicit_flush();
$address = '192.168.1.53';
$port = 10000;
if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
}
if (socket_bind($sock, $address, $port) === false) {
echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}
if (socket_listen($sock, 5) === false) {
echo "socket_listen() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
}
do {
if (($msgsock = socket_accept($sock)) === false) {
echo "socket_accept() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n";
break;
}
/* Send instructions. */
$msg = "\nWelcome to the PHP Test Server. \n" .
"To quit, type 'quit'. To shut down the server type 'shutdown'.\n";
socket_write($msgsock, $msg, strlen($msg));
do {
if (false === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) {
echo "socket_read() failed: reason: " . socket_strerror(socket_last_error($msgsock)) . "\n";
break 2;
}
if (!$buf = trim($buf)) {
continue;
}
if ($buf == 'quit') {
break;
}
if ($buf == 'shutdown') {
socket_close($msgsock);
break 2;
}
$talkback = "PHP: You said '$buf'.\n";
socket_write($msgsock, $talkback, strlen($talkback));
echo "$buf\n";
} while (true);
socket_close($msgsock);
} while (true);
socket_close($sock);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Socket example: Simple TCP/IP client</title>
<para>
This example shows a simple, one-shot HTTP client. It simply
connects to a page, submits a HEAD request, echoes the reply,
and exits.
</para>
<programlisting role="php">
<![CDATA[
<?php
error_reporting(E_ALL);
echo "<h2>TCP/IP Connection</h2>\n";
/* Get the port for the WWW service. */
$service_port = getservbyname('www', 'tcp');
/* Get the IP address for the target host. */
$address = gethostbyname('www.example.com');
/* Create a TCP/IP socket. */
$socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
if ($socket === false) {
echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n";
} else {
echo "OK.\n";
}
echo "Attempting to connect to '$address' on port '$service_port'...";
$result = socket_connect($socket, $address, $service_port);
if ($result === false) {
echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n";
} else {
echo "OK.\n";
}
$in = "HEAD / HTTP/1.1\r\n";
$in .= "Host: www.example.com\r\n";
$in .= "Connection: Close\r\n\r\n";
$out = '';
echo "Sending HTTP HEAD request...";
socket_write($socket, $in, strlen($in));
echo "OK.\n";
echo "Reading response:\n\n";
while ($out = socket_read($socket, 2048)) {
echo $out;
}
echo "Closing socket...";
socket_close($socket);
echo "OK.\n\n";
?>
]]>
</programlisting>
</example>
</para>
</section>
</partintro>
&reference.sockets.entities.functions;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View file

@ -0,0 +1,58 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.2 $ -->
<chapter xml:id="sockets.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<!-- {{{ Requirements -->
<section xml:id="sockets.requirements">
&reftitle.required;
&no.requirement;
</section>
<!-- }}} -->
<!-- {{{ Installation -->
&reference.sockets.configure;
<!-- }}} -->
<!-- {{{ Configuration -->
<section xml:id="sockets.configuration">
&reftitle.runtime;
&no.config;
</section>
<!-- }}} -->
<!-- {{{ Resources -->
<section xml:id="sockets.resources">
&reftitle.resources;
<para>
<function>socket_accept</function>,
<function>socket_create_listen</function> and
<function>socket_create</function> return socket recources.
</para>
</section>
<!-- }}} -->
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->