diff --git a/reference/sockets/book.xml b/reference/sockets/book.xml new file mode 100644 index 0000000000..dc1e2536ca --- /dev/null +++ b/reference/sockets/book.xml @@ -0,0 +1,74 @@ + + + + + + + Sockets + + + + &reftitle.intro; + + 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. + + + For a more generic client-side socket interface, see + stream_socket_client, + stream_socket_server, + fsockopen, and + pfsockopen. + + + 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. + + + 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 Unix Socket + FAQ might be a good start. + + + + &pecl.moved-ver;5.3.0. + + + + + + &reference.sockets.setup; + &reference.sockets.constants; + &reference.sockets.examples; + &reference.sockets.errors; + &reference.sockets.reference; + + + + + diff --git a/reference/sockets/constants.xml b/reference/sockets/constants.xml index 82ef93f3b0..2abca00098 100644 --- a/reference/sockets/constants.xml +++ b/reference/sockets/constants.xml @@ -1,6 +1,6 @@ - -
+ + &reftitle.constants; &extension.constants; @@ -379,7 +379,7 @@ -
+ + + Socket Errors + + 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 + E_WARNING message describing the error. Sometimes this + doesn't happen to the desire of the developer. For example the function + socket_read may suddenly emit an + E_WARNING message because the connection broke + unexpectedly. It's common to suppress the warning with the + @-operator and catch the error code within the + application with the socket_last_error function. You + may call the socket_strerror function with this error + code to retrieve a string describing the error. See their description for + more information. + + + + The E_WARNING messages generated by the socket + extension are in English though the retrieved error message will appear + depending on the current locale (LC_MESSAGES): + + + + + + + + + diff --git a/reference/sockets/examples.xml b/reference/sockets/examples.xml new file mode 100644 index 0000000000..09cc53c05b --- /dev/null +++ b/reference/sockets/examples.xml @@ -0,0 +1,165 @@ + + + + + &reftitle.examples; + + + Socket example: Simple TCP/IP server + + This example shows a simple talkback server. Change the + address and port variables + to suit your setup and execute. You may then connect to the + server with a command similar to: telnet 192.168.1.53 + 10000 (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'. + + + +]]> + + + + + + Socket example: Simple TCP/IP client + + This example shows a simple, one-shot HTTP client. It simply + connects to a page, submits a HEAD request, echoes the reply, + and exits. + + +TCP/IP Connection\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"; +?> +]]> + + + + + + + diff --git a/reference/sockets/reference.xml b/reference/sockets/reference.xml index d1a3852202..a6a27c3207 100644 --- a/reference/sockets/reference.xml +++ b/reference/sockets/reference.xml @@ -1,249 +1,12 @@ - - - - + + + + Socket &Functions; - - Socket Functions - Sockets + &reference.sockets.entities.functions; - + -
- &reftitle.intro; - - 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. - - - For a more generic client-side socket interface, see - stream_socket_client, - stream_socket_server, - fsockopen, and - pfsockopen. - - - 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. - - - 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 Unix Socket - FAQ might be a good start. - - - - &pecl.moved-ver;5.3.0. - - -
- -
- &reftitle.required; - &no.requirement; -
- - &reference.sockets.configure; - -
- &reftitle.runtime; - &no.config; -
- -
- &reftitle.resources; - - socket_accept, - socket_create_listen and - socket_create return socket recources. - -
- - &reference.sockets.constants; - -
- Socket Errors - - 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 - E_WARNING message describing the error. Sometimes this - doesn't happen to the desire of the developer. For example the function - socket_read may suddenly emit an - E_WARNING message because the connection broke - unexpectedly. It's common to suppress the warning with the - @-operator and catch the error code within the - application with the socket_last_error function. You - may call the socket_strerror function with this error - code to retrieve a string describing the error. See their description for - more information. - - - - The E_WARNING messages generated by the socket - extension are in English though the retrieved error message will appear - depending on the current locale (LC_MESSAGES): - - - - - -
- -
- &reftitle.examples; - - - Socket example: Simple TCP/IP server - - This example shows a simple talkback server. Change the - address and port variables - to suit your setup and execute. You may then connect to the - server with a command similar to: telnet 192.168.1.53 - 10000 (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'. - - - -]]> - - - - - - Socket example: Simple TCP/IP client - - This example shows a simple, one-shot HTTP client. It simply - connects to a page, submits a HEAD request, echoes the reply, - and exits. - - -TCP/IP Connection\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"; -?> -]]> - - - -
- - -&reference.sockets.entities.functions; - - + + + &reftitle.setup; + + +
+ &reftitle.required; + &no.requirement; +
+ + + + &reference.sockets.configure; + + + +
+ &reftitle.runtime; + &no.config; +
+ + + +
+ &reftitle.resources; + + socket_accept, + socket_create_listen and + socket_create return socket recources. + +
+ + + + + +