Tell about cleanup handlers & system,waitpid,wait.
[kopensolaris-gnu/glibc.git] / manual / process.texi
1 @node Processes
2 @chapter Processes
3
4 @cindex process
5 @dfn{Processes} are the primitive units for allocation of system
6 resources.  Each process has its own address space and (usually) one
7 thread of control.  A process executes a program; you can have multiple
8 processes executing the same program, but each process has its own copy
9 of the program within its own address space and executes it
10 independently of the other copies.
11
12 @cindex child process
13 @cindex parent process
14 Processes are organized hierarchically.  Each process has a @dfn{parent
15 process} which explicitly arranged to create it.  The processes created
16 by a given parent are called its @dfn{child processes}.  A child
17 inherits many of its attributes from the parent process.
18
19 This chapter describes how a program can create, terminate, and control
20 child processes.  Actually, there are three distinct operations
21 involved: creating a new child process, causing the new process to
22 execute a program, and coordinating the completion of the child process
23 with the original program.
24
25 The @code{system} function provides a simple, portable mechanism for
26 running another program; it does all three steps automatically.  If you
27 need more control over the details of how this is done, you can use the
28 primitive functions to do each step individually instead.
29
30 @menu
31 * Running a Command::           The easy way to run another program.
32 * Process Creation Concepts::   An overview of the hard way to do it.
33 * Process Identification::      How to get the process ID of a process.
34 * Creating a Process::          How to fork a child process.
35 * Executing a File::            How to make a process execute another program.
36 * Process Completion::          How to tell when a child process has completed.
37 * Process Completion Status::   How to interpret the status value
38                                  returned from a child process.
39 * BSD Wait Functions::          More functions, for backward compatibility.
40 * Process Creation Example::    A complete example program.
41 @end menu
42
43
44 @node Running a Command
45 @section Running a Command
46 @cindex running a command
47
48 The easy way to run another program is to use the @code{system}
49 function.  This function does all the work of running a subprogram, but
50 it doesn't give you much control over the details: you have to wait
51 until the subprogram terminates before you can do anything else.
52
53 @comment stdlib.h
54 @comment ISO
55 @deftypefun int system (const char *@var{command})
56 @pindex sh
57 This function executes @var{command} as a shell command.  In the GNU C
58 library, it always uses the default shell @code{sh} to run the command.
59 In particular, it searches the directories in @code{PATH} to find
60 programs to execute.  The return value is @code{-1} if it wasn't
61 possible to create the shell process, and otherwise is the status of the
62 shell process.  @xref{Process Completion}, for details on how this
63 status code can be interpreted.
64
65 This function is a cancelation point in multi-threaded programs.  This
66 is a problem if the thread allocates some resources (like memory, file
67 descriptors, semaphores or whatever) at the time @code{system} is
68 called.  If the thread gets canceled these resources stay allocated
69 until the program ends.  To avoid this calls to @code{system} should be
70 protected using cancelation handlers.
71 @c ref pthread_cleanup_push / pthread_cleanup_pop
72
73 @pindex stdlib.h
74 The @code{system} function is declared in the header file
75 @file{stdlib.h}.
76 @end deftypefun
77
78 @strong{Portability Note:} Some C implementations may not have any
79 notion of a command processor that can execute other programs.  You can
80 determine whether a command processor exists by executing
81 @w{@code{system (NULL)}}; if the return value is nonzero, a command
82 processor is available.
83
84 The @code{popen} and @code{pclose} functions (@pxref{Pipe to a
85 Subprocess}) are closely related to the @code{system} function.  They
86 allow the parent process to communicate with the standard input and
87 output channels of the command being executed.
88
89 @node Process Creation Concepts
90 @section Process Creation Concepts
91
92 This section gives an overview of processes and of the steps involved in
93 creating a process and making it run another program.
94
95 @cindex process ID
96 @cindex process lifetime
97 Each process is named by a @dfn{process ID} number.  A unique process ID
98 is allocated to each process when it is created.  The @dfn{lifetime} of
99 a process ends when its termination is reported to its parent process;
100 at that time, all of the process resources, including its process ID,
101 are freed.
102
103 @cindex creating a process
104 @cindex forking a process
105 @cindex child process
106 @cindex parent process
107 Processes are created with the @code{fork} system call (so the operation
108 of creating a new process is sometimes called @dfn{forking} a process).
109 The @dfn{child process} created by @code{fork} is a copy of the original
110 @dfn{parent process}, except that it has its own process ID.
111
112 After forking a child process, both the parent and child processes
113 continue to execute normally.  If you want your program to wait for a
114 child process to finish executing before continuing, you must do this
115 explicitly after the fork operation, by calling @code{wait} or
116 @code{waitpid} (@pxref{Process Completion}).  These functions give you
117 limited information about why the child terminated---for example, its
118 exit status code.
119
120 A newly forked child process continues to execute the same program as
121 its parent process, at the point where the @code{fork} call returns.
122 You can use the return value from @code{fork} to tell whether the program
123 is running in the parent process or the child.
124
125 @cindex process image
126 Having several processes run the same program is only occasionally
127 useful.  But the child can execute another program using one of the
128 @code{exec} functions; see @ref{Executing a File}.  The program that the
129 process is executing is called its @dfn{process image}.  Starting
130 execution of a new program causes the process to forget all about its
131 previous process image; when the new program exits, the process exits
132 too, instead of returning to the previous process image.
133
134 @node Process Identification
135 @section Process Identification
136
137 The @code{pid_t} data type represents process IDs.  You can get the
138 process ID of a process by calling @code{getpid}.  The function
139 @code{getppid} returns the process ID of the parent of the current
140 process (this is also known as the @dfn{parent process ID}).  Your
141 program should include the header files @file{unistd.h} and
142 @file{sys/types.h} to use these functions.
143 @pindex sys/types.h
144 @pindex unistd.h
145
146 @comment sys/types.h
147 @comment POSIX.1
148 @deftp {Data Type} pid_t
149 The @code{pid_t} data type is a signed integer type which is capable
150 of representing a process ID.  In the GNU library, this is an @code{int}.
151 @end deftp
152
153 @comment unistd.h
154 @comment POSIX.1
155 @deftypefun pid_t getpid (void)
156 The @code{getpid} function returns the process ID of the current process.
157 @end deftypefun
158
159 @comment unistd.h
160 @comment POSIX.1
161 @deftypefun pid_t getppid (void)
162 The @code{getppid} function returns the process ID of the parent of the
163 current process.
164 @end deftypefun
165
166 @node Creating a Process
167 @section Creating a Process
168
169 The @code{fork} function is the primitive for creating a process.
170 It is declared in the header file @file{unistd.h}.
171 @pindex unistd.h
172
173 @comment unistd.h
174 @comment POSIX.1
175 @deftypefun pid_t fork (void)
176 The @code{fork} function creates a new process.
177
178 If the operation is successful, there are then both parent and child
179 processes and both see @code{fork} return, but with different values: it
180 returns a value of @code{0} in the child process and returns the child's
181 process ID in the parent process.
182
183 If process creation failed, @code{fork} returns a value of @code{-1} in
184 the parent process.  The following @code{errno} error conditions are
185 defined for @code{fork}:
186
187 @table @code
188 @item EAGAIN
189 There aren't enough system resources to create another process, or the
190 user already has too many processes running.  This means exceeding the
191 @code{RLIMIT_NPROC} resource limit, which can usually be increased;
192 @pxref{Limits on Resources}.
193
194 @item ENOMEM
195 The process requires more space than the system can supply.
196 @end table
197 @end deftypefun
198
199 The specific attributes of the child process that differ from the
200 parent process are:
201
202 @itemize @bullet
203 @item
204 The child process has its own unique process ID.
205
206 @item
207 The parent process ID of the child process is the process ID of its
208 parent process.
209
210 @item
211 The child process gets its own copies of the parent process's open file
212 descriptors.  Subsequently changing attributes of the file descriptors
213 in the parent process won't affect the file descriptors in the child,
214 and vice versa.  @xref{Control Operations}.  However, the file position
215 associated with each descriptor is shared by both processes;
216 @pxref{File Position}.
217
218 @item
219 The elapsed processor times for the child process are set to zero;
220 see @ref{Processor Time}.
221
222 @item
223 The child doesn't inherit file locks set by the parent process.
224 @c !!! flock locks shared
225 @xref{Control Operations}.
226
227 @item
228 The child doesn't inherit alarms set by the parent process.
229 @xref{Setting an Alarm}.
230
231 @item
232 The set of pending signals (@pxref{Delivery of Signal}) for the child
233 process is cleared.  (The child process inherits its mask of blocked
234 signals and signal actions from the parent process.)
235 @end itemize
236
237
238 @comment unistd.h
239 @comment BSD
240 @deftypefun pid_t vfork (void)
241 The @code{vfork} function is similar to @code{fork} but on systems it
242 is more efficient; however, there are restrictions you must follow to
243 use it safely.
244
245 While @code{fork} makes a complete copy of the calling process's
246 address space and allows both the parent and child to execute
247 independently, @code{vfork} does not make this copy.  Instead, the
248 child process created with @code{vfork} shares its parent's address
249 space until it calls exits or one of the @code{exec} functions.  In the
250 meantime, the parent process suspends execution.
251
252 You must be very careful not to allow the child process created with
253 @code{vfork} to modify any global data or even local variables shared
254 with the parent.  Furthermore, the child process cannot return from (or
255 do a long jump out of) the function that called @code{vfork}!  This
256 would leave the parent process's control information very confused.  If
257 in doubt, use @code{fork} instead.
258
259 Some operating systems don't really implement @code{vfork}.  The GNU C
260 library permits you to use @code{vfork} on all systems, but actually
261 executes @code{fork} if @code{vfork} isn't available.  If you follow
262 the proper precautions for using @code{vfork}, your program will still
263 work even if the system uses @code{fork} instead.
264 @end deftypefun
265
266 @node Executing a File
267 @section Executing a File
268 @cindex executing a file
269 @cindex @code{exec} functions
270
271 This section describes the @code{exec} family of functions, for executing
272 a file as a process image.  You can use these functions to make a child
273 process execute a new program after it has been forked.
274
275 @pindex unistd.h
276 The functions in this family differ in how you specify the arguments,
277 but otherwise they all do the same thing.  They are declared in the
278 header file @file{unistd.h}.
279
280 @comment unistd.h
281 @comment POSIX.1
282 @deftypefun int execv (const char *@var{filename}, char *const @var{argv}@t{[]})
283 The @code{execv} function executes the file named by @var{filename} as a
284 new process image.
285
286 The @var{argv} argument is an array of null-terminated strings that is
287 used to provide a value for the @code{argv} argument to the @code{main}
288 function of the program to be executed.  The last element of this array
289 must be a null pointer.  By convention, the first element of this array
290 is the file name of the program sans directory names.  @xref{Program
291 Arguments}, for full details on how programs can access these arguments.
292
293 The environment for the new process image is taken from the
294 @code{environ} variable of the current process image; see
295 @ref{Environment Variables}, for information about environments.
296 @end deftypefun
297
298 @comment unistd.h
299 @comment POSIX.1
300 @deftypefun int execl (const char *@var{filename}, const char *@var{arg0}, @dots{})
301 This is similar to @code{execv}, but the @var{argv} strings are
302 specified individually instead of as an array.  A null pointer must be
303 passed as the last such argument.
304 @end deftypefun
305
306 @comment unistd.h
307 @comment POSIX.1
308 @deftypefun int execve (const char *@var{filename}, char *const @var{argv}@t{[]}, char *const @var{env}@t{[]})
309 This is similar to @code{execv}, but permits you to specify the environment
310 for the new program explicitly as the @var{env} argument.  This should
311 be an array of strings in the same format as for the @code{environ}
312 variable; see @ref{Environment Access}.
313 @end deftypefun
314
315 @comment unistd.h
316 @comment POSIX.1
317 @deftypefun int execle (const char *@var{filename}, const char *@var{arg0}, char *const @var{env}@t{[]}, @dots{})
318 This is similar to @code{execl}, but permits you to specify the
319 environment for the new program explicitly.  The environment argument is
320 passed following the null pointer that marks the last @var{argv}
321 argument, and should be an array of strings in the same format as for
322 the @code{environ} variable.
323 @end deftypefun
324
325 @comment unistd.h
326 @comment POSIX.1
327 @deftypefun int execvp (const char *@var{filename}, char *const @var{argv}@t{[]})
328 The @code{execvp} function is similar to @code{execv}, except that it
329 searches the directories listed in the @code{PATH} environment variable
330 (@pxref{Standard Environment}) to find the full file name of a
331 file from @var{filename} if @var{filename} does not contain a slash.
332
333 This function is useful for executing system utility programs, because
334 it looks for them in the places that the user has chosen.  Shells use it
335 to run the commands that users type.
336 @end deftypefun
337
338 @comment unistd.h
339 @comment POSIX.1
340 @deftypefun int execlp (const char *@var{filename}, const char *@var{arg0}, @dots{})
341 This function is like @code{execl}, except that it performs the same
342 file name searching as the @code{execvp} function.
343 @end deftypefun
344
345 The size of the argument list and environment list taken together must
346 not be greater than @code{ARG_MAX} bytes.  @xref{General Limits}.  In
347 the GNU system, the size (which compares against @code{ARG_MAX})
348 includes, for each string, the number of characters in the string, plus
349 the size of a @code{char *}, plus one, rounded up to a multiple of the
350 size of a @code{char *}.  Other systems may have somewhat different
351 rules for counting.
352
353 These functions normally don't return, since execution of a new program
354 causes the currently executing program to go away completely.  A value
355 of @code{-1} is returned in the event of a failure.  In addition to the
356 usual file name errors (@pxref{File Name Errors}), the following
357 @code{errno} error conditions are defined for these functions:
358
359 @table @code
360 @item E2BIG
361 The combined size of the new program's argument list and environment
362 list is larger than @code{ARG_MAX} bytes.  The GNU system has no
363 specific limit on the argument list size, so this error code cannot
364 result, but you may get @code{ENOMEM} instead if the arguments are too
365 big for available memory.
366
367 @item ENOEXEC
368 The specified file can't be executed because it isn't in the right format.
369
370 @item ENOMEM
371 Executing the specified file requires more storage than is available.
372 @end table
373
374 If execution of the new file succeeds, it updates the access time field
375 of the file as if the file had been read.  @xref{File Times}, for more
376 details about access times of files.
377
378 The point at which the file is closed again is not specified, but
379 is at some point before the process exits or before another process
380 image is executed.
381
382 Executing a new process image completely changes the contents of memory,
383 copying only the argument and environment strings to new locations.  But
384 many other attributes of the process are unchanged:
385
386 @itemize @bullet
387 @item
388 The process ID and the parent process ID.  @xref{Process Creation Concepts}.
389
390 @item
391 Session and process group membership.  @xref{Concepts of Job Control}.
392
393 @item
394 Real user ID and group ID, and supplementary group IDs.  @xref{Process
395 Persona}.
396
397 @item
398 Pending alarms.  @xref{Setting an Alarm}.
399
400 @item
401 Current working directory and root directory.  @xref{Working
402 Directory}.  In the GNU system, the root directory is not copied when
403 executing a setuid program; instead the system default root directory
404 is used for the new program.
405
406 @item
407 File mode creation mask.  @xref{Setting Permissions}.
408
409 @item
410 Process signal mask; see @ref{Process Signal Mask}.
411
412 @item
413 Pending signals; see @ref{Blocking Signals}.
414
415 @item
416 Elapsed processor time associated with the process; see @ref{Processor Time}.
417 @end itemize
418
419 If the set-user-ID and set-group-ID mode bits of the process image file
420 are set, this affects the effective user ID and effective group ID
421 (respectively) of the process.  These concepts are discussed in detail
422 in @ref{Process Persona}.
423
424 Signals that are set to be ignored in the existing process image are
425 also set to be ignored in the new process image.  All other signals are
426 set to the default action in the new process image.  For more
427 information about signals, see @ref{Signal Handling}.
428
429 File descriptors open in the existing process image remain open in the
430 new process image, unless they have the @code{FD_CLOEXEC}
431 (close-on-exec) flag set.  The files that remain open inherit all
432 attributes of the open file description from the existing process image,
433 including file locks.  File descriptors are discussed in @ref{Low-Level I/O}.
434
435 Streams, by contrast, cannot survive through @code{exec} functions,
436 because they are located in the memory of the process itself.  The new
437 process image has no streams except those it creates afresh.  Each of
438 the streams in the pre-@code{exec} process image has a descriptor inside
439 it, and these descriptors do survive through @code{exec} (provided that
440 they do not have @code{FD_CLOEXEC} set).  The new process image can
441 reconnect these to new streams using @code{fdopen} (@pxref{Descriptors
442 and Streams}).
443
444 @node Process Completion
445 @section Process Completion
446 @cindex process completion
447 @cindex waiting for completion of child process
448 @cindex testing exit status of child process
449
450 The functions described in this section are used to wait for a child
451 process to terminate or stop, and determine its status.  These functions
452 are declared in the header file @file{sys/wait.h}.
453 @pindex sys/wait.h
454
455 @comment sys/wait.h
456 @comment POSIX.1
457 @deftypefun pid_t waitpid (pid_t @var{pid}, int *@var{status-ptr}, int @var{options})
458 The @code{waitpid} function is used to request status information from a
459 child process whose process ID is @var{pid}.  Normally, the calling
460 process is suspended until the child process makes status information
461 available by terminating.
462
463 Other values for the @var{pid} argument have special interpretations.  A
464 value of @code{-1} or @code{WAIT_ANY} requests status information for
465 any child process; a value of @code{0} or @code{WAIT_MYPGRP} requests
466 information for any child process in the same process group as the
467 calling process; and any other negative value @minus{} @var{pgid}
468 requests information for any child process whose process group ID is
469 @var{pgid}.
470
471 If status information for a child process is available immediately, this
472 function returns immediately without waiting.  If more than one eligible
473 child process has status information available, one of them is chosen
474 randomly, and its status is returned immediately.  To get the status
475 from the other eligible child processes, you need to call @code{waitpid}
476 again.
477
478 The @var{options} argument is a bit mask.  Its value should be the
479 bitwise OR (that is, the @samp{|} operator) of zero or more of the
480 @code{WNOHANG} and @code{WUNTRACED} flags.  You can use the
481 @code{WNOHANG} flag to indicate that the parent process shouldn't wait;
482 and the @code{WUNTRACED} flag to request status information from stopped
483 processes as well as processes that have terminated.
484
485 The status information from the child process is stored in the object
486 that @var{status-ptr} points to, unless @var{status-ptr} is a null pointer.
487
488 This function is a cancelation point in multi-threaded programs.  This
489 is a problem if the thread allocates some resources (like memory, file
490 descriptors, semaphores or whatever) at the time @code{waitpid} is
491 called.  If the thread gets canceled these resources stay allocated
492 until the program ends.  To avoid this calls to @code{waitpid} should be
493 protected using cancelation handlers.
494 @c ref pthread_cleanup_push / pthread_cleanup_pop
495
496 The return value is normally the process ID of the child process whose
497 status is reported.  If the @code{WNOHANG} option was specified and no
498 child process is waiting to be noticed, the value is zero.  A value of
499 @code{-1} is returned in case of error.  The following @code{errno}
500 error conditions are defined for this function:
501
502 @table @code
503 @item EINTR
504 The function was interrupted by delivery of a signal to the calling
505 process.  @xref{Interrupted Primitives}.
506
507 @item ECHILD
508 There are no child processes to wait for, or the specified @var{pid}
509 is not a child of the calling process.
510
511 @item EINVAL
512 An invalid value was provided for the @var{options} argument.
513 @end table
514 @end deftypefun
515
516 These symbolic constants are defined as values for the @var{pid} argument
517 to the @code{waitpid} function.
518
519 @comment Extra blank lines make it look better.
520 @table @code
521 @item WAIT_ANY
522
523 This constant macro (whose value is @code{-1}) specifies that
524 @code{waitpid} should return status information about any child process.
525
526
527 @item WAIT_MYPGRP
528 This constant (with value @code{0}) specifies that @code{waitpid} should
529 return status information about any child process in the same process
530 group as the calling process.
531 @end table
532
533 These symbolic constants are defined as flags for the @var{options}
534 argument to the @code{waitpid} function.  You can bitwise-OR the flags
535 together to obtain a value to use as the argument.
536
537 @table @code
538 @item WNOHANG
539
540 This flag specifies that @code{waitpid} should return immediately
541 instead of waiting, if there is no child process ready to be noticed.
542
543 @item WUNTRACED
544
545 This flag specifies that @code{waitpid} should report the status of any
546 child processes that have been stopped as well as those that have
547 terminated.
548 @end table
549
550 @comment sys/wait.h
551 @comment POSIX.1
552 @deftypefun pid_t wait (int *@var{status-ptr})
553 This is a simplified version of @code{waitpid}, and is used to wait
554 until any one child process terminates.  The call:
555
556 @smallexample
557 wait (&status)
558 @end smallexample
559
560 @noindent
561 is exactly equivalent to:
562
563 @smallexample
564 waitpid (-1, &status, 0)
565 @end smallexample
566
567 This function is a cancelation point in multi-threaded programs.  This
568 is a problem if the thread allocates some resources (like memory, file
569 descriptors, semaphores or whatever) at the time @code{wait} is
570 called.  If the thread gets canceled these resources stay allocated
571 until the program ends.  To avoid this calls to @code{wait} should be
572 protected using cancelation handlers.
573 @c ref pthread_cleanup_push / pthread_cleanup_pop
574 @end deftypefun
575
576 @comment sys/wait.h
577 @comment BSD
578 @deftypefun pid_t wait4 (pid_t @var{pid}, int *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
579 If @var{usage} is a null pointer, @code{wait4} is equivalent to
580 @code{waitpid (@var{pid}, @var{status-ptr}, @var{options})}.
581
582 If @var{usage} is not null, @code{wait4} stores usage figures for the
583 child process in @code{*@var{rusage}} (but only if the child has
584 terminated, not if it has stopped).  @xref{Resource Usage}.
585
586 This function is a BSD extension.
587 @end deftypefun
588
589 Here's an example of how to use @code{waitpid} to get the status from
590 all child processes that have terminated, without ever waiting.  This
591 function is designed to be a handler for @code{SIGCHLD}, the signal that
592 indicates that at least one child process has terminated.
593
594 @smallexample
595 @group
596 void
597 sigchld_handler (int signum)
598 @{
599   int pid;
600   int status;
601   while (1)
602     @{
603       pid = waitpid (WAIT_ANY, &status, WNOHANG);
604       if (pid < 0)
605         @{
606           perror ("waitpid");
607           break;
608         @}
609       if (pid == 0)
610         break;
611       notice_termination (pid, status);
612     @}
613 @}
614 @end group
615 @end smallexample
616
617 @node Process Completion Status
618 @section Process Completion Status
619
620 If the exit status value (@pxref{Program Termination}) of the child
621 process is zero, then the status value reported by @code{waitpid} or
622 @code{wait} is also zero.  You can test for other kinds of information
623 encoded in the returned status value using the following macros.
624 These macros are defined in the header file @file{sys/wait.h}.
625 @pindex sys/wait.h
626
627 @comment sys/wait.h
628 @comment POSIX.1
629 @deftypefn Macro int WIFEXITED (int @var{status})
630 This macro returns a nonzero value if the child process terminated
631 normally with @code{exit} or @code{_exit}.
632 @end deftypefn
633
634 @comment sys/wait.h
635 @comment POSIX.1
636 @deftypefn Macro int WEXITSTATUS (int @var{status})
637 If @code{WIFEXITED} is true of @var{status}, this macro returns the
638 low-order 8 bits of the exit status value from the child process.
639 @xref{Exit Status}.
640 @end deftypefn
641
642 @comment sys/wait.h
643 @comment POSIX.1
644 @deftypefn Macro int WIFSIGNALED (int @var{status})
645 This macro returns a nonzero value if the child process terminated
646 because it received a signal that was not handled.
647 @xref{Signal Handling}.
648 @end deftypefn
649
650 @comment sys/wait.h
651 @comment POSIX.1
652 @deftypefn Macro int WTERMSIG (int @var{status})
653 If @code{WIFSIGNALED} is true of @var{status}, this macro returns the
654 signal number of the signal that terminated the child process.
655 @end deftypefn
656
657 @comment sys/wait.h
658 @comment BSD
659 @deftypefn Macro int WCOREDUMP (int @var{status})
660 This macro returns a nonzero value if the child process terminated
661 and produced a core dump.
662 @end deftypefn
663
664 @comment sys/wait.h
665 @comment POSIX.1
666 @deftypefn Macro int WIFSTOPPED (int @var{status})
667 This macro returns a nonzero value if the child process is stopped.
668 @end deftypefn
669
670 @comment sys/wait.h
671 @comment POSIX.1
672 @deftypefn Macro int WSTOPSIG (int @var{status})
673 If @code{WIFSTOPPED} is true of @var{status}, this macro returns the
674 signal number of the signal that caused the child process to stop.
675 @end deftypefn
676
677
678 @node BSD Wait Functions
679 @section BSD Process Wait Functions
680
681 The GNU library also provides these related facilities for compatibility
682 with BSD Unix.  BSD uses the @code{union wait} data type to represent
683 status values rather than an @code{int}.  The two representations are
684 actually interchangeable; they describe the same bit patterns.  The GNU
685 C Library defines macros such as @code{WEXITSTATUS} so that they will
686 work on either kind of object, and the @code{wait} function is defined
687 to accept either type of pointer as its @var{status-ptr} argument.
688
689 These functions are declared in @file{sys/wait.h}.
690 @pindex sys/wait.h
691
692 @comment sys/wait.h
693 @comment BSD
694 @deftp {Data Type} {union wait}
695 This data type represents program termination status values.  It has
696 the following members:
697
698 @table @code
699 @item int w_termsig
700 The value of this member is the same as the result of the
701 @code{WTERMSIG} macro.
702
703 @item int w_coredump
704 The value of this member is the same as the result of the
705 @code{WCOREDUMP} macro.
706
707 @item int w_retcode
708 The value of this member is the same as the result of the
709 @code{WEXITSTATUS} macro.
710
711 @item int w_stopsig
712 The value of this member is the same as the result of the
713 @code{WSTOPSIG} macro.
714 @end table
715
716 Instead of accessing these members directly, you should use the
717 equivalent macros.
718 @end deftp
719
720 The @code{wait3} function is the predecessor to @code{wait4}, which is
721 more flexible.  @code{wait3} is now obsolete.
722
723 @comment sys/wait.h
724 @comment BSD
725 @deftypefun pid_t wait3 (union wait *@var{status-ptr}, int @var{options}, struct rusage *@var{usage})
726 If @var{usage} is a null pointer, @code{wait3} is equivalent to
727 @code{waitpid (-1, @var{status-ptr}, @var{options})}.
728
729 If @var{usage} is not null, @code{wait3} stores usage figures for the
730 child process in @code{*@var{rusage}} (but only if the child has
731 terminated, not if it has stopped).  @xref{Resource Usage}.
732 @end deftypefun
733
734 @node Process Creation Example
735 @section Process Creation Example
736
737 Here is an example program showing how you might write a function
738 similar to the built-in @code{system}.  It executes its @var{command}
739 argument using the equivalent of @samp{sh -c @var{command}}.
740
741 @smallexample
742 #include <stddef.h>
743 #include <stdlib.h>
744 #include <unistd.h>
745 #include <sys/types.h>
746 #include <sys/wait.h>
747
748 /* @r{Execute the command using this shell program.}  */
749 #define SHELL "/bin/sh"
750
751 @group
752 int
753 my_system (const char *command)
754 @{
755   int status;
756   pid_t pid;
757 @end group
758
759   pid = fork ();
760   if (pid == 0)
761     @{
762       /* @r{This is the child process.  Execute the shell command.} */
763       execl (SHELL, SHELL, "-c", command, NULL);
764       _exit (EXIT_FAILURE);
765     @}
766   else if (pid < 0)
767     /* @r{The fork failed.  Report failure.}  */
768     status = -1;
769   else
770     /* @r{This is the parent process.  Wait for the child to complete.}  */
771     if (waitpid (pid, &status, 0) != pid)
772       status = -1;
773   return status;
774 @}
775 @end smallexample
776
777 @comment Yes, this example has been tested.
778
779 There are a couple of things you should pay attention to in this
780 example.
781
782 Remember that the first @code{argv} argument supplied to the program
783 represents the name of the program being executed.  That is why, in the
784 call to @code{execl}, @code{SHELL} is supplied once to name the program
785 to execute and a second time to supply a value for @code{argv[0]}.
786
787 The @code{execl} call in the child process doesn't return if it is
788 successful.  If it fails, you must do something to make the child
789 process terminate.  Just returning a bad status code with @code{return}
790 would leave two processes running the original program.  Instead, the
791 right behavior is for the child process to report failure to its parent
792 process.
793
794 Call @code{_exit} to accomplish this.  The reason for using @code{_exit}
795 instead of @code{exit} is to avoid flushing fully buffered streams such
796 as @code{stdout}.  The buffers of these streams probably contain data
797 that was copied from the parent process by the @code{fork}, data that
798 will be output eventually by the parent process.  Calling @code{exit} in
799 the child would output the data twice.  @xref{Termination Internals}.