Implement pause()

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@5376 42af7a65-404d-4744-a932-0658087f49c3

5 files changed, 152 insertions, 3 deletions

diff --git a/nuttx/ChangeLog b/nuttx/ChangeLog
index d5f13d407..c5537e17a 100644
--- a/nuttx/ChangeLog
+++ b/nuttx/ChangeLog
@@ -3651,4 +3651,6 @@
 	* arch/several:  Change UARTs are enabled for i.MX, LM3S, ez80, and M16C to
 	  match how they are enabled for other architectures.
 	* configs/ez80f910200kitg:  Convert to use mconf configuration.
+	* sched/pause.c:  Implements the POSIX pause() function.
+
 
diff --git a/nuttx/Documentation/NuttxUserGuide.html b/nuttx/Documentation/NuttxUserGuide.html
index 586b744c7..5326f2280 100644
--- a/nuttx/Documentation/NuttxUserGuide.html
+++ b/nuttx/Documentation/NuttxUserGuide.html
@@ -13,7 +13,7 @@
       <h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></font></big></h1>
       <p><small>by</small></p>
       <p>Gregory Nutt<p>
-      <p>Last Updated: August 1, 2012</p>
+      <p>Last Updated: November 20, 2012</p>
     </td>
   </tr>
 </table>
@@ -3419,6 +3419,7 @@ interface of the same name.
   <li><a href="#sigtimedwait">2.8.11 sigtimedwait</a></li>
   <li><a href="#sigqueue">2.8.12 sigqueue</a></li>
   <li><a href="#kill">2.8.13 kill</a></li>
+  <li><a href="#pause">2.8.14 pause</a></li>
 </ul>
 
 <H3><a name="sigemptyset">2.8.1 sigemptyset</a></H3>
@@ -3946,7 +3947,7 @@ be sent.
 <b>Function Prototype:</b> 
 <pre>
    #include &lt;sys/types.h&gt;
-   #include &ltsignal.h&gt;
+   #include &lt;signal.h&gt;
    int kill(pid_t pid, int sig);
 </pre>
 
@@ -3996,6 +3997,39 @@ be sent.
   <li>Sending of signals to 'process groups' is not supported in NuttX.</li>
 </ul>
 
+<H3><a name="pause">2.8.14 pause</a></H3>
+
+<p>
+<b>Function Prototype:</b> 
+<pre>
+   #include &lt;unistd.h&gt;
+   int pause(void);
+</pre>
+
+<p>
+<b>Description:</b> 
+  The <code>pause()</code> function will suspend the calling thread until delivery of a non-blocked signal.
+</p>
+<b>Input Parameters:</b> 
+<ul>
+<li><i>None</i>
+</ul>
+
+<p>
+  <b>Returned Value:</b> 
+ Since <code>pause()</code> suspends thread execution indefinitely unless interrupted a signal, there is no successful completion return value.
+ A value of -1 (<code>ERROR</code> will always be returned and errno set to indicate the error (<code>EINTR</code>).
+</p>
+
+<p>
+  <b>Assumptions/Limitations:</b> 
+</p>
+<p>
+  <b>POSIX  Compatibility:</b>
+    In the POSIX description of this function is the <code>pause()</code> function will suspend the calling thread until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process.
+    This implementation only waits for any non-blocked signal to be recieved.
+</p>
+
 <table width ="100%">
   <tr bgcolor="#e4e4e4">
   <td>
@@ -6711,6 +6745,7 @@ pid_t   getpid(void);
 void    _exit(int status) noreturn_function;
 unsigned int sleep(unsigned int seconds);
 void    usleep(unsigned long usec);
+int     pause(void);
 
 int     close(int fd);
 int     dup(int fd);
@@ -8187,6 +8222,7 @@ notify a task when a message is available on a queue.
 </td>
 <td valign="top" width="33%">
   <li><a href="#OS_Interfaces">OS Interfaces</a></li>
+  <li><a href="#pause">pause</a></li>
   <li><a href="#pipe">pipe</a></li>
   <li><a href="#poll">poll</a></li>
   <li><a href="#drvrpollops">poll.h</a></li>
diff --git a/nuttx/include/unistd.h b/nuttx/include/unistd.h
index e2ad6ff82..681ce9e63 100644
--- a/nuttx/include/unistd.h
+++ b/nuttx/include/unistd.h
@@ -133,6 +133,7 @@ EXTERN pid_t   getpid(void);
 EXTERN void    _exit(int status) noreturn_function;
 EXTERN unsigned int sleep(unsigned int seconds);
 EXTERN int     usleep(useconds_t usec);
+EXTERN int     pause(void);
 
 /* File descriptor operations */
 
diff --git a/nuttx/sched/Makefile b/nuttx/sched/Makefile
index 9b15108f4..82f74fc3c 100644
--- a/nuttx/sched/Makefile
+++ b/nuttx/sched/Makefile
@@ -94,7 +94,7 @@ SIGNAL_SRCS	= sig_initialize.c \
 		  sig_findaction.c sig_allocatependingsigaction.c \
 		  sig_releasependingsigaction.c sig_unmaskpendingsignal.c \
 		  sig_removependingsignal.c sig_releasependingsignal.c sig_lowest.c \
-		  sig_mqnotempty.c sig_cleanup.c sig_received.c sig_deliver.c
+		  sig_mqnotempty.c sig_cleanup.c sig_received.c sig_deliver.c pause.c
 
 MQUEUE_SRCS	= mq_open.c mq_close.c mq_unlink.c mq_send.c mq_timedsend.c\
 		  mq_sndinternal.c mq_receive.c mq_timedreceive.c mq_rcvinternal.c \
diff --git a/nuttx/sched/pause.c b/nuttx/sched/pause.c
new file mode 100644
index 000000000..fb5542d84
--- /dev/null
+++ b/nuttx/sched/pause.c
@@ -0,0 +1,110 @@
+/****************************************************************************
+ * sched/pause.c
+ *
+ *   Copyright (C) 2012 Gregory Nutt. All rights reserved.
+ *   Author: Gregory Nutt <gnutt@nuttx.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ * 3. Neither the name NuttX nor the names of its contributors may be
+ *    used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+ * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+ * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+ * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <unistd.h>
+#include <signal.h>
+
+/****************************************************************************
+ * Preprocessor Definitions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Private Type Definitions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Global Variables
+ ****************************************************************************/
+
+/****************************************************************************
+ * Private Variables
+ ****************************************************************************/
+
+/****************************************************************************
+ * Private Function Prototypes
+ ****************************************************************************/
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: pause
+ *
+ * Description:
+ *   The pause() function will suspend the calling thread until delivery of a
+ *   non-blocked signal.
+ *
+ * Input Parameters:
+ *   None
+ *
+ * Returned Value:
+ *   Since pause() suspends thread execution indefinitely unless interrupted 
+ *   a signal, there is no successful completion return value. A value of -1
+ *   will always be returned and errno set to indicate the error (EINTR).
+ *
+ * POSIX compatibility:
+ *   In the POSIX description of this function is the pause() function will
+ *   suspend the calling thread until delivery of a signal whose action is
+ *   either to execute a signal-catching function or to terminate the
+ *   process.  This implementation only waits for any non-blocked signal
+ *   to be recieved.
+ *
+ ****************************************************************************/
+
+int pause(void)
+{
+  sigset_t set;
+  struct siginfo value;
+ 
+  /* Set up for the sleep.  Using the empty set means that we are not
+   * waiting for any particualar signal.  However, any unmasked signal
+   * can still awaken sigtimedwait().
+   */
+
+  (void)sigemptyset(&set);
+
+  /* sigtwaitinfo() cannot succeed.  It should always return error EINTR
+   * meaning that some unblocked signal was caught.
+   */
+
+  return sigwaitinfo(&set, &value);
+}