cvs: phpdoc / manual.xml.in /en/appendices transports.xml wrappers.xml /en/reference/network/functions fsockopen.xml /en/reference/stream/functions
stream-socket-client.xml stream-socket-server.xml

pollita Sat Apr 26 23:46:16 2003 EDT Added files: /phpdoc/en/appendices transports.xml Modified files: /phpdoc manual.xml.in /phpdoc/en/appendices wrappers.xml /phpdoc/en/reference/network/functions fsockopen.xml /phpdoc/en/reference/stream/functions stream-socket-client.xml stream-socket-server.xml Log: Document transports including recently added ssl:// transport context options and add additional documentation to fsockopen() stream_socket_client() stream_socket_server() and the wrappers appendix.

Index: phpdoc/manual.xml.in diff -u phpdoc/manual.xml.in:1.142 phpdoc/manual.xml.in:1.143 --- phpdoc/manual.xml.in:1.142 Fri Mar 14 04:21:05 2003 +++ phpdoc/manual.xml.in Sat Apr 26 23:46:16 2003 @@ -236,6 +236,7 @@ &appendices.reserved; &appendices.resources; &appendices.wrappers; + &appendices.transports; &appendices.tokens; &appendices.about; &global.function-index; Index: phpdoc/en/appendices/wrappers.xml diff -u phpdoc/en/appendices/wrappers.xml:1.15 phpdoc/en/appendices/wrappers.xml:1.16 --- phpdoc/en/appendices/wrappers.xml:1.15 Sat Apr 26 16:03:15 2003 +++ phpdoc/en/appendices/wrappers.xml Sat Apr 26 23:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.15 $ --> +<!-- $Revision: 1.16 $ --> <appendix id="wrappers"> <title>List of Supported Protocols/Wrappers</title> <para> @@ -99,6 +99,18 @@ </tgroup> </table> </para> + + <note> + <title>Underlying socket stream context options</title> + <simpara> + Additional context options may be supported by the + <link linkend="transports.inet">underlying transport</link> + For <literal>http://</literal> streams, refer to context + options for the <literal>tcp://</literal> transport. For + <literal>https://</literal> streams, refer to context options + for the <literal>ssl://</literal> transport. + </simpara> + </note> </section> <section id="wrappers.ftp"> @@ -170,6 +182,17 @@ </tgroup> </table> </para> + <note> + <title>Underlying socket stream context options</title> + <simpara> + Additional context options may be supported by the + <link linkend="transports.inet">underlying transport</link> + For <literal>ftp://</literal> streams, refer to context + options for the <literal>tcp://</literal> transport. For + <literal>ftps://</literal> streams, refer to context options + for the <literal>ssl://</literal> transport. + </simpara> + </note> </section> <section id="wrappers.php"> Index: phpdoc/en/reference/network/functions/fsockopen.xml diff -u phpdoc/en/reference/network/functions/fsockopen.xml:1.5 phpdoc/en/reference/network/functions/fsockopen.xml:1.6 --- phpdoc/en/reference/network/functions/fsockopen.xml:1.5 Fri Apr 11 08:44:32 2003 +++ phpdoc/en/reference/network/functions/fsockopen.xml Sat Apr 26 23:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.5 $ --> +<!-- $Revision: 1.6 $ --> <!-- splitted from ./en/functions/network.xml, last change in rev 1.2 --> <refentry id="function.fsockopen"> <refnamediv> @@ -12,26 +12,18 @@ <title>Description</title> <methodsynopsis> <type>int</type><methodname>fsockopen</methodname> - <methodparam><type>string</type><parameter>hostname</parameter></methodparam> + <methodparam><type>string</type><parameter>target</parameter></methodparam> <methodparam><type>int</type><parameter>port</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>errno</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>errstr</parameter></methodparam> <methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam> </methodsynopsis> <para> - Initiates a stream connection in the Internet (AF_INET, using TCP - or UDP) or Unix (AF_UNIX) domain. For the Internet domain, it - will open a TCP socket connection to - <parameter>hostname</parameter> on port - <parameter>port</parameter>. <parameter>hostname</parameter> may - in this case be either a fully qualified domain name or an IP - address. For UDP connections, you need to explicitly specify the - protocol by prefixing <parameter>hostname</parameter> with - '<literal>udp://</literal>'. For the Unix domain, - <parameter>hostname</parameter> will be used as the path to the - socket, <parameter>port</parameter> must be set to 0 in this - case. The optional <parameter>timeout</parameter> can be used to - set a timeout in seconds for the connect system call. + Initiates a socket connection to the resource specified by + <parameter>target</parameter>. <literal>PHP</literal> supports + targets in the Internet and Unix domains as described in + <xref linkend="transports"/>. A list of supported transports + can also be retrieved using <function>stream_get_transports</function>. </para> <note> <simpara> Index: phpdoc/en/reference/stream/functions/stream-socket-client.xml diff -u phpdoc/en/reference/stream/functions/stream-socket-client.xml:1.3 phpdoc/en/reference/stream/functions/stream-socket-client.xml:1.4 --- phpdoc/en/reference/stream/functions/stream-socket-client.xml:1.3 Fri Apr 11 08:44:32 2003 +++ phpdoc/en/reference/stream/functions/stream-socket-client.xml Sat Apr 26 23:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <refentry id="function.stream-socket-client"> <refnamediv> <refname>stream_socket_client</refname> @@ -71,6 +71,7 @@ Depending on the environment, the Unix domain or the optional connect timeout may not be available. A list of available transports can be retrieved using <function>stream_get_transports</function>. + See <xref linkend="transports"/> for a list of built in transports. </para> <para> The stream will by default be opened in blocking mode. You can Index: phpdoc/en/reference/stream/functions/stream-socket-server.xml diff -u phpdoc/en/reference/stream/functions/stream-socket-server.xml:1.3 phpdoc/en/reference/stream/functions/stream-socket-server.xml:1.4 --- phpdoc/en/reference/stream/functions/stream-socket-server.xml:1.3 Fri Apr 11 08:44:32 2003 +++ phpdoc/en/reference/stream/functions/stream-socket-server.xml Sat Apr 26 23:46:16 2003 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <refentry id="function.stream-socket-server"> <refnamediv> <refname>stream_socket_server</refname> @@ -53,7 +53,8 @@ <para> Depending on the environment, Unix domain sockets may not be available. A list of available transports can be retrieved using - <function>stream_get_transports</function>. + <function>stream_get_transports</function>. See + <xref linkend="transports"/> for a list of bulitin transports. </para> <para> <function>stream_socket_server</function>. Index: phpdoc/en/appendices/transports.xml +++ phpdoc/en/appendices/transports.xml <?xml version="1.0" encoding="iso-8859-1"?> <!-- $Revision: 1.1 $ --> <appendix id="transports"> <title>List of Supported Socket Transports</title> <para> The following is a list of the various URL style socket transports that PHP has built-in for use with the streams based socket functions such as <function>fsockopen</function>, and <function>stream_socket_client</function>. These transports do <emphasis>not</emphasis> apply to the <link linkend="ref.sockets">Sockets Extension</link>. </para> <para> For a list of transports installed in your version of <literal>PHP</literal> use <function>stream_get_transports</function>. </para> <section id="transports.inet"> <title>Internet Domain: TCP, UDP, and SSL</title> <simpara>PHP 3, PHP 4. <filename>ssl://</filename> since PHP 4.3</simpara> <note> <simpara> If no transport is specified, <literal>tcp://</literal> will be assumed. </simpara> </note> <itemizedlist> <listitem><simpara><literal>127.0.0.1</literal></simpara></listitem> <listitem><simpara><literal>fe80::1</literal></simpara></listitem> <listitem><simpara><literal>www.example.com</literal></simpara></listitem> <listitem><simpara><literal>tcp://127.0.0.1</literal></simpara></listitem> <listitem><simpara><literal>tcp://fe80::1</literal></simpara></listitem> <listitem><simpara><literal>tcp://www.example.com</literal></simpara></listitem> <listitem><simpara><literal>udp://www.example.com</literal></simpara></listitem> <listitem><simpara><literal>ssl://www.example.com</literal></simpara></listitem> </itemizedlist> <simpara> Internet Domain sockets expect a port number in addition to a target address. In the case of <function>fsockopen</function> this is specified in a second parameter and therefore does not impact the formatting of transport url. With <function>stream_socket_client</function> and related functions as with traditional URLs however, the port number is speicified as a suffix of the transport URL delimited by a colon. </simpara> <itemizedlist> <listitem><simpara><literal>tcp://127.0.0.1:80</literal></simpara></listitem> <listitem><simpara><literal>tcp://[fe80::1]:80</literal></simpara></listitem> <listitem><simpara><literal>tcp://www.example.com:80</literal></simpara></listitem> </itemizedlist> <note> <title>IPv6 numeric addresses with port numbers</title> <simpara> In the second example above, while the IPv4 and hostname examples are left untouched apart from the addition of their colon and portnumber, the IPv6 address is wrapped in square brackets: <literal>[fe80::1]</literal>. This is to distinguish between the colons used in an IPv6 address and the colon used to delimit the portnumber. </simpara> </note> <simpara> The <literal>ssl://</literal> transport (available only when openssl support is compiled into PHP) is an extension of the <literal>tcp://</literal> transport which includes SSL encryption. </simpara> <para> <table> <title>Context options (as of <literal>PHP 4.3.2</literal>)</title> <tgroup cols="4"> <thead> <row> <entry>Name</entry> <entry>Usage</entry> <entry>Default</entry> <entry>Transport</entry> </row> </thead> <tbody> <row> <entry><literal>verify_peer</literal></entry> <entry> &true; or &false;. Require verification of SSL certificate used. </entry> <entry>&false;</entry> <entry><literal>ssl://</literal></entry> </row> <row> <entry><literal>cafile</literal></entry> <entry> Location of Certificate Authority file on local filesystem which should be used with the <literal>verify_peer</literal> context option to authenticate the identity of the remote peer. </entry> <entry></entry> <entry><literal>ssl://</literal></entry> </row> <row> <entry><literal>local_cert</literal></entry> <entry> Path to local certificate file on filesystem. It must be a PEM encoded file which contains your certificate and private key. It can optionally contain the certificate chain of issuers. </entry> <entry></entry> <entry><literal>ssl://</literal></entry> </row> <row> <entry><literal>passphrase</literal></entry> <entry> Passphrase with which your <literal>local_cert</literal> file was encoded. </entry> <entry></entry> </row> <row> <entry><literal>cn_match</literal></entry> <entry> Common Name we are expecting. PHP will perform limited wildcard matching. If the Common Name does not match this, the connection attempt will fail. </entry> <entry></entry> <entry><literal>ssl://</literal></entry> </row> </tbody> </tgroup> </table> </para> </section> <section id="transports.unix"> <title>Unix Domain: UNIX and UDG</title> <simpara> <literal>unix://</literal> since <literal>PHP 3</literal>, <literal>udg://</literal> since <literal>PHP 5</literal> </simpara> <itemizedlist> <listitem><simpara><literal>unix:///tmp/mysock</literal></simpara></listitem> <listitem><simpara><literal>udg:///tmp/mysock</literal></simpara></listitem> </itemizedlist> <simpara> <literal>unix://</literal> provides access to a socket stream connection in the unix domain. <literal>udg://</literal> provides an alternate transport to a unix domain socket using the user datagram protocol. </simpara> <simpara> Unix Domain sockets, unlike Internet Domain sockets, do not expect a port number. In the case of <function>fsockopen</function> the <parameter>portno</parameter> parameter should be set to 0. </simpara> </section> </appendix> <!-- 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 -->