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