cvs: phpdoc /en/reference/network/functions checkdnsrr.xml closelog.xml debugger-off.xml debugger-on.xml define-syslog-variables.xml
dns-check-record.xml dns-get-mx.xml dns-get-record.xml fsockopen.xml gethostbyaddr.xml gethostbyname.xml gethostbynamel.xml getmxrr.xml
getprotobyname.xml getprotobynumber.xml getservbyname.xml getservbyport.xml header.xml headers-list.xml headers-sent.xml inet-ntop.xml inet-pton.xml
ip2long.xml long2ip.xml openlog.xml pfsockopen.xml setcookie.xml setrawcookie.xml socket-get-status.xml socket-set-blocking.xml socket-set-timeout.xml
syslog.xml

From:	Mehdi Achour	Date:	Sun, 10 Jun 2007 01:57:09 +0000
Subject:	cvs: phpdoc /en/reference/network/functions checkdnsrr.xml closelog.xml debugger-off.xml debugger-on.xml define-syslog-variables.xml dns-check-record.xml dns-get-mx.xml dns-get-record.xml fsockopen.xml gethostbyaddr.xml gethostbyname.xml gethostbynamel.xml getmxrr.xml getprotobyname.xml getprotobynumber.xml getservbyname.xml getservbyport.xml header.xml headers-list.xml headers-sent.xml inet-ntop.xml inet-pton.xml ip2long.xml long2ip.xml openlog.xml pfsockopen.xml setcookie.xml setrawcookie.xml socket-get-status.xml socket-set-blocking.xml socket-set-timeout.xml syslog.xml
Groups:	php.doc
Request:	Send a blank email to phpdoc+get-969376613@lists.php.net to get a copy of this message

didou Sun Jun 10 01:57:09 2007 UTC Modified files: /phpdoc/en/reference/network/functions checkdnsrr.xml closelog.xml debugger-off.xml debugger-on.xml define-syslog-variables.xml dns-check-record.xml dns-get-mx.xml dns-get-record.xml fsockopen.xml gethostbyaddr.xml gethostbyname.xml gethostbynamel.xml getmxrr.xml getprotobyname.xml getprotobynumber.xml getservbyname.xml getservbyport.xml header.xml headers-list.xml headers-sent.xml inet-ntop.xml inet-pton.xml ip2long.xml long2ip.xml openlog.xml pfsockopen.xml setcookie.xml setrawcookie.xml socket-get-status.xml socket-set-blocking.xml socket-set-timeout.xml syslog.xml Log: ref.network: switch to new doc style #: why are (old) debugging and accurate error handling facilities located here ?

http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/network/functions/checkdnsrr.xml?r1=1.9&r2=1.10&diff_format=u Index: phpdoc/en/reference/network/functions/checkdnsrr.xml diff -u phpdoc/en/reference/network/functions/checkdnsrr.xml:1.9 phpdoc/en/reference/network/functions/checkdnsrr.xml:1.10 --- phpdoc/en/reference/network/functions/checkdnsrr.xml:1.9 Sun Jun 10 01:55:51 2007 +++ phpdoc/en/reference/network/functions/checkdnsrr.xml Sun Jun 10 01:57:08 2007 @@ -1,57 +1,107 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.checkdnsrr"> <refnamediv> <refname>checkdnsrr</refname> <refpurpose>Check DNS records corresponding to a given Internet host name or IP address</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>checkdnsrr</methodname> <methodparam><type>string</type><parameter>host</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter>type</parameter></methodparam> </methodsynopsis> - <simpara> + <para> Searches DNS for records of type <parameter>type</parameter> - corresponding to <parameter>host</parameter>. Returns &true; if any - records are found; returns &false; if no records were found or if - an error occurred. - </simpara> - <simpara> - <parameter>type</parameter> may be any one of: A, MX, NS, SOA, - PTR, CNAME, AAAA, A6, SRV, NAPTR or ANY. The default is MX. - </simpara> - <simpara> - <parameter>host</parameter> may either be the IP address in - dotted-quad notation or the host name. - </simpara> + corresponding to <parameter>host</parameter>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - <note> - <simpara> - AAAA type added with PHP 5.0.0 - </simpara> - </note> + <variablelist> + <varlistentry> + <term><parameter>host</parameter></term> + <listitem> + <para> + <parameter>host</parameter> may either be the IP address in + dotted-quad notation or the host name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem> + <para> + <parameter>type</parameter> may be any one of: A, MX, NS, SOA, + PTR, CNAME, AAAA, A6, SRV, NAPTR or ANY. The default is MX. + </para> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - <note> - <simpara> - This function is not implemented on Windows platforms. Try the - <ulink url="&url.php.pear;">PEAR</ulink> class - <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>. - </simpara> - </note> + Returns &true; if any records are found; returns &false; if no records + were found or if an error occurred. </para> - <simpara> - See also <function>dns_get_record</function>, - <function>getmxrr</function>, - <function>gethostbyaddr</function>, - <function>gethostbyname</function>, - <function>gethostbynamel</function>, and the named(8) manual - page. - </simpara> </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.0.0</entry> + <entry> + AAAA <parameter>type</parameter> was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + This function is not implemented on Windows platforms. Try the + <ulink url="&url.php.pear;">PEAR</ulink> class + <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>. + </para> + </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>dns_get_record</function></member> + <member><function>getmxrr</function></member> + <member><function>gethostbyaddr</function></member> + <member><function>gethostbyname</function></member> + <member><function>gethostbynamel</function></member> + <member>the named(8) manual page</member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.closelog"> <refnamediv> <refname>closelog</refname> <refpurpose>Close connection to system logger</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>closelog</methodname> <void/> </methodsynopsis> <para> - <function>closelog</function> closes the descriptor being used to - write to the system logger. The use of - <function>closelog</function> is optional. + <function>closelog</function> closes the descriptor being used to write to + the system logger. The use of <function>closelog</function> is optional. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also <function>define_syslog_variables</function>, - <function>syslog</function> and - <function>openlog</function>. + &return.success; </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>define_syslog_variables</function></member> + <member><function>syslog</function></member> + <member><function>openlog</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.debugger-off"> <refnamediv> <refname>debugger_off</refname> <refpurpose>Disable internal PHP debugger (PHP 3)</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>debugger_off</methodname> <void/> </methodsynopsis> <para> - Disables the internal PHP debugger. This function is only - available in PHP 3. + Disable internal PHP debugger. </para> - <simpara> - For more information see the appendix on <link - linkend="debugger">Debugging PHP</link>. - </simpara> </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns 1 on success, 0 on error. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <para> + This function is only available in PHP 3. + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><link linkend="debugger">Debugging PHP</link></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.debugger-on"> <refnamediv> <refname>debugger_on</refname> <refpurpose>Enable internal PHP debugger (PHP 3)</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>debugger_on</methodname> <methodparam><type>string</type><parameter>address</parameter></methodparam> </methodsynopsis> <para> Enables the internal PHP debugger, connecting it to - <parameter>address</parameter>. This function is only - available in PHP 3. + <parameter>address</parameter>. </para> - <simpara> - For more information see the appendix on <link - linkend="debugger">Debugging PHP</link>. - </simpara> </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>address</parameter></term> + <listitem> + <para> + The host name of the debugger. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns 1 on success, 0 on error. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <para> + This function is only available in PHP 3. + </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><link linkend="debugger">Debugging PHP</link></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.define-syslog-variables"> <refnamediv> <refname>define_syslog_variables</refname> <refpurpose>Initializes all syslog related constants</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>define_syslog_variables</methodname> <void/> @@ -15,12 +15,26 @@ <para> Initializes all constants used in the syslog functions. </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also <function>openlog</function>, - <function>syslog</function> and - <function>closelog</function>. + &return.void; </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>openlog</function></member> + <member><function>syslog</function></member> + <member><function>closelog</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  + <refentry id="function.dns-check-record"> <refnamediv> <refname>dns_check_record</refname> - <refpurpose>Synonym for <function>checkdnsrr</function></refpurpose> + <refpurpose>&Alias; <function>checkdnsrr</function></refpurpose> </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>dns_check_record</methodname> - <methodparam><type>string</type><parameter>host</parameter></methodparam> - <methodparam choice="opt"><type>string</type><parameter>type</parameter></methodparam> - </methodsynopsis> + + <refsect1 role="description"> + &reftitle.description; <para> - Check DNS records corresponding to a given Internet host name or - IP address + &info.function.alias; + <function>checkdnsrr</function>. </para> </refsect1> + </refentry>  + <refentry id="function.dns-get-mx"> <refnamediv> <refname>dns_get_mx</refname> - <refpurpose>Synonym for <function>getmxrr</function></refpurpose> + <refpurpose>&Alias; <function>getmxrr</function></refpurpose> </refnamediv> - <refsect1> - <title>Description</title> - <methodsynopsis> - <type>bool</type><methodname>dns_get_mx</methodname> - <methodparam><type>string</type><parameter>hostname</parameter></methodparam> - <methodparam><type>array</type><parameter role="reference">mxhosts</parameter></methodparam> - <methodparam choice="opt"><type>array</type><parameter role="reference">weight</parameter></methodparam> - </methodsynopsis> + + <refsect1 role="description"> + &reftitle.description; <para> - Get MX records corresponding to a given Internet host name. + &info.function.alias; + <function>getmxrr</function>. </para> </refsect1> + </refentry>  + <refentry id="function.dns-get-record"> <refnamediv> <refname>dns_get_record</refname> <refpurpose>Fetch DNS Resource Records associated with a hostname</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>dns_get_record</methodname> <methodparam><type>string</type><parameter>hostname</parameter></methodparam> @@ -15,15 +16,85 @@ <methodparam><type>array</type><parameter role="reference">addtl</parameter></methodparam> </methodsynopsis> <para> - <note> - <simpara> - This function is not implemented on Windows platforms, nor does it - (currently) work on *BSD systems. Try the - <ulink url="&url.php.pear;">PEAR</ulink> class - <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>. - </simpara> - </note> + Fetch DNS Resource Records associated with the given + <parameter>hostname</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem> + <para> + <parameter>hostname</parameter> should be a valid DNS hostname such + as "www.example.com". Reverse lookups can be generated using in-addr.arpa + notation, but <function>gethostbyaddr</function> is more suitable for + the majority of reverse lookups. + </para> + <note> + <para> + Per DNS standards, email addresses are given in user.host format (for + example: hostmaster.example.com as opposed to hostmaster@example.com), + be sure to check this value and modify if necessary before using it + with a functions such as <function>mail</function>. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter></term> + <listitem> + <para> + By default, <function>dns_get_record</function> will search for any + resource records associated with <parameter>hostname</parameter>. + To limit the query, specify the optional <parameter>type</parameter> + parameter. May be any one of the following: + <constant>DNS_A</constant>, <constant>DNS_CNAME</constant>, + <constant>DNS_HINFO</constant>, <constant>DNS_MX</constant>, + <constant>DNS_NS</constant>, <constant>DNS_PTR</constant>, + <constant>DNS_SOA</constant>, <constant>DNS_TXT</constant>, + <constant>DNS_AAAA</constant>, <constant>DNS_SRV</constant>, + <constant>DNS_NAPTR</constant>, <constant>DNS_A6</constant>, + <constant>DNS_ALL</constant> or <constant>DNS_ANY</constant>. + The default is <emphasis>DNS_ANY</emphasis>. + </para> + <note> + <para> + Because of eccentricities in the performance of libresolv + between platforms, <constant>DNS_ANY</constant> will not + always return every record, the slower <constant>DNS_ALL</constant> + will collect all records more reliably. + </para> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>authns</parameter></term> + <listitem> + <para> + Passed by reference and, if given, will be populated with Resource + Records for the <emphasis>Authoritative Name Servers</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>addtl</parameter></term> + <listitem> + <para> + Passed by reference and, if given, will be populated with any + <emphasis>Additional Records</emphasis>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> This function returns an array of associative arrays. Each associative array contains <emphasis>at minimum</emphasis> the following keys: @@ -69,42 +140,6 @@ </tgroup> </table> </para> - <simpara> - <parameter>hostname</parameter> should be a valid DNS hostname such - as "www.example.com". Reverse lookups can be generated using in-addr.arpa - notation, but <function>gethostbyaddr</function> is more suitable for - the majority of reverse lookups. - </simpara> - <para> - By default, <function>dns_get_record</function> will search for any resource - records associated with <parameter>hostname</parameter>. To limit the - query, specify the optional <parameter>type</parameter> parameter. - <parameter>type</parameter> may be any one of the following: - <constant>DNS_A</constant>, <constant>DNS_CNAME</constant>, - <constant>DNS_HINFO</constant>, <constant>DNS_MX</constant>, - <constant>DNS_NS</constant>, <constant>DNS_PTR</constant>, - <constant>DNS_SOA</constant>, <constant>DNS_TXT</constant>, - <constant>DNS_AAAA</constant>, <constant>DNS_SRV</constant>, - <constant>DNS_NAPTR</constant>, <constant>DNS_A6</constant>, - <constant>DNS_ALL</constant> or <constant>DNS_ANY</constant>. - The default is <emphasis>DNS_ANY</emphasis>. - <note> - <para> - Because of eccentricities in the performance of libresolv - between platforms, <constant>DNS_ANY</constant> will not - always return every record, the slower <constant>DNS_ALL</constant> - will collect all records more reliably. - </para> - </note> - </para> - <simpara> - The optional third and fourth arguments to this function, - <parameter>authns</parameter> and <parameter>addtl</parameter> - are passed by reference and, if given, will be populated with - Resource Records for the <emphasis>Authoritative Name Servers</emphasis>, - and any <emphasis>Additional Records</emphasis> respectively. - See the example below. - </simpara> <para> <table> <title>Other keys in associative arrays dependant on 'type'</title> @@ -233,30 +268,23 @@ </tgroup> </table> </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - <note> - <para> - Per DNS standards, email addresses are given in user.host format (for - example: hostmaster.example.com as opposed to hostmaster@example.com), - be sure to check this value and modify if necessary before using it - with a functions such as <function>mail</function>. - </para> - </note> - </para> - <example> - <title>Using <function>dns_get_record</function></title> - <programlisting role="php"> + <example> + <title>Using <function>dns_get_record</function></title> + <programlisting role="php"> <![CDATA[ <?php $result = dns_get_record("php.net"); print_r($result); ?> ]]> - </programlisting> - <para> - Produces output similar to the following: - </para> - <screen> + </programlisting> + &example.outputs.similar; + <screen> <![CDATA[ Array ( @@ -281,19 +309,19 @@ ) ]]> - </screen> - </example> - <simpara> - Since it's very common to want the IP address of a mail server - once the MX record has been resolved, <function>dns_get_record</function> - also returns an array in <parameter>addtl</parameter> which - contains associate records. <parameter>authns</parameter> - is returned as well containing a list of authoritative name - servers. - </simpara> - <example> - <title>Using <function>dns_get_record</function> and DNS_ANY</title> - <programlisting role="php"> + </screen> + </example> + <simpara> + Since it's very common to want the IP address of a mail server + once the MX record has been resolved, <function>dns_get_record</function> + also returns an array in <parameter>addtl</parameter> which + contains associate records. <parameter>authns</parameter> + is returned as well containing a list of authoritative name + servers. + </simpara> + <example> + <title>Using <function>dns_get_record</function> and DNS_ANY</title> + <programlisting role="php"> <![CDATA[ <?php /* Request "ANY" record for php.net, @@ -310,11 +338,9 @@ print_r($addtl); ?> ]]> - </programlisting> - <para> - Produces output similar to the following: - </para> - <screen> + </programlisting> + &example.outputs.similar; + <screen> <![CDATA[ Result = Array ( @@ -426,14 +452,33 @@ ) ]]> - </screen> - </example> - <simpara> - See also - <function>dns_get_mx</function>, and - <function>dns_check_record</function> - </simpara> + </screen> + </example> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + This function is not implemented on Windows platforms, nor does it + (currently) work on *BSD systems. Try the + <ulink url="&url.php.pear;">PEAR</ulink> class + <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>. + </para> + </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>dns_get_mx</function></member> + <member><function>dns_check_record</function></member> + </simplelist> + </para> </refsect1> + </refentry>  - + <refentry id="function.fsockopen"> <refnamediv> <refname>fsockopen</refname> <refpurpose>Open Internet or Unix domain socket connection</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>resource</type><methodname>fsockopen</methodname> - <methodparam><type>string</type><parameter>target</parameter></methodparam> + <methodparam><type>string</type><parameter>hostname</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>port</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter role="reference">errno</parameter></methodparam> <methodparam choice="opt"><type>string</type><parameter role="reference">errstr</parameter></methodparam> @@ -18,55 +18,138 @@ </methodsynopsis> <para> Initiates a socket connection to the resource specified by - <parameter>target</parameter>. PHP 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>. + <parameter>hostname</parameter>. </para> - <note> - <simpara> - If you need to set a timeout for reading/writing data over the socket, - use <function>stream_set_timeout</function>, as the <parameter>timeout</parameter> - parameter to <function>fsockopen</function> only applies while - connecting the socket. - </simpara> - </note> <para> - As of PHP 4.3.0, if you have compiled in OpenSSL support, you may - prefix the <parameter>hostname</parameter> with either - '<literal>ssl://</literal>' or '<literal>tls://</literal>' to - use an SSL or TLS client connection over TCP/IP to connect - to the remote host. + PHP 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> <para> - <function>fsockopen</function> returns a file pointer which may - be used together with the other file functions (such as - <function>fgets</function>, <function>fgetss</function>, - <function>fwrite</function>, <function>fclose</function>, and - <function>feof</function>). + The socket will by default be opened in blocking mode. You can + switch it to non-blocking mode by using + <function>stream_set_blocking</function>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - If the call fails, it will return &false; and if the optional - <parameter>errno</parameter> and <parameter>errstr</parameter> - arguments are present they will be set to indicate the actual - system level error that occurred in the system-level - <literal>connect()</literal> call. If the value returned in - <parameter>errno</parameter> is <literal>0</literal> and the - function returned &false;, it is an indication that the error - occurred before the <literal>connect()</literal> call. This is - most likely due to a problem initializing the socket. Note that - the <parameter>errno</parameter> and - <parameter>errstr</parameter> arguments will always be passed by - reference. + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem> + <para> + If you have compiled in OpenSSL support, you may prefix the + <parameter>hostname</parameter> with either <literal>ssl://</literal> + or <literal>tls://</literal> to use an SSL or TLS client connection + over TCP/IP to connect to the remote host. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + The port number. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>errno</parameter></term> + <listitem> + <para> + If provided, holds the system level error number that occurred in the + system-level <literal>connect()</literal> call. + </para> + <para> + If the value returned in <parameter>errno</parameter> is + <literal>0</literal> and the function returned &false;, it is an + indication that the error occurred before the + <literal>connect()</literal> call. This is most likely due to a + problem initializing the socket. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>errstr</parameter></term> + <listitem> + <para> + The error message as a string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>timeout</parameter></term> + <listitem> + <para> + The connection timeout, in seconds. + </para> + <note> + <para> + If you need to set a timeout for reading/writing data over the + socket, use <function>stream_set_timeout</function>, as the + <parameter>timeout</parameter> parameter to + <function>fsockopen</function> only applies while connecting the + socket. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - Depending on the environment, the Unix domain or the optional - connect timeout may not be available. + <function>fsockopen</function> returns a file pointer which may be used + together with the other file functions (such as + <function>fgets</function>, <function>fgetss</function>, + <function>fwrite</function>, <function>fclose</function>, and + <function>feof</function>). If the call fails, it will return &false; </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + SSL and TLS over TCP/IP support was added. + </entry> + </row> + <row> + <entry>4.0.0</entry> + <entry> + UDP support was added. + </entry> + </row> + <row> + <entry>3.0.9</entry> + <entry> + The <parameter>timeout</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> - The socket will by default be opened in blocking mode. You can - switch it to non-blocking mode by using - <function>stream_set_blocking</function>. <example> <title><function>fsockopen</function> Example</title> <programlisting role="php"> @@ -90,11 +173,15 @@ ]]> </programlisting> </example> - The example below shows how to retrieve the day and time - from the UDP service "daytime" (port 13) in your own machine. + </para> + <para> <example> - <title>Using UDP connection</title> - <programlisting role="php"> + <title>Using UDP connection</title> + <para> + The example below shows how to retrieve the day and time from the UDP + service "daytime" (port 13) in your own machine. + </para> + <programlisting role="php"> <![CDATA[ <?php $fp = fsockopen("udp://127.0.0.1", 13, $errno, $errstr); @@ -107,32 +194,49 @@ } ?> ]]> - </programlisting> + </programlisting> </example> - <warning> - <simpara> - UDP sockets will sometimes appear to have opened without an error, - even if the remote host is unreachable. The error will only - become apparent when you read or write data to/from the socket. - The reason for this is because UDP is a "connectionless" protocol, - which means that the operating system does not try to establish - a link for the socket until it actually needs to send or receive data. - </simpara> - </warning> - &ipv6.brackets; - <note> - <para>The timeout parameter was introduced in PHP 3.0.9 and - UDP support was added in PHP 4. - </para> - </note> - See also <function>pfsockopen</function>, - <function>stream_set_blocking</function>, - <function>stream_set_timeout</function>, <function>fgets</function>, - <function>fgetss</function>, <function>fwrite</function>, - <function>fclose</function>, <function>feof</function>, and - the <link linkend="ref.curl">Curl extension</link>. </para> </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + Depending on the environment, the Unix domain or the optional + connect timeout may not be available. + </para> + </note> + <warning> + <para> + UDP sockets will sometimes appear to have opened without an error, + even if the remote host is unreachable. The error will only + become apparent when you read or write data to/from the socket. + The reason for this is because UDP is a "connectionless" protocol, + which means that the operating system does not try to establish + a link for the socket until it actually needs to send or receive data. + </para> + </warning> + &ipv6.brackets; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>pfsockopen</function></member> + <member><function>stream_set_blocking</function></member> + <member><function>stream_set_timeout</function></member> + <member><function>fgets</function></member> + <member><function>fgetss</function></member> + <member><function>fwrite</function></member> + <member><function>fclose</function></member> + <member><function>feof</function></member> + <member>The <link linkend="ref.curl">Curl extension</link></member> + </simplelist> + </para> + </refsect1> + </refentry>  + <refentry id="function.gethostbyaddr"> <refnamediv> <refname>gethostbyaddr</refname> @@ -9,15 +9,42 @@ </refnamediv> <refsect1 role="description"> &reftitle.description; - <methodsynopsis> - <type>string</type><methodname>gethostbyaddr</methodname> - <methodparam><type>string</type><parameter>ip_address</parameter></methodparam> - </methodsynopsis> + <methodsynopsis> + <type>string</type><methodname>gethostbyaddr</methodname> + <methodparam><type>string</type><parameter>ip_address</parameter></methodparam> + </methodsynopsis> <para> Returns the host name of the Internet host specified by - <parameter>ip_address</parameter> or a string containing the unmodified - <parameter>ip_address</parameter> on failure. + <parameter>ip_address</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>ip_address</parameter></term> + <listitem> + <para> + The host IP address. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the host name or the unmodified <parameter>ip_address</parameter> + on failure. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A simple <function>gethostbyaddr</function> example</title> @@ -43,6 +70,7 @@ </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.gethostbyname"> <refnamediv> <refname>gethostbyname</refname> @@ -7,17 +7,45 @@ Get the IP address corresponding to a given Internet host name </refpurpose> </refnamediv> + <refsect1 role="description"> &reftitle.description; - <methodsynopsis> - <type>string</type><methodname>gethostbyname</methodname> - <methodparam><type>string</type><parameter>hostname</parameter></methodparam> - </methodsynopsis> + <methodsynopsis> + <type>string</type><methodname>gethostbyname</methodname> + <methodparam><type>string</type><parameter>hostname</parameter></methodparam> + </methodsynopsis> <para> Returns the IP address of the Internet host specified by - <parameter>hostname</parameter> or a string containing the unmodified + <parameter>hostname</parameter>. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem> + <para> + The host name. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the IP address or a string containing the unmodified <parameter>hostname</parameter> on failure. </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>A simple <function>gethostbyname</function> example</title> @@ -43,6 +71,7 @@ </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.gethostbynamel"> <refnamediv> <refname>gethostbynamel</refname> @@ -10,28 +10,54 @@ </refnamediv> <refsect1 role="description"> &reftitle.description; - <methodsynopsis> - <type>array</type><methodname>gethostbynamel</methodname> - <methodparam><type>string</type><parameter>hostname</parameter></methodparam> - </methodsynopsis> + <methodsynopsis> + <type>array</type><methodname>gethostbynamel</methodname> + <methodparam><type>string</type><parameter>hostname</parameter></methodparam> + </methodsynopsis> <para> Returns a list of IP addresses to which the Internet host - specified by <parameter>hostname</parameter> resolves. Returns &false; if + specified by <parameter>hostname</parameter> resolves. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem> + <para> + The host name. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns an array of IP addresses or &false; if <parameter>hostname</parameter> could not be resolved. </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title><function>gethostbynamel</function> example</title> <programlisting role="php"> <![CDATA[ <?php - $hosts = gethostbynamel('www.example.com'); - print_r($hosts); +$hosts = gethostbynamel('www.example.com'); +print_r($hosts); ?> ]]> </programlisting> - <para> - The printout of the above program will be: - </para> + &example.outputs; <screen> <![CDATA[ Array @@ -41,6 +67,7 @@ ]]> </screen> </example> + </para> </refsect1> <refsect1 role="seealso"> @@ -55,6 +82,7 @@ </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.getmxrr"> <refnamediv> <refname>getmxrr</refname> <refpurpose>Get MX records corresponding to a given Internet host name</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>getmxrr</methodname> <methodparam><type>string</type><parameter>hostname</parameter></methodparam> <methodparam><type>array</type><parameter role="reference">mxhosts</parameter></methodparam> <methodparam choice="opt"><type>array</type><parameter role="reference">weight</parameter></methodparam> </methodsynopsis> - <simpara> - Searches DNS for MX records corresponding to - <parameter>hostname</parameter>. Returns &true; if any records are - found; returns &false; if no records were found or if an error - occurred. - </simpara> - <simpara> - A list of the MX records found is placed into the array - <parameter>mxhosts</parameter>. If the - <parameter>weight</parameter> array is given, it will be filled - with the weight information gathered. - </simpara> <para> - <note> - <simpara> - This function should not be used for the purposes of address - verification. Only the mailexchangers found in DNS are returned, - however, according to <ulink url="&url.rfc;2821">RFC 2821</ulink> - when no mail exchangers are listed, <parameter>hostname</parameter> - itself should be used as the only mail exchanger with a priority of - <literal>0</literal>. - </simpara> - </note> + Searches DNS for MX records corresponding to + <parameter>hostname</parameter>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - <note> - <simpara> - This function is not implemented on Windows platforms. Try the - <ulink url="&url.php.pear;">PEAR</ulink> class - <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>. - </simpara> - </note> + <variablelist> + <varlistentry> + <term><parameter>hostname</parameter></term> + <listitem> + <para> + The Internet host name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>mxhosts</parameter></term> + <listitem> + <para> + A list of the MX records found is placed into the array + <parameter>mxhosts</parameter>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>weight</parameter></term> + <listitem> + <para> + If the <parameter>weight</parameter> array is given, it will be filled + with the weight information gathered. + </para> + </listitem> + </varlistentry> + </variablelist> </para> - <simpara> - See also <function>checkdnsrr</function>, - <function>dns_get_record</function>, - <function>gethostbyname</function>, - <function>gethostbynamel</function>, - <function>gethostbyaddr</function>, and the - <literal>named(8)</literal> manual page. - </simpara> </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns &true; if any records are found; returns &false; if no records + were found or if an error occurred. + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + This function should not be used for the purposes of address + verification. Only the mailexchangers found in DNS are returned, + however, according to <ulink url="&url.rfc;2821">RFC 2821</ulink> + when no mail exchangers are listed, <parameter>hostname</parameter> + itself should be used as the only mail exchanger with a priority of + <literal>0</literal>. + </para> + </note> + <note> + <para> + This function is not implemented on Windows platforms. Try the + <ulink url="&url.php.pear;">PEAR</ulink> class + <ulink url="&url.pear.package;Net_DNS">Net_DNS</ulink>. + </para> + </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>checkdnsrr</function></member> + <member><function>dns_get_record</function></member> + <member><function>gethostbyname</function></member> + <member><function>gethostbynamel</function></member> + <member><function>gethostbyaddr</function></member> + <member>the <literal>named(8)</literal> manual page</member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.getprotobyname"> <refnamediv> <refname>getprotobyname</refname> <refpurpose>Get protocol number associated with protocol name</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>getprotobyname</methodname> <methodparam><type>string</type><parameter>name</parameter></methodparam> @@ -17,6 +17,33 @@ associated with the protocol <parameter>name</parameter> as per <filename>/etc/protocols</filename>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + The protocol name. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the protocol number or -1 if the protocol is not found. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>getprotobyname</function> example</title> @@ -26,7 +53,6 @@ $protocol = 'tcp'; $get_prot = getprotobyname($protocol); if ($get_prot == -1) { - // if nothing found, returns -1 echo 'Invalid Protocol'; } else { echo 'Protocol #' . $get_prot; @@ -36,10 +62,17 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also: <function>getprotobynumber</function>. + <simplelist> + <member><function>getprotobynumber</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.getprotobynumber"> <refnamediv> <refname>getprotobynumber</refname> <refpurpose>Get protocol name associated with protocol number</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>getprotobynumber</methodname> <methodparam><type>int</type><parameter>number</parameter></methodparam> @@ -17,10 +17,40 @@ associated with protocol <parameter>number</parameter> as per <filename>/etc/protocols</filename>. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>number</parameter></term> + <listitem> + <para> + The protocol number. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also: <function>getprotobyname</function>. + Returns the protocol name as a string. </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>getprotobyname</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.getservbyname"> <refnamediv> <refname>getservbyname</refname> <refpurpose>Get port number associated with an Internet service and protocol</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>getservbyname</methodname> <methodparam><type>string</type><parameter>service</parameter></methodparam> @@ -18,11 +18,44 @@ which corresponds to <parameter>service</parameter> for the specified <parameter>protocol</parameter> as per <filename>/etc/services</filename>. - <parameter>protocol</parameter> is either <literal>"tcp"</literal> - or <literal>"udp"</literal> (in lowercase). Returns &false; if - <parameter>service</parameter> or <parameter>protocol</parameter> is not - found. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>service</parameter></term> + <listitem> + <para> + The Internet service name, as a string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>protocol</parameter></term> + <listitem> + <para> + <parameter>protocol</parameter> is either <literal>"tcp"</literal> + or <literal>"udp"</literal> (in lowercase). + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the port number, or &false; if <parameter>service</parameter> or + <parameter>protocol</parameter> is not found. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title><function>getservbyname</function> example</title> @@ -41,13 +74,21 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - For complete list of port numbers see: &url.network.port-numbers;. - </para> - <para> - See also: <function>getservbyport</function>. + <simplelist> + <member><function>getservbyport</function></member> + <member> + <ulink url='&url.network.port-numbers;'>&url.network.port-numbers;</ulink> + for a complete list of port numbers. + </member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.getservbyport"> <refnamediv> <refname>getservbyport</refname> <refpurpose>Get Internet service which corresponds to port and protocol</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>getservbyport</methodname> <methodparam><type>int</type><parameter>port</parameter></methodparam> @@ -17,13 +17,50 @@ <function>getservbyport</function> returns the Internet service associated with <parameter>port</parameter> for the specified <parameter>protocol</parameter> as per <filename>/etc/services</filename>. - <parameter>protocol</parameter> is either <literal>"tcp"</literal> - or <literal>"udp"</literal> (in lowercase). </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>port</parameter></term> + <listitem> + <para> + The port number. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>protocol</parameter></term> + <listitem> + <para> + <parameter>protocol</parameter> is either <literal>"tcp"</literal> + or <literal>"udp"</literal> (in lowercase). + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also: <function>getservbyname</function>. + Returns the Internet service name as a string. </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>getservbyname</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.header"> <refnamediv> <refname>header</refname> <refpurpose>Send a raw HTTP header</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>void</type><methodname>header</methodname> <methodparam><type>string</type><parameter>string</parameter></methodparam> @@ -15,80 +15,72 @@ <methodparam choice="opt"><type>int</type><parameter>http_response_code</parameter></methodparam> </methodsynopsis> <para> - <function>header</function> is used to send a raw - <acronym>HTTP</acronym> header. See the <ulink - url="&url.rfc;2616">HTTP/1.1 specification</ulink> for more - information on <acronym>HTTP</acronym> headers. - </para> - <note> - <para> - Since PHP 4.4.2 and PHP 5.1.2 this function prevents more than one - header to be sent at once as a protection against header injection - attacks. - </para> - </note> - <para> - The optional <parameter>replace</parameter> parameter indicates - whether the header should replace a previous similar header, or - add a second header of the same type. By default it will replace, - but if you pass in &false; as the second argument you can force - multiple headers of the same type. For example: + <function>header</function> is used to send a raw <acronym>HTTP</acronym> + header. See the <ulink url="&url.rfc;2616">HTTP/1.1 specification</ulink> + for more information on <acronym>HTTP</acronym> headers. </para> <para> + Remember that <function>header</function> must be called before any + actual output is sent, either by normal HTML tags, blank lines in a + file, or from PHP. It is a very common error to read code with + <function>include</function>, or <function>require</function>, + functions, or another file access function, and have spaces or empty + lines that are output before <function>header</function> is called. + The same problem exists when using a single PHP/HTML file. <informalexample> <programlisting role="php"> <![CDATA[ +<html> <?php -header('WWW-Authenticate: Negotiate'); -header('WWW-Authenticate: NTLM', false); +/* This will give an error. Note the output + * above, which is before the header() call */ +header('Location: http://www.example.com/'); ?> ]]> </programlisting> </informalexample> </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - The second optional <parameter>http_response_code</parameter> force the - HTTP response code to the specified value. (This parameter is available - in PHP 4.3.0 and higher.) - </para> - <para> - There are two special-case header calls. The first is a header - that starts with the string "<literal>HTTP/</literal>" (case is not - significant), which will be used to figure out the HTTP status - code to send. For example, if you have configured Apache to - use a PHP script to handle requests for missing files (using - the <literal>ErrorDocument</literal> directive), you may want to - make sure that your script generates the proper status code. - </para> - <para> - <informalexample> - <programlisting role="php"> + <variablelist> + <varlistentry> + <term><parameter>string</parameter></term> + <listitem> + <para> + The header string. + </para> + <para> + There are two special-case header calls. The first is a header + that starts with the string "<literal>HTTP/</literal>" (case is not + significant), which will be used to figure out the HTTP status + code to send. For example, if you have configured Apache to + use a PHP script to handle requests for missing files (using + the <literal>ErrorDocument</literal> directive), you may want to + make sure that your script generates the proper status code. + </para> + <para> + <informalexample> + <programlisting role="php"> <![CDATA[ <?php header("HTTP/1.0 404 Not Found"); ?> ]]> - </programlisting> - </informalexample> - </para> - <note> - <para> - The HTTP status header line will always be the first sent - to the client, regardless of the actual <function>header</function> - call being the first or not. The status may be overridden - by calling <function>header</function> with a new status line - at any time unless the HTTP headers have already been sent. - </para> - </note> - <para> - The second special case is the "Location:" header. Not only does - it send this header back to the browser, but it also returns a - <literal>REDIRECT</literal> (302) status code to the browser unless - some <literal>3xx</literal> status code has already been set. - </para> - <para> - <informalexample> - <programlisting role="php"> + </programlisting> + </informalexample> + </para> + <para> + The second special case is the "Location:" header. Not only does + it send this header back to the browser, but it also returns a + <literal>REDIRECT</literal> (302) status code to the browser unless + some <literal>3xx</literal> status code has already been set. + </para> + <para> + <informalexample> + <programlisting role="php"> <![CDATA[ <?php header("Location: http://www.example.com/"); /* Redirect browser */ @@ -97,100 +89,152 @@ exit; ?> ]]> - </programlisting> - </informalexample> - </para> - <note> - <para> - HTTP/1.1 requires an absolute <acronym>URI</acronym> as argument to - <ulink url="&spec.http1.1;-sec14.html#sec14.30">Location:</ulink> - including the scheme, hostname and absolute path, but - some clients accept relative URIs. You can usually use - <literal>$_SERVER['HTTP_HOST']</literal>, <literal>$_SERVER['PHP_SELF']</literal> - and <function>dirname</function> to make an absolute URI from a - relative one yourself: - <informalexample> - <programlisting role="php"> + </programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>replace</parameter></term> + <listitem> + <para> + The optional <parameter>replace</parameter> parameter indicates + whether the header should replace a previous similar header, or + add a second header of the same type. By default it will replace, + but if you pass in &false; as the second argument you can force + multiple headers of the same type. For example: + </para> + <para> + <informalexample> + <programlisting role="php"> <![CDATA[ <?php -/* Redirect to a different page in the current directory that was requested */ -$host = $_SERVER['HTTP_HOST']; -$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\'); -$extra = 'mypage.php'; -header("Location: http://$host$uri/$extra"); -exit; +header('WWW-Authenticate: Negotiate'); +header('WWW-Authenticate: NTLM', false); ?> ]]> - </programlisting> - </informalexample> - </para> - </note> - <note> - <para> - Session ID is not passed with Location header even if <link - linkend="ini.session.use-trans-sid">session.use_trans_sid</link> is - enabled. It must by passed manually using <constant>SID</constant> - constant. - </para> - </note> + </programlisting> + </informalexample> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>http_response_code</parameter></term> + <listitem> + <para> + Forces the HTTP response code to the specified value. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - PHP scripts often generate dynamic content that must not be cached - by the client browser or any proxy caches between the server and the - client browser. Many proxies and clients can be forced to disable - caching with: + &return.void; </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; <para> - <informalexample> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.4.2 and 5.1.2</entry> + <entry> + This function now prevents more than one header to be sent at once as + a protection against header injection attacks. + </entry> + </row> + <row> + <entry>4.3.0</entry> + <entry> + The <parameter>http_response_code</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title>Download dialog</title> + <para> + If you want the user to be prompted to save the data you are + sending, such as a generated PDF file, you can use the <ulink + url="&url.rfc;2183">Content-Disposition</ulink> header to + supply a recommended filename and force the browser to display the + save dialog. + </para> <programlisting role="php"> <![CDATA[ <?php -header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1 -header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // Date in the past +// We'll be outputting a PDF +header('Content-type: application/pdf'); + +// It will be called downloaded.pdf +header('Content-Disposition: attachment; filename="downloaded.pdf"'); + +// The PDF source is in original.pdf +readfile('original.pdf'); ?> ]]> </programlisting> - </informalexample> - </para> - <note> - <para> - You may find that your pages aren't cached even if you don't - output all of the headers above. There are a number of options - that users may be able to set for their browser that change its - default caching behavior. By sending the headers above, you should - override any settings that may otherwise cause the output of your - script to be cached. - </para> - <para> - Additionally, <function>session_cache_limiter</function> and - the <literal>session.cache_limiter</literal> configuration - setting can be used to automatically generate the correct - caching-related headers when sessions are being used. - </para> - </note> - <para> - Remember that <function>header</function> must be - called before any actual output is sent, either by normal HTML - tags, blank lines in a file, or from PHP. It is a very common - error to read code with <function>include</function>, or - <function>require</function>, functions, or another file access - function, and have spaces or empty lines that are output before - <function>header</function> is called. The same problem exists - when using a single PHP/HTML file. + </example> </para> <para> - <informalexample> + <example> + <title>Caching directives</title> + <para> + PHP scripts often generate dynamic content that must not be cached + by the client browser or any proxy caches between the server and the + client browser. Many proxies and clients can be forced to disable + caching with: + </para> <programlisting role="php"> <![CDATA[ -<html> <?php -/* This will give an error. Note the output - * above, which is before the header() call */ -header('Location: http://www.example.com/'); +header("Cache-Control: no-cache, must-revalidate"); // HTTP/1.1 +header("Expires: Mon, 26 Jul 1997 05:00:00 GMT"); // Date in the past ?> ]]> </programlisting> - </informalexample> + <note> + <para> + You may find that your pages aren't cached even if you don't + output all of the headers above. There are a number of options + that users may be able to set for their browser that change its + default caching behavior. By sending the headers above, you should + override any settings that may otherwise cause the output of your + script to be cached. + </para> + <para> + Additionally, <function>session_cache_limiter</function> and + the <literal>session.cache_limiter</literal> configuration + setting can be used to automatically generate the correct + caching-related headers when sessions are being used. + </para> + </note> + </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> As of PHP 4, you can use output buffering to get around this problem, @@ -202,31 +246,15 @@ server configuration files. </para> </note> - <para> - If you want the user to be prompted to save the data you are - sending, such as a generated PDF file, you can use the <ulink - url="&url.rfc;2183">Content-Disposition</ulink> header to - supply a recommended filename and force the browser to display the - save dialog. - </para> - <para> - <informalexample> - <programlisting role="php"> -<![CDATA[ -<?php -// We'll be outputting a PDF -header('Content-type: application/pdf'); - -// It will be called downloaded.pdf -header('Content-Disposition: attachment; filename="downloaded.pdf"'); - -// The PDF source is in original.pdf -readfile('original.pdf'); -?> -]]> - </programlisting> - </informalexample> - </para> + <note> + <para> + The HTTP status header line will always be the first sent + to the client, regardless of the actual <function>header</function> + call being the first or not. The status may be overridden + by calling <function>header</function> with a new status line + at any time unless the HTTP headers have already been sent. + </para> + </note> <note> <para> There is a bug in Microsoft Internet Explorer 4.01 that prevents @@ -243,12 +271,55 @@ this header (used for HTTP Authentication). </simpara> </note> + <note> + <para> + HTTP/1.1 requires an absolute <acronym>URI</acronym> as argument to + <ulink url="&spec.http1.1;-sec14.html#sec14.30">Location:</ulink> + including the scheme, hostname and absolute path, but + some clients accept relative URIs. You can usually use + <literal>$_SERVER['HTTP_HOST']</literal>, <literal>$_SERVER['PHP_SELF']</literal> + and <function>dirname</function> to make an absolute URI from a + relative one yourself: + <informalexample> + <programlisting role="php"> +<![CDATA[ +<?php +/* Redirect to a different page in the current directory that was requested */ +$host = $_SERVER['HTTP_HOST']; +$uri = rtrim(dirname($_SERVER['PHP_SELF']), '/\\'); +$extra = 'mypage.php'; +header("Location: http://$host$uri/$extra"); +exit; +?> +]]> + </programlisting> + </informalexample> + </para> + </note> + <note> + <para> + Session ID is not passed with Location header even if <link + linkend="ini.session.use-trans-sid">session.use_trans_sid</link> is + enabled. It must by passed manually using <constant>SID</constant> + constant. + </para> + </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>headers_sent</function>, - <function>setcookie</function>, and the section on - <link linkend="features.http-auth">HTTP authentication</link>. + <simplelist> + <member><function>headers_sent</function></member> + <member><function>setcookie</function></member> + <member> + The section on <link linkend="features.http-auth">HTTP + authentication</link> + </member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.headers-list"> <refnamediv> <refname>headers_list</refname> <refpurpose>Returns a list of response headers sent (or ready to send)</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>array</type><methodname>headers_list</methodname> <void/> </methodsynopsis> - <simpara> - <function>headers_list</function> will return a numerically indexed array - of headers to be sent to the browser / client. To determine whether or not - these headers have been sent yet, use <function>headers_sent</function>. - </simpara> + <para> + <function>headers_list</function> will return a list of headers to be sent + to the browser / client. To determine whether or not these headers have + been sent yet, use <function>headers_sent</function>. + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a numerically indexed array of headers. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Examples using <function>headers_list</function></title> @@ -39,9 +51,7 @@ ?> ]]> </programlisting> - <para> - this will output : - </para> + &example.outputs; <screen> <![CDATA[ array(4) { @@ -59,13 +69,19 @@ </screen> </example> </para> - <simpara> - See Also: - <function>headers_sent</function>, - <function>header</function>, and - <function>setcookie</function>. - </simpara> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>headers_sent</function></member> + <member><function>header</function></member> + <member><function>setcookie</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.headers-sent"> <refnamediv> <refname>headers_sent</refname> <refpurpose>Checks if or where headers have been sent</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>headers_sent</methodname> <methodparam choice="opt"><type>string</type><parameter role="reference">file</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter role="reference">line</parameter></methodparam> </methodsynopsis> - <simpara> - <function>headers_sent</function> will return &false; if no HTTP headers - have already been sent or &true; otherwise. If the optional - <parameter>file</parameter> and <parameter>line</parameter> parameters - are set, <function>headers_sent</function> will put the PHP source - file name and line number where output started in the <parameter>file</parameter> - and <parameter>line</parameter> variables. - </simpara> - <simpara> + <para> + Checks if or where headers have been sent. + </para> + <para> You can't add any more header lines using the <function>header</function> function once the header block has already been sent. Using this function you can at least prevent getting HTTP header related error messages. Another option is to use <link linkend="ref.outcontrol">Output Buffering</link>. - </simpara> - <note> - <simpara> - The optional <parameter>file</parameter> and <parameter>line</parameter> - parameters were added in PHP 4.3.0. - </simpara> - </note> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>file</parameter></term> + <listitem> + <para> + If the optional <parameter>file</parameter> and + <parameter>line</parameter> parameters are set, + <function>headers_sent</function> will put the PHP source file name + and line number where output started in the <parameter>file</parameter> + and <parameter>line</parameter> variables. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>line</parameter></term> + <listitem> + <para> + The line number where the output started. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + <function>headers_sent</function> will return &false; if no HTTP headers + have already been sent or &true; otherwise. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.3.0</entry> + <entry> + The optional <parameter>file</parameter> and <parameter>line</parameter> + parameters were added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> <example> <title>Examples using <function>headers_sent</function></title> @@ -67,12 +121,22 @@ </programlisting> </example> </para> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>ob_start</function>, <function>trigger_error</function>, - and <function>header</function> for a more detailed discussion of the - matters involved. + <simplelist> + <member><function>ob_start</function></member> + <member><function>trigger_error</function></member> + <member> + <function>header</function> for a more detailed discussion of the + matters involved. + </member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.inet-ntop"> <refnamediv> <refname>inet_ntop</refname> <refpurpose>Converts a packed internet address to a human readable representation</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>inet_ntop</methodname> <methodparam><type>string</type><parameter>in_addr</parameter></methodparam> @@ -14,11 +15,39 @@ <simpara> This function converts a 32bit IPv4, or 128bit IPv6 address (if PHP was built with IPv6 support enabled) into an address family appropriate - string representation. Returns &false; on failure. + string representation. </simpara> - <example> - <title><function>inet_ntop</function> Example</title> - <programlisting role="php"> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>in_addr</parameter></term> + <listitem> + <para> + A 32bit IPv4, or 128bit IPv6 address. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns a string representation of the address or &false; on failure. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>inet_ntop</function> Example</title> + <programlisting role="php"> <![CDATA[ <?php $packed = chr(127) . chr(0) . chr(0) . chr(1); @@ -34,15 +63,27 @@ echo $expanded; ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; &note.no-windows; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>long2ip</function>, - <function>inet_pton</function>, and - <function>ip2long</function>. + <simplelist> + <member><function>long2ip</function></member> + <member><function>ip2long</function></member> + <member><function>inet_pton</function></member> + </simplelist> </para> </refsect1> + </refentry>  + <refentry id="function.inet-pton"> <refnamediv> <refname>inet_pton</refname> <refpurpose>Converts a human readable IP address to its packed in_addr representation</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>inet_pton</methodname> <methodparam><type>string</type><parameter>address</parameter></methodparam> </methodsynopsis> - <simpara> + <para> This function converts a human readable IPv4 or IPv6 address (if PHP was built with IPv6 support enabled) into an address family appropriate 32bit or 128bit binary structure. - </simpara> - <example> - <title><function>inet_pton</function> Example</title> - <programlisting role="php"> -<![CDATA[ -<?php -$in_addr = inet_pton('127.0.0.1'); - -$in6_addr = inet_pton('::1'); - -?> -]]> - </programlisting> - </example> + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>address</parameter></term> + <listitem> + <para> + A human readable IPv4 or IPv6 address. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the <literal>in_addr</literal> representation of the given + <parameter>address</parameter> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>inet_pton</function> Example</title> + <programlisting role="php"> + <![CDATA[ + <?php + $in_addr = inet_pton('127.0.0.1'); + + $in6_addr = inet_pton('::1'); + + ?> + ]]> + </programlisting> + </example> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; &note.no-windows; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>ip2long</function>, - <function>inet_ntop</function>, and - <function>long2ip</function>. + <simplelist> + <member><function>ip2long</function></member> + <member><function>long2ip</function></member> + <member><function>inet_ntop</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.ip2long"> <refnamediv> <refname>ip2long</refname> <refpurpose>Converts a string containing an (IPv4) Internet Protocol dotted address into a proper address</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>int</type><methodname>ip2long</methodname> <methodparam><type>string</type><parameter>ip_address</parameter></methodparam> @@ -15,19 +15,70 @@ <para> The function <function>ip2long</function> generates an IPv4 Internet network address from its Internet standard format (dotted string) - representation. If <parameter>ip_address</parameter> is invalid then - <literal>-1</literal> is returned. Note that <literal>-1</literal> - does not evaluate as &false; in PHP. + representation. </para> - <note> - <para> - As of PHP 5.0.0 <function>ip2long</function> returns &false; when - <parameter>ip_address</parameter> is invalid. - </para> - </note> - <example> - <title><function>ip2long</function> Example</title> - <programlisting role="php"> + <para> + <function>ip2long</function> will also work with non-complete IP + addresses. Read <ulink url="&url.ip2long.tech;">&url.ip2long.tech;</ulink> + for more info. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>ip_address</parameter></term> + <listitem> + <para> + A standard format address. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns the IPv4 address or &false; if <parameter>ip_address</parameter> + is invalid. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.0.0</entry> + <entry> + Prior to this version, <function>ip2long</function> returned -1 on + failure. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>ip2long</function> Example</title> + <programlisting role="php"> <![CDATA[ <?php $ip = gethostbyname('www.example.com'); @@ -36,25 +87,17 @@ echo $out; ?> ]]> - </programlisting> - </example> + </programlisting> + </example> + </para> <para> - <note> + <example> + <title>Displaying an IP address</title> <para> - Because PHP's integer type is signed, and many IP addresses will - result in negative integers, you need to use the "%u" formatter of - <function>sprintf</function> or <function>printf</function> to get - the string representation of the unsigned IP address. + This second example shows how to print a converted address with the + <function>printf</function> function in both PHP 4 and PHP 5: </para> - </note> - </para> - <para> - This second example shows how to print a converted address with the - <function>printf</function> function in both PHP 4 and PHP 5: - </para> - <example> - <title>Displaying an IP address</title> - <programlisting role="php"> + <programlisting role="php"> <![CDATA[ <?php $ip = gethostbyname('www.example.com'); @@ -69,15 +112,17 @@ } ?> ]]> - </programlisting> - </example> - <para> - <function>ip2long</function> should not be used as the sole form - of IP validation. Combine it with <function>long2ip</function>: + </programlisting> + </example> </para> - <example> - <title>IP validation</title> - <programlisting role="php"> + <para> + <example> + <title>IP validation</title> + <para> + <function>ip2long</function> should not be used as the sole form + of IP validation. Combine it with <function>long2ip</function>: + </para> + <programlisting role="php"> <![CDATA[ <?php // make sure IPs are valid. also converts a non-complete IP into @@ -87,13 +132,21 @@ $ip = long2ip(ip2long("10.0.256")); // "10.0.1.0" ?> ]]> - </programlisting> - </example> - <para> - <function>ip2long</function> will also work with non-complete IP - addresses. Read <ulink url="&url.ip2long.tech;">&url.ip2long.tech;</ulink> - for more info. + </programlisting> + </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + <note> + <para> + Because PHP's integer type is signed, and many IP addresses will + result in negative integers, you need to use the "%u" formatter of + <function>sprintf</function> or <function>printf</function> to get + the string representation of the unsigned IP address. + </para> + </note> <note> <para> <function>ip2long</function> will return &false; for the IP @@ -101,11 +154,18 @@ PHP 5.0.3 where it returns <literal>-1</literal> (same as PHP 4). </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>long2ip</function> and - <function>sprintf</function>. + <simplelist> + <member><function>long2ip</function></member> + <member><function>sprintf</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.long2ip"> <refnamediv> <refname>long2ip</refname> <refpurpose>Converts an (IPv4) Internet network address into a string in Internet standard dotted format</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>string</type><methodname>long2ip</methodname> <methodparam><type>int</type><parameter>proper_address</parameter></methodparam> @@ -17,10 +17,40 @@ in dotted format (i.e.: aaa.bbb.ccc.ddd) from the proper address representation. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>proper_address</parameter></term> + <listitem> + <para> + A proper address representation. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - See also: <function>ip2long</function> + Returns the Internet IP address as a string. </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>ip2long</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.openlog"> <refnamediv> <refname>openlog</refname> <refpurpose>Open connection to system logger</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>openlog</methodname> <methodparam><type>string</type><parameter>ident</parameter></methodparam> @@ -16,145 +16,186 @@ </methodsynopsis> <para> <function>openlog</function> opens a connection to the system - logger for a program. The string <parameter>ident</parameter> is - added to each message. Values for <parameter>option</parameter> - and <parameter>facility</parameter> are given below. - The <parameter>option</parameter> argument is used to indicate - what logging options will be used when generating a log message. - The <parameter>facility</parameter> argument is used to specify what - type of program is logging the message. This allows you to specify - (in your machine's syslog configuration) how messages coming from - different facilities will be handled. + logger for a program. + </para> + <para> The use of <function>openlog</function> is optional. It will automatically be called by <function>syslog</function> if necessary, in which case <parameter>ident</parameter> will default to &false;. </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - <table> - <title><function>openlog</function> Options</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Constant</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>LOG_CONS</entry> - <entry> - if there is an error while sending data to the system logger, - write directly to the system console - </entry> - </row> - <row> - <entry>LOG_NDELAY</entry> - <entry> - open the connection to the logger immediately - </entry> - </row> - <row> - <entry>LOG_ODELAY</entry> - <entry> - (default) delay opening the connection until the first - message is logged - </entry> - </row> - <row> - <entry>LOG_PERROR</entry> - <entry>print log message also to standard error</entry> - </row> - <row> - <entry>LOG_PID</entry> - <entry>include PID with each message</entry> - </row> - </tbody> - </tgroup> - </table> - You can use one or more of this options. When using multiple options - you need to <literal>OR</literal> them, i.e. to open the connection - immediately, write to the console and include the PID in each message, - you will use: <literal>LOG_CONS | LOG_NDELAY | LOG_PID</literal> + <variablelist> + <varlistentry> + <term><parameter>ident</parameter></term> + <listitem> + <para> + The string <parameter>ident</parameter> is added to each message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>option</parameter></term> + <listitem> + <para> + The <parameter>option</parameter> argument is used to indicate + what logging options will be used when generating a log message. + <table> + <title><function>openlog</function> Options</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Constant</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>LOG_CONS</constant></entry> + <entry> + if there is an error while sending data to the system <constant>LOGger, + write directly to the system console + </entry> + </row> + <row> + <entry><constant>LOG_NDELAY</constant></entry> + <entry> + open the connection to the <constant>LOGger immediately + </entry> + </row> + <row> + <entry><constant>LOG_ODELAY</constant></entry> + <entry> + (default) delay opening the connection until the first + message is <constant>LOGged + </entry> + </row> + <row> + <entry><constant>LOG_PERROR</constant></entry> + <entry>print <constant>LOG message also to standard error</entry> + </row> + <row> + <entry><constant>LOG_PID</constant></entry> + <entry>include PID with each message</entry> + </row> + </tbody> + </tgroup> + </table> + You can use one or more of this options. When using multiple options + you need to <literal>OR</literal> them, i.e. to open the connection + immediately, write to the console and include the PID in each message, + you will use: <literal>LOG_CONS | LOG_NDELAY | LOG_PID</literal> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>facility</parameter></term> + <listitem> + <para> + The <parameter>facility</parameter> argument is used to specify what + type of program is logging the message. This allows you to specify + (in your machine's syslog configuration) how messages coming from + different facilities will be handled. + <table> + <title><function>openlog</function> Facilities</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Constant</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>LOG_AUTH</constant></entry> + <entry> + security/authorization messages (use + <constant>LOG_AUTHPRIV</constant> instead + in systems where that constant is defined) + </entry> + </row> + <row> + <entry><constant>LOG_AUTHPRIV</constant></entry> + <entry>security/authorization messages (private)</entry> + </row> + <row> + <entry><constant>LOG_CRON</constant></entry> + <entry>clock daemon (cron and at)</entry> + </row> + <row> + <entry><constant>LOG_DAEMON</constant></entry> + <entry>other system daemons</entry> + </row> + <row> + <entry><constant>LOG_KERN</constant></entry> + <entry>kernel messages</entry> + </row> + <row> + <entry><constant>LOG_LOCAL0</constant> ... <constant>LOG_LOCAL7</constant></entry> + <entry>reserved for local use, these are not available in Windows</entry> + </row> + <row> + <entry><constant>LOG_LPR</constant></entry> + <entry>line printer subsystem</entry> + </row> + <row> + <entry><constant>LOG_MAIL</constant></entry> + <entry>mail subsystem</entry> + </row> + <row> + <entry><constant>LOG_NEWS</constant></entry> + <entry>USENET news subsystem</entry> + </row> + <row> + <entry><constant>LOG_SYSLOG</constant></entry> + <entry>messages generated internally by syslogd</entry> + </row> + <row> + <entry><constant>LOG_USER</constant></entry> + <entry>generic user-level messages</entry> + </row> + <row> + <entry><constant>LOG_UUCP</constant></entry> + <entry>UUCP subsystem</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <note> + <para> + <constant>LOG_USER</constant> is the only valid log type under Windows + operating systems + </para> + </note> + </listitem> + </varlistentry> + </variablelist> </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; <para> - <table> - <title><function>openlog</function> Facilities</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Constant</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>LOG_AUTH</entry> - <entry> - security/authorization messages (use LOG_AUTHPRIV instead - in systems where that constant is defined) - </entry> - </row> - <row> - <entry>LOG_AUTHPRIV</entry> - <entry>security/authorization messages (private)</entry> - </row> - <row> - <entry>LOG_CRON</entry> - <entry>clock daemon (cron and at)</entry> - </row> - <row> - <entry>LOG_DAEMON</entry> - <entry>other system daemons</entry> - </row> - <row> - <entry>LOG_KERN</entry> - <entry>kernel messages</entry> - </row> - <row> - <entry>LOG_LOCAL0 ... LOG_LOCAL7</entry> - <entry>reserved for local use, these are not available in Windows</entry> - </row> - <row> - <entry>LOG_LPR</entry> - <entry>line printer subsystem</entry> - </row> - <row> - <entry>LOG_MAIL</entry> - <entry>mail subsystem</entry> - </row> - <row> - <entry>LOG_NEWS</entry> - <entry>USENET news subsystem</entry> - </row> - <row> - <entry>LOG_SYSLOG</entry> - <entry>messages generated internally by syslogd</entry> - </row> - <row> - <entry>LOG_USER</entry> - <entry>generic user-level messages</entry> - </row> - <row> - <entry>LOG_UUCP</entry> - <entry>UUCP subsystem</entry> - </row> - </tbody> - </tgroup> - </table> + &return.success; </para> - <note> - <para> - <literal>LOG_USER</literal> is the only valid log type under Windows - operating systems - </para> - </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>define_syslog_variables</function>, - <function>syslog</function> and - <function>closelog</function>. + <simplelist> + <member><function>define_syslog_variables</function></member> + <member><function>syslog</function></member> + <member><function>closelog</function></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.pfsockopen"> <refnamediv> <refname>pfsockopen</refname> <refpurpose>Open persistent Internet or Unix domain socket connection</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>resource</type><methodname>pfsockopen</methodname> <methodparam><type>string</type><parameter>hostname</parameter></methodparam> @@ -17,12 +17,21 @@ <methodparam choice="opt"><type>float</type><parameter>timeout</parameter></methodparam> </methodsynopsis> <para> - This function behaves exactly as <function>fsockopen</function> - with the difference that the connection is not closed after the - script finishes. It is the persistent version of - <function>fsockopen</function>. + This function behaves exactly as <function>fsockopen</function> with the + difference that the connection is not closed after the script finishes. + It is the persistent version of <function>fsockopen</function>. </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>fsockopen</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.setcookie"> <refnamediv> <refname>setcookie</refname> <refpurpose>Send a cookie</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>setcookie</methodname> <methodparam><type>string</type><parameter>name</parameter></methodparam> @@ -19,216 +19,159 @@ <methodparam choice="opt"><type>bool</type><parameter>httponly</parameter></methodparam> </methodsynopsis> <para> - <function>setcookie</function> defines a cookie to be sent along - with the rest of the HTTP headers. Like other headers, cookies - must be sent <emphasis>before</emphasis> any output from your - script (this is a protocol restriction). This requires that you - place calls to this function prior to any output, including - <literal><html></literal> and <literal><head></literal> tags - as well as any whitespace. If output exists prior to calling this - function, <function>setcookie</function> will fail and return &false;. - If <function>setcookie</function> successfully runs, it will return - &true;. This does not indicate whether the user accepted the cookie. - </para> - <note> - <para> - As of PHP 4, you can use output buffering to send output prior to the - call of this function, with the overhead of all of your output to the - browser being buffered in the server until you send it. You can do this - by calling <function>ob_start</function> and - <function>ob_end_flush</function> in your script, or setting the - <literal>output_buffering</literal> configuration directive on in your - &php.ini; or server configuration files. - </para> - </note> - <para> - All the arguments except the <parameter>name</parameter> argument - are optional. You may also replace an argument with an empty string - (<emphasis>""</emphasis>) in order to skip that - argument. Because the <parameter>expire</parameter> - argument is integer, it cannot - be skipped with an empty string, use a zero (<emphasis>0</emphasis>) - instead. The following table explains each parameter of the - <function>setcookie</function> function, be sure to read the - <ulink url="&spec.cookies;">Netscape cookie specification</ulink> for - specifics on how each <function>setcookie</function> parameter works - and <ulink url="&url.rfc;2965">RFC 2965</ulink> for additional - information on how HTTP cookies work. - </para> - <para> - <table> - <title><function>setcookie</function> parameters explained</title> - <tgroup cols="3"> - <thead> - <row> - <entry>Parameter</entry> - <entry>Description</entry> - <entry>Examples</entry> - </row> - </thead> - <tbody> - <row> - <entry><parameter>name</parameter></entry> - <entry> - The name of the cookie. - </entry> - <entry> - 'cookiename' is called as <varname>$_COOKIE['cookiename']</varname> - </entry> - </row> - <row> - <entry><parameter>value</parameter></entry> - <entry> - The value of the cookie. This value is stored on the clients - computer; do not store sensitive information. - </entry> - <entry> - Assuming the <parameter>name</parameter> is 'cookiename', this - value is retrieved through <varname>$_COOKIE['cookiename']</varname> - </entry> - </row> - <row> - <entry><parameter>expire</parameter></entry> - <entry> - The time the cookie expires. This is a Unix timestamp so is - in number of seconds since the epoch. In other words, you'll - most likely set this with the <function>time</function> function - plus the number of seconds before you want it to expire. Or - you might use <function>mktime</function>. - </entry> - <entry> - <literal>time()+60*60*24*30</literal> will set the cookie to - expire in 30 days. If set to 0, or omitted, the cookie will expire at - the end of the session (when the browser closes). - </entry> - </row> - <row> - <entry><parameter>path</parameter></entry> - <entry> - The path on the server in which the cookie will be available on. - </entry> - <entry> - If set to <literal>'/'</literal>, the cookie will be available - within the entire <parameter>domain</parameter>. If set to - <literal>'/foo/'</literal>, the cookie will only be available - within the <literal>/foo/</literal> directory and all - sub-directories such as <literal>/foo/bar/</literal> of - <parameter>domain</parameter>. The default value is the - current directory that the cookie is being set in. - </entry> - </row> - <row> - <entry><parameter>domain</parameter></entry> - <entry> - The domain that the cookie is available. - </entry> - <entry> - To make the cookie available on all subdomains of example.com - then you'd set it to <literal>'.example.com'</literal>. The - <literal>.</literal> is not required but makes it compatible - with more browsers. Setting it to <literal>www.example.com</literal> - will make the cookie only available in the <literal>www</literal> - subdomain. Refer to tail matching in the - <ulink url="&spec.cookies;">spec</ulink> for details. - </entry> - </row> - <row> - <entry><parameter>secure</parameter></entry> - <entry> - Indicates that the cookie should only be transmitted over a - secure HTTPS connection from the client. When set to &true;, the - cookie will only be set if a secure connection exists. The default - is &false;. On the server-side, it's on the programmer to send this - kind of cookie only on secure connection (e.g. with respect to - <literal>$_SERVER["HTTPS"]</literal>). - </entry> - <entry> - &true; or &false; - </entry> - </row> - <row> - <entry><parameter>httponly</parameter></entry> - <entry> - When &true; the cookie will be made accessible only through the HTTP - protocol. This means that the cookie won't be accessible by - scripting languages, such as JavaScript. This setting can effectly - help to reduce identity theft through XSS attacks (although it is - not supported by all browsers). Added in PHP 5.2.0. - </entry> - <entry> - &true; or &false; - </entry> - </row> - </tbody> - </tgroup> - </table> + <function>setcookie</function> defines a cookie to be sent along with the + rest of the HTTP headers. Like other headers, cookies must be sent + <emphasis>before</emphasis> any output from your script (this is a + protocol restriction). This requires that you place calls to this function + prior to any output, including <literal><html></literal> and + <literal><head></literal> tags as well as any whitespace. </para> <para> Once the cookies have been set, they can be accessed on the next page load with the <link linkend="reserved.variables.cookies">$_COOKIE</link> or <varname>$HTTP_COOKIE_VARS</varname> arrays. Note, <link linkend="language.variables.superglobals">superglobals</link> - such as <varname>$_COOKIE</varname> became available in PHP - <ulink url="&url.php.release4.1.0;">4.1.0</ulink>. - <varname>$HTTP_COOKIE_VARS</varname> has existed since PHP 3. Cookie + such as <varname>$_COOKIE</varname> became available in PHP 4.1.0. + <varname>$HTTP_COOKIE_VARS</varname> has existed since PHP 3. Cookie values also exist in <link linkend="reserved.variables.request"> $_REQUEST</link>. </para> - <note> - <para> - If the PHP directive <link linkend="ini.register-globals">register_globals</link> - is set to <literal>on</literal> then cookie values will also be made into - variables. In our examples below, <varname>$TestCookie</varname> will - exist. It's recommended to use <varname>$_COOKIE</varname>. - </para> - </note> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; <para> - Common Pitfalls: - <itemizedlist> - <listitem> - <simpara> - Cookies will not become visible until the next loading of a page that - the cookie should be visible for. To test if a cookie was successfully - set, check for the cookie on a next loading page before the cookie - expires. Expire time is set via the <parameter>expire</parameter> - parameter. A nice way to debug the existence of cookies is by - simply calling <literal>print_r($_COOKIE);</literal>. - </simpara> - </listitem> - <listitem> - <simpara> - Cookies must be deleted with the same parameters as they were set with. - If the value argument is an empty string, or &false;, and all other arguments - match a previous call to setcookie, then the cookie with the specified - name will be deleted from the remote client. - </simpara> - </listitem> - <listitem> - <simpara> - Because setting a cookie with a value of &false; will try to delete the cookie, - you should not use boolean values. Instead, use <emphasis>0</emphasis> for &false; - and <emphasis>1</emphasis> for &true;. - </simpara> - </listitem> - <listitem> - <simpara> - Cookies names can be set as array names and will be available to your - PHP scripts as arrays but separate cookies are stored on the users - system. Consider <function>explode</function> to set one cookie with - multiple names and values. It is not recommended to use - <function>serialize</function> for this purpose, because it can result - in security holes. - </simpara> - </listitem> - </itemizedlist> + All the arguments except the <parameter>name</parameter> argument are + optional. You may also replace an argument with an empty string + (<emphasis>""</emphasis>) in order to skip that argument. + Because the <parameter>expire</parameter> argument is integer, it cannot + be skipped with an empty string, use a zero (<emphasis>0</emphasis>) + instead. </para> - <simpara> - In PHP 3, multiple calls to <function>setcookie</function> in the same - script will be performed in reverse order. If you are trying to - delete one cookie before inserting another you should put the - insert before the delete. As of PHP 4, multiple calls to - <function>setcookie</function> are performed in the order called. - </simpara> + <para> + See <ulink url="&spec.cookies;">Netscape cookie specification</ulink> for + specifics on how each <function>setcookie</function> parameter works + <variablelist> + <varlistentry> + <term><parameter>name</parameter></term> + <listitem> + <para> + The name of the cookie. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter></term> + <listitem> + <para> + The value of the cookie. This value is stored on the clients + computer; do not store sensitive information. + Assuming the <parameter>name</parameter> is 'cookiename', this + value is retrieved through <varname>$_COOKIE['cookiename']</varname> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>expire</parameter></term> + <listitem> + <para> + The time the cookie expires. This is a Unix timestamp so is + in number of seconds since the epoch. In other words, you'll + most likely set this with the <function>time</function> function + plus the number of seconds before you want it to expire. Or + you might use <function>mktime</function>. + <literal>time()+60*60*24*30</literal> will set the cookie to + expire in 30 days. If set to 0, or omitted, the cookie will expire at + the end of the session (when the browser closes). + </para> + <para> + <note> + <para> + You may notice the <parameter>expire</parameter> parameter takes on a + Unix timestamp, as opposed to the date format <literal>Wdy, DD-Mon-YYYY + HH:MM:SS GMT</literal>, this is because PHP does this conversion + internally. + </para> + <para> + <parameter>expire</parameter> is compared to the client's time which can + differ from server's time. + </para> + </note> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>path</parameter></term> + <listitem> + <para> + The path on the server in which the cookie will be available on. + If set to <literal>'/'</literal>, the cookie will be available + within the entire <parameter>domain</parameter>. If set to + <literal>'/foo/'</literal>, the cookie will only be available + within the <literal>/foo/</literal> directory and all + sub-directories such as <literal>/foo/bar/</literal> of + <parameter>domain</parameter>. The default value is the + current directory that the cookie is being set in. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>domain</parameter></term> + <listitem> + <para> + The domain that the cookie is available. + To make the cookie available on all subdomains of example.com + then you'd set it to <literal>'.example.com'</literal>. The + <literal>.</literal> is not required but makes it compatible + with more browsers. Setting it to <literal>www.example.com</literal> + will make the cookie only available in the <literal>www</literal> + subdomain. Refer to tail matching in the + <ulink url="&spec.cookies;">spec</ulink> for details. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>secure</parameter></term> + <listitem> + <para> + Indicates that the cookie should only be transmitted over a + secure HTTPS connection from the client. When set to &true;, the + cookie will only be set if a secure connection exists. The default + is &false;. On the server-side, it's on the programmer to send this + kind of cookie only on secure connection (e.g. with respect to + <literal>$_SERVER["HTTPS"]</literal>). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>httponly</parameter></term> + <listitem> + <para> + When &true; the cookie will be made accessible only through the HTTP + protocol. This means that the cookie won't be accessible by + scripting languages, such as JavaScript. This setting can effectly + help to reduce identity theft through XSS attacks (although it is + not supported by all browsers). Added in PHP 5.2.0. + &true; or &false; + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + If output exists prior to calling this function, + <function>setcookie</function> will fail and return &false;. If + <function>setcookie</function> successfully runs, it will return &true;. + This does not indicate whether the user accepted the cookie. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; <para> Some examples follow how to send cookies: <example> @@ -272,13 +215,13 @@ </informalexample> </para> <para> - When deleting a cookie you should assure that the expiration date - is in the past, to trigger the removal mechanism in your browser. - Examples follow how to delete cookies sent in previous example: - </para> - <para> <example> <title><function>setcookie</function> delete example</title> + <para> + When deleting a cookie you should assure that the expiration date + is in the past, to trigger the removal mechanism in your browser. + Examples follow how to delete cookies sent in previous example: + </para> <programlisting role="php"> <![CDATA[ <?php @@ -291,15 +234,15 @@ </example> </para> <para> - You may also set array cookies by using array notation in the - cookie name. This has the effect of setting as many cookies as - you have array elements, but when the cookie is received by your - script, the values are all placed in an array with the cookie's - name: - </para> - <para> <example> <title><function>setcookie</function> and arrays</title> + <para> + You may also set array cookies by using array notation in the + cookie name. This has the effect of setting as many cookies as + you have array elements, but when the cookie is received by your + script, the values are all placed in an array with the cookie's + name: + </para> <programlisting role="php"> <![CDATA[ <?php @@ -317,9 +260,7 @@ ?> ]]> </programlisting> - <para> - which prints - </para> + &example.outputs; <screen> <![CDATA[ three : cookiethree @@ -329,40 +270,101 @@ </screen> </example> </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <note> <para> - The following RFC's may also be useful: - <ulink url="&url.rfc;2109">RFC 2109</ulink> and - <ulink url="&url.rfc;2965">RFC 2695</ulink> - </para> - <para> - You may notice the <parameter>expire</parameter> parameter takes on a - Unix timestamp, as opposed to the date format <literal>Wdy, DD-Mon-YYYY - HH:MM:SS GMT</literal>, this is because PHP does this conversion - internally. + As of PHP 4, you can use output buffering to send output prior to the + call of this function, with the overhead of all of your output to the + browser being buffered in the server until you send it. You can do this + by calling <function>ob_start</function> and + <function>ob_end_flush</function> in your script, or setting the + <literal>output_buffering</literal> configuration directive on in your + &php.ini; or server configuration files. </para> + </note> + <note> <para> - <parameter>expire</parameter> is compared to the client's time which can - differ from server's time. + If the PHP directive <link linkend="ini.register-globals">register_globals</link> + is set to <literal>on</literal> then cookie values will also be made into + variables. In our examples below, <varname>$TestCookie</varname> will + exist. It's recommended to use <varname>$_COOKIE</varname>. </para> </note> + <para> + Common Pitfalls: + <itemizedlist> + <listitem> + <simpara> + Cookies will not become visible until the next loading of a page that + the cookie should be visible for. To test if a cookie was successfully + set, check for the cookie on a next loading page before the cookie + expires. Expire time is set via the <parameter>expire</parameter> + parameter. A nice way to debug the existence of cookies is by + simply calling <literal>print_r($_COOKIE);</literal>. + </simpara> + </listitem> + <listitem> + <simpara> + Cookies must be deleted with the same parameters as they were set with. + If the value argument is an empty string, or &false;, and all other arguments + match a previous call to setcookie, then the cookie with the specified + name will be deleted from the remote client. + </simpara> + </listitem> + <listitem> + <simpara> + Because setting a cookie with a value of &false; will try to delete the cookie, + you should not use boolean values. Instead, use <emphasis>0</emphasis> for &false; + and <emphasis>1</emphasis> for &true;. + </simpara> + </listitem> + <listitem> + <simpara> + Cookies names can be set as array names and will be available to your + PHP scripts as arrays but separate cookies are stored on the users + system. Consider <function>explode</function> to set one cookie with + multiple names and values. It is not recommended to use + <function>serialize</function> for this purpose, because it can result + in security holes. + </simpara> + </listitem> + </itemizedlist> + </para> + <simpara> + In PHP 3, multiple calls to <function>setcookie</function> in the same + script will be performed in reverse order. If you are trying to + delete one cookie before inserting another you should put the + insert before the delete. As of PHP 4, multiple calls to + <function>setcookie</function> are performed in the order called. + </simpara> <note> <simpara> - Microsoft Internet Explorer 4 with Service Pack 1 applied does - not correctly deal with cookies that have their path parameter - set. + Microsoft Internet Explorer 4 with Service Pack 1 applied does not + correctly deal with cookies that have their path parameter set. </simpara> <simpara> - Netscape Communicator 4.05 and Microsoft Internet Explorer 3.x - appear to handle cookies incorrectly when the path and time - are not set. + Netscape Communicator 4.05 and Microsoft Internet Explorer 3.x appear to + handle cookies incorrectly when the path and time are not set. </simpara> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>header</function>, <function>setrawcookie</function> - and the <link linkend="features.cookies">cookies section</link>. + <simplelist> + <member><function>header</function></member> + <member><function>setrawcookie</function></member> + <member><link linkend="features.cookies">cookies section</link></member> + <member><ulink url="&url.rfc;2109">RFC 2109</ulink></member> + <member><ulink url="&url.rfc;2965">RFC 2695</ulink></member> + </simplelist> </para> </refsect1> + </refentry>  - + <refentry id="function.setrawcookie"> <refnamediv> <refname>setrawcookie</refname> <refpurpose>Send a cookie without urlencoding the cookie value</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>setrawcookie</methodname> <methodparam><type>string</type><parameter>name</parameter></methodparam> @@ -20,19 +20,51 @@ </methodsynopsis> <para> <function>setrawcookie</function> is exactly the same as - <function>setcookie</function> except that the cookie value will not - be automatically urlencoded when sent to the browser. + <function>setcookie</function> except that the cookie value will not be + automatically urlencoded when sent to the browser. </para> - <note> - <para> - The <parameter>httponly</parameter> parameter was added in PHP 5.2.0. - </para> - </note> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; <para> - See also <function>header</function>, <function>setcookie</function> and the - <link linkend="features.cookies">cookies section</link>. + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>5.2.0</entry> + <entry> + The <parameter>httponly</parameter> parameter was added. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </para> </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>setcookie</function></member> + </simplelist> + </para> + </refsect1> + </refentry>  - + <refentry id="function.socket-get-status"> <refnamediv> <refname>socket_get_status</refname> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/network/functions/socket-set-blocking.xml?r1=1.6&r2=1.7&diff_format=u Index: phpdoc/en/reference/network/functions/socket-set-blocking.xml diff -u phpdoc/en/reference/network/functions/socket-set-blocking.xml:1.6 phpdoc/en/reference/network/functions/socket-set-blocking.xml:1.7 --- phpdoc/en/reference/network/functions/socket-set-blocking.xml:1.6 Mon Apr 25 16:17:01 2005 +++ phpdoc/en/reference/network/functions/socket-set-blocking.xml Sun Jun 10 01:57:09 2007 @@ -1,6 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.socket-set-blocking"> <refnamediv> <refname>socket_set_blocking</refname> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/network/functions/socket-set-timeout.xml?r1=1.8&r2=1.9&diff_format=u Index: phpdoc/en/reference/network/functions/socket-set-timeout.xml diff -u phpdoc/en/reference/network/functions/socket-set-timeout.xml:1.8 phpdoc/en/reference/network/functions/socket-set-timeout.xml:1.9 --- phpdoc/en/reference/network/functions/socket-set-timeout.xml:1.8 Mon Apr 25 16:17:01 2005 +++ phpdoc/en/reference/network/functions/socket-set-timeout.xml Sun Jun 10 01:57:09 2007 @@ -1,6 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.socket-set-timeout"> <refnamediv> <refname>socket_set_timeout</refname> http://cvs.php.net/viewvc.cgi/phpdoc/en/reference/network/functions/syslog.xml?r1=1.10&r2=1.11&diff_format=u Index: phpdoc/en/reference/network/functions/syslog.xml diff -u phpdoc/en/reference/network/functions/syslog.xml:1.10 phpdoc/en/reference/network/functions/syslog.xml:1.11 --- phpdoc/en/reference/network/functions/syslog.xml:1.10 Sun Jun 10 01:55:51 2007 +++ phpdoc/en/reference/network/functions/syslog.xml Sun Jun 10 01:57:09 2007 @@ -1,13 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> - - + <refentry id="function.syslog"> <refnamediv> <refname>syslog</refname> <refpurpose>Generate a system log message</refpurpose> </refnamediv> - <refsect1> - <title>Description</title> + + <refsect1 role="description"> + &reftitle.description; <methodsynopsis> <type>bool</type><methodname>syslog</methodname> <methodparam><type>int</type><parameter>priority</parameter></methodparam> @@ -16,61 +16,100 @@ <para> <function>syslog</function> generates a log message that will be distributed by the system logger. - <parameter>priority</parameter> is a combination of the facility - and the level, values for which are given in the next section. - The remaining argument is the message to send, except that the - two characters <literal>%m</literal> will be replaced by the - error message string (strerror) corresponding to the present - value of <errortype>errno</errortype>. - </para> - <para> - <table> - <title><function>syslog</function> Priorities (in descending order)</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Constant</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>LOG_EMERG</entry> - <entry>system is unusable</entry> - </row> - <row> - <entry>LOG_ALERT</entry> - <entry>action must be taken immediately</entry> - </row> - <row> - <entry>LOG_CRIT</entry> - <entry>critical conditions</entry> - </row> - <row> - <entry>LOG_ERR</entry> - <entry>error conditions</entry> - </row> - <row> - <entry>LOG_WARNING</entry> - <entry>warning conditions</entry> - </row> - <row> - <entry>LOG_NOTICE</entry> - <entry>normal, but significant, condition</entry> - </row> - <row> - <entry>LOG_INFO</entry> - <entry>informational message</entry> - </row> - <row> - <entry>LOG_DEBUG</entry> - <entry>debug-level message</entry> - </row> - </tbody> - </tgroup> - </table> </para> <para> + For information on setting up a user defined log handler, see the + <citerefentry><refentrytitle>syslog.conf</refentrytitle> + <manvolnum>5</manvolnum></citerefentry> Unix manual page. More + information on the syslog facilities and option can be found in the man + pages for <citerefentry><refentrytitle>syslog</refentrytitle> + <manvolnum>3</manvolnum></citerefentry> on Unix machines. + </para> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>priority</parameter></term> + <listitem> + <para> + <parameter>priority</parameter> is a combination of the facility and + the level. Possible values are: + <table> + <title><function>syslog</function> Priorities (in descending order)</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Constant</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>LOG_EMERG</constant></entry> + <entry>system is unusable</entry> + </row> + <row> + <entry><constant>LOG_ALERT</constant></entry> + <entry>action must be taken immediately</entry> + </row> + <row> + <entry><constant>LOG_CRIT</constant></entry> + <entry>critical conditions</entry> + </row> + <row> + <entry><constant>LOG_ERR</constant></entry> + <entry>error conditions</entry> + </row> + <row> + <entry><constant>LOG_WARNING</constant></entry> + <entry>warning conditions</entry> + </row> + <row> + <entry><constant>LOG_NOTICE</constant></entry> + <entry>normal, but significant, condition</entry> + </row> + <row> + <entry><constant>LOG_INFO</constant></entry> + <entry>informational message</entry> + </row> + <row> + <entry><constant>LOG_DEBUG</constant></entry> + <entry>debug-level message</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>message</parameter></term> + <listitem> + <para> + The message to send, except that the two characters + <literal>%m</literal> will be replaced by the error message string + (strerror) corresponding to the present value of + <errortype>errno</errortype>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> <example> <title>Using <function>syslog</function></title> <programlisting role="php"> @@ -98,13 +137,11 @@ ]]> </programlisting> </example> - For information on setting up a user defined log handler, see the - <citerefentry><refentrytitle>syslog.conf</refentrytitle> - <manvolnum>5</manvolnum></citerefentry> Unix manual page. More - information on the syslog facilities and option can be found in the man - pages for <citerefentry><refentrytitle>syslog</refentrytitle> - <manvolnum>3</manvolnum></citerefentry> on Unix machines. </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; <para> On Windows NT, the syslog service is emulated using the Event Log. @@ -117,12 +154,19 @@ in Windows. </para> </note> + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>define_syslog_variables</function>, - <function>openlog</function> and - <function>closelog</function>. + <simplelist> + <member><function>define_syslog_variables</function></member> + <member><function>openlog</function></member> + <member><function>closelog</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file