From 1fa343d1abdd0b62c68b3c87bf8ced6236a79232 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Fri, 9 Dec 2005 16:37:05 +0000
Subject: [PATCH] Added example program demonstrating use of fork() and
 waitpid().

---
 man2/wait.2 | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/man2/wait.2 b/man2/wait.2
index 4a0aab533..922adb0be 100644
--- a/man2/wait.2
+++ b/man2/wait.2
@@ -485,6 +485,79 @@ type ("clone" or "non-clone").
 .\" since patch-2.4.0-test8
 (Since Linux 2.4) Do not wait for children of other threads in
 the same thread group. This was the default before Linux 2.4.
+.SH EXAMPLE
+The following program demonstrates the use of 
+.BR fork(2) 
+and 
+.BR waitpid (2).
+The program creates a child process.
+If no command-line argument is supplied to the program, 
+then the child suspends its execution using 
+.BR pause (2),
+to allow the user to send signals to the child.
+Otherwise, if a command-line argument is supplied,
+then the child exits immediately, 
+using the integer supplied on the command line as the exit status.
+The parent process executes a loop that monitors the child using
+.BR waitpid (2),
+and uses the W*() macros described above to analyse the wait status value.
+
+The following shell session demonstrates the use of the program:
+.nf
+
+$ ./a.out &
+Child PID is 32360
+[1] 32359
+$ kill -STOP 32360
+stopped by signal 19
+$ kill -CONT 32360
+continued
+$ kill -TERM 32360
+killed by signal 15
+[1]+  Done                    ./a.out
+$
+
+
+#include <sys/wait.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <stdio.h>
+
+int
+main(int argc, char *argv[])
+{
+    pid_t cpid, w;
+    int status;
+
+    cpid = fork();
+    if (cpid == -1) { perror("fork"); exit(EXIT_FAILURE); }
+
+    if (cpid == 0) {            /* Code executed by child */
+        printf("Child PID is %ld\\n", (long) getpid());
+        if (argc == 1)
+            pause();                    /* Wait for signals */
+        _exit(atoi(argv[1]));
+
+    } else {                    /* Code executed by parent */
+        do {
+            w = waitpid(cpid, &status, WUNTRACED | WCONTINUED);
+            if (w == -1) { perror("waitpid"); exit(EXIT_FAILURE); }
+
+            if (WIFEXITED(status)) {
+                printf("exited, status=%d\\n", WEXITSTATUS(status));
+            } else if (WIFSIGNALED(status)) {
+                printf("killed by signal %d\\n", WTERMSIG(status));
+            } else if (WIFSTOPPED(status)) {
+                printf("stopped by signal %d\\n", WSTOPSIG(status));
+            } else if (WIFCONTINUED(status)) {
+                printf("continued\\n");
+            }
+        } while (!WIFEXITED(status) && !WIFSIGNALED(status));
+        exit(EXIT_SUCCESS);
+    }
+}
+
+.fi
 .SH "CONFORMING TO"
 SVr4, POSIX.1
 .SH "SEE ALSO"