From edd777d73cee024fd93d4a2041041112ef97ad05 Mon Sep 17 00:00:00 2001
From: Dave Barr <dave@php.net>
Date: Tue, 10 Aug 2004 18:45:07 +0000
Subject: [PATCH] - Document time_nanosleep(), with example.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@165949 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/misc/functions/time-nanosleep.xml | 85 ++++++++++++++++++++-
 1 file changed, 81 insertions(+), 4 deletions(-)

diff --git a/reference/misc/functions/time-nanosleep.xml b/reference/misc/functions/time-nanosleep.xml
index ebb4be4fae..312b85ded6 100644
--- a/reference/misc/functions/time-nanosleep.xml
+++ b/reference/misc/functions/time-nanosleep.xml
@@ -1,22 +1,99 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <refentry id="function.time-nanosleep">
  <refnamediv>
   <refname>time_nanosleep</refname>
   <refpurpose>
-   Delay for a number of seconds and nano seconds
+   Delay for a number of seconds and nanoseconds
   </refpurpose>
  </refnamediv>
  <refsect1>
-  <title>Description</title>
+  &reftitle.description;
   <methodsynopsis>
    <type>mixed</type><methodname>time_nanosleep</methodname>
    <methodparam><type>int</type><parameter>seconds</parameter></methodparam>
    <methodparam><type>int</type><parameter>nanoseconds</parameter></methodparam>
   </methodsynopsis>
+  <para>
+   Delays program execution for the given number of
+   <parameter>seconds</parameter> and <parameter>nanoseconds</parameter>.
+  </para>
+  <para>
+   <parameter>seconds</parameter> must be a positive integer, and
+   <parameter>nanoseconds</parameter> must be a positive integer less than
+   1 billion.
+  </para>
+ </refsect1>
+ <refsect1>
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; on success, &false; on failure.
+  </para>
+  <para>
+   If the delay was interrupted by a signal, an associative array will be
+   returned with the components:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      <literal>seconds</literal> - number of seconds remaining in
+      the delay
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>nanoseconds</literal> - number of nanoseconds
+      remaining in the delay
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+ </refsect1>
+ <refsect1>
+  &reftitle.seealso;
+  <para>
+   <function>sleep</function>,
+   <function>usleep</function>,
+   <function>set_time_limit</function>
+  </para>
+ </refsect1>
+ <refsect1>
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>time_nanosleep</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+/* Careful! This won't work as expected if an array is returned */
+if (time_nanosleep(0, 500000)) {
+    echo "Slept for half a second.\n";
+}
 
-   &warn.undocumented.func;
+/* This is better: */
+if (time_nanosleep(0, 500000) === true) {
+    echo "Slept for half a second.\n";
+}
 
+/* And this is the best: */
+$nano = time_nanosleep(2, 100000);
+
+if ($nano === true) {
+    echo "Slept for 2 seconds, 100 milliseconds.\n";
+}
+else if ($nano === false) {
+    echo "Sleeping failed.\n";
+}
+else if (is_array($nano)) {
+    $seconds = $nano['seconds'];
+    $nanoseconds = $nano['nanoseconds'];
+    echo "Interrupted by a signal.\n";
+    echo "Time remaining: $seconds seconds, $nanoseconds nanoseconds.";
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
  </refsect1>
 </refentry>