From 97e5b1043e8674c113f29439e646ac11b9894192 Mon Sep 17 00:00:00 2001 From: Torben Wilson Date: Sun, 27 Aug 2000 21:14:11 +0000 Subject: [PATCH] Started documenting the sockets extenstion. Re-ordered a couple of things. Fixed one typo in fsockopen(). git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@31391 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/network.xml | 610 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 538 insertions(+), 72 deletions(-) diff --git a/functions/network.xml b/functions/network.xml index b9a0c169b5..b02ea3fbad 100644 --- a/functions/network.xml +++ b/functions/network.xml @@ -2,6 +2,183 @@ Network Functions Network + + + accept_connect + Accepts a connection on a socket. + + + Description + + + int accept_connect + int socket + + + + + After the socket socket has been created + using socket, bound to a name with + bind, and told to listen for connections + with listen, this function will accept + incoming connections on that socket. Once a successful connection + is made, a new socket descriptor is returned, which may be used + for communication. If there are multiple connections queued on + the socket, the first will be used. If there are no pending + connections, accept_connect will block until + a connection becomes present. If socket + has been made non-blocking using + socket_set_blocking or + set_nonblock, an error code will be + returned. + + + + The socket descriptor returned by + accept_connect may not be used to accept new + connections. The original listening socket + socket, however, remains open and may be + reused. + + + + Returns a new socket descriptor on success, or a negative error + code on failure. This code may be passed to + strerror to get a textual explanation of the + error. + + + + See the documentation for bind for an + example of using accept_connect. + + + + See also + bind, + connect, + listen, + socket, and + strerror. + + + + + + + + bind + Binds a name to a socket. + + + Description + + + int bind + int socket + string address + int + protocol + + + + + + bind binds the name given in + address to the socket described by + socket, which must be a valid socket + descriptor created with socket. + + + + The address parameter is either an IP + address in dotted-quad notation + (e.g. 127.0.0.1), if the socket is of the + AF_INET family; or the pathname of a + Unix-domain socket, if the socket family is + AF_UNIX. + + + + The port parameter is only used when + connecting to an AF_INET socket, and + designates the port on the remote host to which a connection + should be made. + + + + Returns zero on success, or a negative error code on + failure. This code may be passed to strerror + to get a textual explanation of the error. + + + + + <function>bind</function> Example + +<?php +error_reporting(E_ALL); + +/* Allow the script to hang around waiting for connections. */ +set_time_limit(0); + +if (($sock = socket(AF_INET, SOCK_STREAM, 0)) < 0) { + echo "socket() failed: reason: " . strerror($sock) . "\n"; +} + +if (($ret = bind($sock, '192.168.1.53', 10001)) < 0) { + echo "bind() failed: reason: " . strerror($ret) . "\n"; +} + +if (($ret = listen($sock, 5)) < 0) { + echo "listen() failed: reason: " . strerror($ret) . "\n"; +} + +do { + if (($msgsock = accept_connect($sock)) < 0) { + echo "accept_connect() failed: reason: " . strerror($msgsock) . "\n"; + break; + } + do { + $buf = ''; + $ret = read($msgsock, $buf, 2048); + if ($ret < 0) { + echo "read() failed: reason: " . strerror($ret) . "\n"; + break 2; + } + if ($ret == 0) { + break 2; + } + $buf = trim($buf); + if ($buf == 'quit') { + close($msgsock); + break 2; + } + $talkback = "PHP: You said '$buf'.\n"; + write($msgsock, $talkback, strlen($talkback)); + echo "$buf\n"; + } while (true); + close($msgsock); +} while (true); + +close($sock); +?> + + + + + + See also + accept_connect, + connect, + listen, + socket, and + strerror. + + + + + checkdnsrr @@ -66,6 +243,114 @@ + + + connect + Initiates a connection on a socket. + + + Description + + + int connect + int socket + string address + int + protocol + + + + + + Initiates a connection using the socket descriptor + socket, which must be a valid socket + descriptor created with socket. + + + + The address parameter is either an IP + address in dotted-quad notation + (e.g. 127.0.0.1), if the socket is of the + AF_INET family; or the pathname of a + Unix-domain socket, if the socket family is + AF_UNIX. + + + + The port parameter is only used when + connecting to an AF_INET socket, and + designates the port on the remote host to which a connection + should be made. + + + + Returns zero on success, or a negative error code on + failure. This code may be passed to strerror + to get a textual explanation of the error. + + + + + <function>connect</function> Example + +<?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.php.net'); + +/* Create a TCP/IP socket. */ +$socket = socket(AF_INET, SOCK_STREAM, 0); +if ($socket < 0) { + echo "socket() failed: reason: " . strerror($socket) . "\n"; +} else { + "socket() successful: " . strerror($socket) . "\n"; +} + +echo "Attempting to connect to '$address' on port '$service_port'..."; +$result = connect($socket, $address, $service_port); +if ($result < 0) { + echo "connect() failed.\nReason: ($result) " . strerror($result) . "\n"; +} else { + echo "OK.\n"; +} + +$in = "HEAD / HTTP/1.0\r\n\r\n"; +$out = ''; + +echo "Sending HTTP HEAD request..."; +write($socket, $in, strlen($in)); +echo "OK.\n"; + +echo "Reading response:\n\n"; +while (read($socket, $out, 2048)) { + echo $out; +} + +echo "Closing socket..."; +close($socket); +echo "OK.\n\n"; +?> + + + + + + See also + bind, + listen, + socket, and + strerror. + + + + + debugger_off @@ -141,11 +426,11 @@ hostname on port port. hostname may in this case be either a fully qualified domain name or an IP - address. For UDP connections, you need to explicitely specify the - the protocol: udp://hostname. For the - Unix domain, hostname will be used as the - path to the socket, port must be set to 0 - in this case. The optional timeout can be + address. For UDP connections, you need to explicitly specify the + protocol: udp://hostname. For the Unix + domain, hostname will be used as the path + to the socket, port must be set to 0 in + this case. The optional timeout can be used to set a timeout in seconds for the connect system call. @@ -449,6 +734,124 @@ if (!$fp) { + + + ip2long + + Converts a string containing an (IPv4) Internet Protocol dotted address + into a proper address. + + + + Description + + + int ip2long + string ip_address + + + + The function ip2long generates an IPv4 Internet + network address from its Internet standard format (dotted string) + representation. + + <function>Ip2long</function> Example + +<? +$ip = gethostbyname("www.php.net"); +$out = "The following URLs are equivalent:<br>\n"; +$out .= "http://www.php.net/, http://".$ip."/, and http://".ip2long($ip)."/<br>\n"; +echo $out; +?> + + + + + See also: long2ip + + + + + + + listen + Listens for a connection on a socket. + + + Description + + + int listen + int socket + int backlog + + + + + After the socket socket has been created + using socket and bound to a name with + bind, it may be told to listen for incoming + connections on socket. A maximum of + backlog incoming connections will be + queued for processing. + + + + listen is applicable only to sockets with + type SOCK_STREAM or + SOCK_SEQPACKET. + + + + Returns zero on success, or a negative error code on + failure. This code may be passed to strerror + to get a textual explanation of the error. + + + + See the documentation for bind for an + example of using listen. + + + + See also + accept_connect, + bind, + connect, + socket, and + strerror. + + + + + + + + long2ip + + Converts an (IPv4) Internet network address into a string in Internet + standard dotted format + + + + Description + + + string long2ip + int proper_address + + + + The function long2ip generates an Internet address + in dotted format (i.e.: aaa.bbb.ccc.ddd) from the proper address + representation. + + + See also: ip2long + + + + openlog @@ -515,6 +918,71 @@ if (!$fp) { + + + socket + Create a socket (endpoint for communication). + + + Description + + + int socket + int domain + int type + int protocol + + + + + Creates a communication endpoint (a socket), and returns a + descriptor to the socket. + + + + The domain parameter sets the + domain. Currently, AF_INET and + AF_UNIX are understood. + + + + The type parameter selects the socket + type. This is one of SOCK_STREAM, + SOCK_DGRAM, + SOCK_SEQPACKET, + SOCK_RAW, SOCK_RDM, or + SOCK_PACKET. + + + + protocol sets the protocol. + + + + Returns a valid socket descriptor on success, or a negative error + code on failure. This code may be passed to + strerror to get a textual explanation of the + error. + + + + For more information on the usage of socket, + as well as on the meanings of the various parameters, see the + Unix man page socket (2). + + + + See also + accept_connect, + bind, + connect, + listen, and + strerror. + + + + + socket_set_blocking @@ -544,7 +1012,7 @@ if (!$fp) { - + socket_set_timeout @@ -589,11 +1057,74 @@ if(!$fp) { set_socket_timeout but this usage is deprecated. - See also: fsockopenandfopen. + See also: fsockopen and fopen. + + + strerror + Return a string describing a socket error. + + + Description + + + string strerror + int errno + + + + + strerror takes as its + errno parameter the return value of one of + the socket functions, and returns the corresponding explanatory + text. This makes it a bit more pleasant to figure out why + something didn't work; for instance, instead of having to track + down a system include file to find out what '-111' means, you + just pass it to strerror, and it tells you + what happened. + + + + + <function>strerror</function> example + +<?php +if (($socket = socket(AF_INET, SOCK_STREAM, 0)) < 0) { + echo "socket() failed: reason: " . strerror($socket) . "\n"; +} + +if (($ret = bind($socket, '127.0.0.1', 80)) < 0) { + echo "bind() failed: reason: " . strerror($ret) . "\n"; +} +?> + + + + The expected output from the above example (assuming the script + is not run with root priviledges): + + bind() failed: reason: Permission denied + + + + + + + + See also + accept_connect, + bind, + connect, + listen, and + socket. + + + + + syslog @@ -629,71 +1160,6 @@ if(!$fp) { - - - ip2long - - Converts a string containing an (IPv4) Internet Protocol dotted address - into a proper address. - - - - Description - - - int ip2long - string ip_address - - - - The function ip2long generates an IPv4 Internet - network address from its Internet standard format (dotted string) - representation. - - <function>Ip2long</function> Example - -<? -$ip = gethostbyname("www.php.net"); -$out = "The following URLs are equivalent:<br>\n"; -$out .= "http://www.php.net/, http://".$ip."/, and http://".ip2long($ip)."/<br>\n"; -echo $out; -?> - - - - - See also: long2ip - - - - - - - long2ip - - Converts an (IPv4) Internet network address into a string in Internet - standard dotted format - - - - Description - - - string long2ip - int proper_address - - - - The function long2ip generates an Internet address - in dotted format (i.e.: aaa.bbb.ccc.ddd) from the proper address - representation. - - - See also: ip2long - - - -