<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<!-- Author: Wez Furlong <wez@thebrainroom.com>
  Please contact me before making any major amendments to the
  content of this section.  Splitting/Merging are fine if they are
  required for php-doc restructuring purposes - just drop me a line
  if you make a change (so I can update my local copy).
-->

 <sect1 id="streams.socket-api">
  <title>Streams Socket API Reference</title>

  <refentry id="streams.php-stream-sock-open-from-socket">
   <refnamediv>
    <refname>php_stream_sock_open_from_socket</refname>
    <refpurpose>Convert a socket descriptor into a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>php_stream *</type><methodname>php_stream_sock_open_from_socket</methodname>
      <methodparam><type>int</type><parameter>socket</parameter></methodparam>
      <methodparam><type>int</type><parameter>persistent</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_sock_open_from_socket</function> returns a stream based on the
     <parameter>socket</parameter>. <parameter>persistent</parameter> is a flag that
     controls whether the stream is opened as a persistent stream.  Generally speaking, this parameter
     will usually be 0.
     </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-sock-open-host">
   <refnamediv>
    <refname>php_stream_sock_open_host</refname>
    <refpurpose>Open a connection to a host and return a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>php_stream *</type><methodname>php_stream_sock_open_host</methodname>
      <methodparam><type>const char *</type><parameter>host</parameter></methodparam>
      <methodparam><type>unsigned short</type><parameter>port</parameter></methodparam>
      <methodparam><type>int</type><parameter>socktype</parameter></methodparam>
      <methodparam><type>struct timeval *</type><parameter>timeout</parameter></methodparam>
      <methodparam><type>int</type><parameter>persistent</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_sock_open_host</function> establishes a connect to the specified
     <parameter>host</parameter> and <parameter>port</parameter>. <parameter>socktype</parameter>
     specifies the connection semantics that should apply to the connection. Values for
     <parameter>socktype</parameter> are system dependent, but will usually include (at a minimum)
     <constant>SOCK_STREAM</constant> for sequenced, reliable, two-way connection based streams (TCP),
     or <constant>SOCK_DGRAM</constant> for connectionless, unreliable messages of a fixed maximum
     length (UDP).
    </para>
    <para>
     <parameter>persistent</parameter> is a flag the controls whether the stream is opened as a persistent
     stream. Generally speaking, this parameter will usually be 0.
    </para>
    <para>
     If not NULL, <parameter>timeout</parameter> specifies a maximum time to allow for the connection to be made.
     If the connection attempt takes longer than the timeout value, the connection attempt is aborted and
     NULL is returned to indicate that the stream could not be opened.
    </para>
    <note>
     <simpara>
      The timeout value does not include the time taken to perform a DNS lookup. The reason for this is
      because there is no portable way to implement a non-blocking DNS lookup.
     </simpara>
     <simpara>
      The timeout only applies to the connection phase; if you need to set timeouts for subsequent read
      or write operations, you should use <function>php_stream_sock_set_timeout</function> to configure
      the timeout duration for your stream once it has been opened.
     </simpara>
    </note>
    <para>
     The streams API places no restrictions on the values you use for <parameter>socktype</parameter>,
     but encourages you to consider the portability of values you choose before you release your
     extension.
    </para>
   </refsect1>
  </refentry>

  <refentry id="streams.php-stream-sock-open-unix">
   <refnamediv>
    <refname>php_stream_sock_open_unix</refname>
    <refpurpose>Open a UNIX domain socket and convert into a stream</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>php_stream *</type><methodname>php_stream_sock_open_unix</methodname>
      <methodparam><type>const char *</type><parameter>path</parameter></methodparam>
      <methodparam><type>int</type><parameter>pathlen</parameter></methodparam>
      <methodparam><type>int</type><parameter>persistent</parameter></methodparam>
      <methodparam><type>struct timeval *</type><parameter>timeout</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>php_stream_sock_open_unix</function> attempts to open the UNIX domain socket
      specified by <parameter>path</parameter>.  <parameter>pathlen</parameter> specifies the
      length of <parameter>path</parameter>.
      If <parameter>timeout</parameter> is not NULL, it specifies a timeout period for the connection attempt.
      <parameter>persistent</parameter> indicates if the stream should be opened as a persistent
      stream. Generally speaking, this parameter will usually be 0.
     </para>
     <note>
      <simpara>
       This function will not work under Windows, which does not implement unix domain sockets.
       A possible exception to this rule is if your PHP binary was built using cygwin.  You are encouraged
       to consider this aspect of the portability of your extension before it's release.
      </simpara>
    </note>
    <note>
      <simpara>
       This function treats <parameter>path</parameter> in a binary safe manner, suitable for
       use on systems with an abstract namespace (such as Linux), where the first character
       of path is a NUL character.
      </simpara>
    </note>
   </refsect1>
  </refentry>



 </sect1>
 
 
 

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->