From 3568fecf934e4b99e0374e08dc790ff77812bf87 Mon Sep 17 00:00:00 2001
From: Nuno Lopes <nlopess@php.net>
Date: Wed, 23 Feb 2005 12:52:26 +0000
Subject: [PATCH] convert to new style, expland explanations and add an example

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@180559 c90b9560-bf6c-de11-be94-00142212c4b1
---
 .../stream/functions/stream-socket-pair.xml   | 152 +++++++++++++++---
 1 file changed, 131 insertions(+), 21 deletions(-)

diff --git a/reference/stream/functions/stream-socket-pair.xml b/reference/stream/functions/stream-socket-pair.xml
index 1046452717..4c74b37eb4 100755
--- a/reference/stream/functions/stream-socket-pair.xml
+++ b/reference/stream/functions/stream-socket-pair.xml
@@ -1,27 +1,137 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
-  <refentry id="function.stream-socket-pair">
-   <refnamediv>
-    <refname>stream_socket_pair</refname>
-    <refpurpose>
-     Creates a pair of connected, indistinguishable socket streams
-    </refpurpose>
-   </refnamediv>
-   <refsect1>
-    <title>Description</title>
-    <methodsynopsis>
-     <type>array</type><methodname>stream_socket_pair</methodname>
-     <methodparam><type>int</type><parameter>domain</parameter></methodparam>
-     <methodparam><type>int</type><parameter>type</parameter></methodparam>
-     <methodparam><type>int</type><parameter>protocol</parameter></methodparam>
-    </methodsynopsis>
+<!-- $Revision: 1.2 $ -->
+<refentry id="function.stream-socket-pair">
+ <refnamediv>
+  <refname>stream_socket_pair</refname>
+  <refpurpose>
+   Creates a pair of connected, indistinguishable socket streams
+  </refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>array</type><methodname>stream_socket_pair</methodname>
+   <methodparam><type>int</type><parameter>domain</parameter></methodparam>
+   <methodparam><type>int</type><parameter>type</parameter></methodparam>
+   <methodparam><type>int</type><parameter>protocol</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   <function>stream_socket_pair</function> creates a pair of connected,
+   indistinguishable socket streams. This function is commonly used in IPC
+   (Inter-Process Communication).     
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>domain</parameter></term>
+     <listitem>
+      <para>
+       The protocol family to be used: <constant>STREAM_PF_INET</constant>,
+       <constant>STREAM_PF_INET6</constant> or
+       <constant>STREAM_PF_UNIX</constant>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>type</parameter></term>
+     <listitem>
+      <para>
+       The type of communication to be used:
+       <constant>STREAM_SOCK_DGRAM</constant>,
+       <constant>STREAM_SOCK_RAW</constant>,
+       <constant>STREAM_SOCK_RDM</constant>,
+       <constant>STREAM_SOCK_SEQPACKET</constant> or
+       <constant>STREAM_SOCK_STREAM</constant>
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>protocol</parameter></term>
+     <listitem>
+      <para>
+       The protocol to be used: <constant>STREAM_IPPROTO_ICMP</constant>,
+       <constant>STREAM_IPPROTO_IP</constant>,
+       <constant>STREAM_IPPROTO_RAW</constant>,
+       <constant>STREAM_IPPROTO_TCP</constant> or
+       <constant>STREAM_IPPROTO_UDP</constant>       
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+  <note>
+   <simpara>
+    Please consult the <link linkend="stream.constants">Streams constant
+     list</link> for further details on each constant.
+   </simpara>
+  </note>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns an <type>array</type> with the two socket resources on success, or
+   &false; on failure.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>A <function>stream_socket_pair</function> example</title>
     <para>
-     <function>stream_socket_pair</function> creates a pair of connected,
-     indistinguishable socket streams. This function is commonly used in IPC
-     (InterProcess Communication).     
+     This example shows the basic usage of
+     <function>stream_socket_pair</function> in Inter-Process Comunication.
     </para>
-   </refsect1>
-  </refentry>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$sockets = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
+$pid     = pcntl_fork();
+
+if ($pid == -1) {
+     die('could not fork');
+
+} else if ($pid) {
+     /* parent */
+    fclose($sockets[0]);
+
+    fwrite($sockets[1], "child PID: $pid\n");
+    echo fgets($sockets[1]);
+
+    fclose($sockets[1]);
+
+} else {
+    /* child */
+    fclose($sockets[1]);
+
+    fwrite($sockets[0], "message from child\n");
+    echo fgets($sockets[0]);
+
+    fclose($sockets[0]);
+}
+
+?>
+]]>
+    </programlisting>
+    &example.outputs.similar;
+    <screen>
+<![CDATA[
+child PID: 1378
+message from child
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+</refentry>
 
 <!-- Keep this comment at the end of the file
 Local variables: