Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / job.texi
1 @node Job Control
2 @chapter Job Control
3
4 @cindex process groups
5 @cindex job control
6 @cindex job
7 @cindex session
8 @dfn{Job control} refers to the protocol for allowing a user to share a
9 terminal between multiple @dfn{process groups} (or @dfn{jobs}) within a
10 single login @dfn{session}.  The job control facilities are set up so
11 that appropriate behavior for most programs normally happens
12 automatically.  You can probably ignore the material in this chapter
13 unless you are writing a shell or login program.
14
15 You need to be familiar with concepts relating to process creation
16 (@pxref{Creating New Processes}), signal handling (@pxref{Signal
17 Handling}) in order to understand this material presented in this
18 chapter.
19
20 @menu
21 * Job Control Concepts::                Introduction and overview.
22 * Job Control is Optional::             Not all POSIX systems support 
23                                          job control.
24 * Controlling Terminal of a Process::   How a process gets its controlling
25                                          terminal.
26 * Access to the Controlling Terminal::  How processes share the controlling
27                                          terminal
28 * Orphaned Process Groups::
29 * Implementing a Job Control Shell::    What a shell must do to implement
30                                          job control.
31 * Job Control Functions::               Detailed specification of the
32                                          functional interface.
33 @end menu
34
35 @node Job Control Concepts
36 @section Job Control Concepts
37
38 @cindex shell
39 The fundamental purpose of an interactive @dfn{shell} is to read
40 commands from the user's terminal and create processes to execute the
41 programs specified by those commands.  It can do this using the
42 @code{fork} (@pxref{Creating a Process}) and @code{exec}
43 (@pxref{Executing a File}) functions.
44
45 Processes are organized into process groups to make it easier for the
46 shell to perform actions such as signaling on all of the processes in
47 the group as a whole.  In a typical shell, a process group corresponds
48 to a set of processes from a single command that are linked together via
49 pipes.  In turn, process groups are organized into sessions.  
50
51 @cindex session leader
52 Every process belongs to a process group.  When a process is created, it
53 becomes a member of the same process group and session as its parent
54 process.  You can change the process group to which a process belongs by
55 using the @code{setpgid} function, but you can't move it into a process
56 group that belongs to another session that way.  The only way to put a
57 process in a different session is to make it the initial process of a
58 new session, or a @dfn{session leader}, using the @code{setsid}
59 function.  This also puts the session leader into a new process group,
60 and you can't move it out of that process group again.
61
62 Usually, new sessions are created by the system login program, and the
63 session leader is the process running the user's default shell.
64
65 @cindex controlling terminal
66 A shell that supports job control must also implement a protocol for
67 allocating its @dfn{controlling terminal} to a particular process group.
68 Without such a protocol, there might be multiple jobs trying to read
69 from the terminal at once, and confusion about which process should
70 receive the input typed by the user.  So, the shell must work
71 cooperatively with the terminal driver to ensure that input and output
72 to the controlling terminal are handled in a reasonable way.
73
74 @cindex foreground job
75 @cindex background job
76 The shell can give unlimited access to the controlling terminal to only
77 one process group at a time.  This is called the @dfn{foreground job} on
78 that controlling terminal.  Other process groups managed by the shell
79 that are executing without such access to the terminal are called
80 @dfn{background jobs}.
81
82 @cindex stopped job
83 If a background job needs to read from or write to its controlling
84 terminal, it is @dfn{stopped} by the terminal driver.  A job can also be
85 stopped by typing the SUSP character (@pxref{Special Characters}) or
86 sending it a @code{SIGSTOP} signal.  It's the responsibility
87 of the shell to check for stopped jobs, notify the user about them, and
88 to provide mechanisms for allowing the user to interactively continue
89 stopped jobs and switch jobs between foreground and background.
90
91 For more information about I/O to the controlling terminal,
92 @pxref{Access to the Controlling Terminal}.
93
94
95 @node Job Control is Optional
96 @section Job Control is Optional
97 @cindex job control is optional
98
99 Not all operating systems support job control.  The GNU system does
100 support job control, but if you are using the GNU library on some other
101 system, that system may not support job control itself.
102
103 You can use the @code{_POSIX_JOB_CONTROL} macro to test at compile-time
104 whether the system supports job control.  @xref{System Parameters}.
105
106 If job control is not supported, then there can be only one process
107 group per session, which behaves as if it were always in the foreground.
108 The functions for creating additional process groups simply fail.
109 The macros naming the various job control signals (@pxref{Job Control
110 Signals}) are defined even if job control is not supported.  However,
111 the system never generates these signals, and attempts to send a job
112 control signal or examine or specify their actions fail.
113
114
115 @node Controlling Terminal of a Process
116 @section Controlling Terminal of a Process
117
118 One of the attributes of a process is its controlling terminal.  Child
119 processes created with @code{fork} inherit the controlling terminal from
120 their parent process.  In this way, all the processes in a session
121 inherit the controlling terminal from the session leader.
122
123 @cindex controlling process
124 A session leader that has control of a terminal is called the
125 @dfn{controlling process} of that terminal.  You generally do not need
126 to worry about the exact mechanism used to allocate a controlling
127 terminal to a session, since it is done for you by the system when you
128 log in.  In the GNU system, a new session gains control of a terminal by
129 opening a terminal device file.  In other systems, a controlling
130 terminal might be assigned to a session in some other way.
131
132 An individual process relinquishes its controlling terminal when it
133 calls @code{setsid} to become the leader of a new session.
134 @xref{Process Group Functions}.
135
136
137 @node Access to the Controlling Terminal
138 @section Access to the Controlling Terminal
139 @cindex controlling terminal, access to
140
141 Processes in the foreground job of a controlling terminal have
142 unrestricted access to that terminal; bacground proesses do not.  This
143 section describes in more details what happens when a process in a
144 background job tries to access its controlling terminal.
145
146 @cindex @code{SIGTTIN}, from background job
147 When a process in a background job tries to read from its controlling
148 terminal, the process group is usually sent a @code{SIGTTIN} signal.
149 This normally causes all of the processes in that group to stop.
150 However, if the reading process is ignoring or blocking this signal,
151 then @code{read} fails with a @code{EIO} error instead.
152
153 @cindex @code{SIGTTOU}, from background job
154 Similarly, when a process in a background job tries to write to its
155 controlling terminal, the default behavior is to send a @code{SIGTTOU} 
156 signal to the process group.  However, the behavior is modified by the
157 @code{TOSTOP} bit of the local modes flags (@pxref{Local Modes}).  If
158 this bit is not set, then writing to the controlling terminal is always
159 permitted without sending a signal.  Writing is also permitted if the
160 @code{SIGTTOU} signal is being ignored or blocked by the writing
161 process.
162
163 For more information about the primitive @code{read} and @code{write}
164 functions, see @ref{I/O Primitives}.
165
166
167 @node Orphaned Process Groups
168 @section Orphaned Process Groups
169 @cindex orphaned process group
170
171 When a controlling process terminates, its terminal becomes free and a
172 new session can be established on it.  This could cause a problem if any
173 processes from the old session are still trying to use that terminal.
174 To prevent such problems, all of the processes in a session are sent a
175 @code{SIGHUP} signal when the session leader terminates.
176
177 Ordinarily, receiving a @code{SIGHUP} signal causes a process to
178 terminate.  However, if you have your program ignore this signal or
179 establish a handler for it (@pxref{Signal Handling}), it can continue
180 running even after its controlling process terminates.  A process group
181 that continues running even after its session leader has terminated is
182 called an @dfn{orphaned process group}.
183
184 Processes in an orphaned process group cannot read from or write to the
185 controlling terminal.  Attempts to do so will fail with an @code{EIO}
186 error.
187
188
189 @node Implementing a Job Control Shell
190 @section Implementing a Job Control Shell
191
192 This section describes what a shell must do to implement job control by
193 presenting an extensive example program to illustrate the concepts
194 involved.
195
196 @iftex
197 @itemize @bullet
198 @item 
199 @ref{Data Structures and Utilities}, introduces the example program
200 and its primary data structures.
201
202 @item
203 @ref{Initializing the Shell}, discusses actions which the shell must
204 perform before taking responsibility for job control.
205
206 @item
207 @ref{Launching Jobs}, includes information about how to create jobs
208 to execute commands.
209
210 @item
211 @ref{Foreground and Background Jobs}, discusses what the shell should
212 do differently when launching jobs in the foreground as opposed to
213 a background job.
214
215 @item
216 @ref{Stopped and Terminated Jobs}, discusses reporting of job status
217 back to the shell.
218
219 @item
220 @ref{Continuing Stopped Jobs}, tells you how to continue jobs that
221 have been stopped.
222
223 @item
224 @ref{The Missing Pieces}, discusses other parts of the shell.
225 @end itemize
226 @end iftex
227
228 @menu
229 * Data Structures and Utilities::       Introduction to the sample shell.
230 * Initializing the Shell::              What the shell must do to take
231                                          responsibility for job control.
232 * Launching Jobs::                      Creating jobs to execute commands.
233 * Foreground and Background Jobs::      What the shell must do after launching
234                                          the job.
235 * Stopped and Terminated Jobs::         Reporting job status.
236 * Continuing Stopped Jobs::             How to continue a stopped job in
237                                          the foreground or background.
238 * The Missing Pieces::                  Other parts of the shell.
239 @end menu
240
241 @node Data Structures and Utilities
242 @subsection Data Structures and Utilities
243
244 All of the program examples included in this chapter are part of
245 a simple shell program.  This section presents the data structures
246 and some utility functions which are used throught the example.
247
248 The sample shell deals with two main kinds of data structures.  The
249 @code{Job} type contains information about a job, which is a
250 set of subprocesses linked together with pipes.  The @code{Process} type
251 holds information about a single subprocess.  Here are the relevant
252 data structure declarations:
253
254 @example
255 /* @r{A Process is a single process.}  */
256
257 typedef struct process @{
258   struct process *next;       /* @r{next process in pipeline} */
259   char **argv;                /* @r{for exec} */
260   pid_t pid;                  /* @r{process ID} */
261   char completed;             /* @r{true if process has completed} */
262   char stopped;               /* @r{true if process has stopped} */
263   int status;                 /* @r{reported status value} */
264 @} Process;
265
266
267 /* @r{A Job is a pipeline of Processs.}  */
268
269 typedef struct job @{
270   struct job *next;           /* @r{next active job} */
271   char *command;              /* @r{command line, used for messages} */
272   Process *first_process;     /* @r{list of processs in this job} */
273   pid_t pgid;                 /* @r{process group ID} */
274   char notified;              /* @r{true if user told about stopped job} */
275   struct termios tmodes;      /* @r{saved terminal modes} */
276   int stdin, stdout, stderr;  /* @r{standard i/o channels} */
277 @} Job;
278
279
280 /* @r{The active jobs are linked into a list.  This is its head.}   */
281
282 Job *first_job = NULL;
283 @end example
284
285 Here are some utility functions that are used for operating on @code{Job}
286 objects.
287
288 @example
289 /* @r{Find the active job with the indicated pgid.}  */
290
291 Job *find_job (pid_t pgid)
292 @{
293   Job *j;
294   
295   for (j = first_job; j; j = j->next)
296     if (j->pgid == pgid)
297       return j;
298   return NULL;
299 @}
300
301
302 /* @r{Return true if all processes in the job have stopped or completed.}  */
303
304 int job_is_stopped (Job *j)
305 @{
306   Process *p;
307   
308   for (p = j->first_process; p; p = p->next)
309     if (!p->completed  && !p->stopped)
310       return 0;
311   return 1;
312 @}
313
314
315 /* @r{Return true if all processes in the job have completed.}  */
316
317 int job_is_completed (Job *j)
318 @{
319   Process *p;
320   
321   for (p = j->first_process; p; p = p->next)
322     if (!p->completed)
323       return 0;
324   return 1;
325 @}
326 @end example
327
328
329 @node Initializing the Shell
330 @subsection Initializing the Shell
331 @cindex job control, enabling
332 @cindex subshell
333
334 When a shell program that normally performs job control is started, it
335 has to be careful in case it has been invoked from another shell that is
336 already doing its own job control.  
337
338 A subshell that runs non-interactively cannot support job control.  It
339 must leave all processes it creates in the same process group as the
340 shell itself; this allows the non-interactive shell and its child
341 processes to be treated as a single job by the parent shell.
342
343 A subshell that runs interactively has to ensure that it has been placed
344 in the foreground by its parent shell before it can enable job control
345 itself.  It does this by getting its initial process group ID with the
346 @code{getpgrp} function, and comparing it to the process group ID of the
347 current foreground job associated with its controlling terminal (which
348 can be retrieved using the @code{tcgetpgrp} function).
349
350 If the subshell is not running as a foreground job, it must stop itself
351 by sending a @code{SIGTTIN} signal to its own process group.  Remember
352 that a job cannot arbitrarily put itself into the foreground; it must
353 wait for the user to tell the shell to do this.  If the job is continued
354 again, it should repeat the check and stop itself again if it is still
355 not in the foreground.
356
357 @cindex job control, enabling
358 Once the subshell has been placed into the foreground by its parent
359 shell, it can enable its own job control.  It does this by calling
360 @code{setpgid} to put itself into its own process group, and then
361 calling @code{tcsetpgrp} to place this process group into the
362 foreground.
363
364 When a shell enables job control, it should set itself to ignore all the
365 job control stop signals so that it doesn't accidentally stop itself.
366 You can do this by setting the action for all the stop signals to
367 @code{SIG_IGN}.
368
369 Here is the initialization code for the sample shell that shows how to
370 do all of this.
371
372 @example
373 /* @r{Keep track of attributes of the shell.}  */
374
375 pid_t shell_pgid;
376 struct termios shell_tmodes;
377 int shell_terminal;
378 int shell_is_interactive;
379
380
381 /* @r{Make sure the shell is running interactively as the foreground job}
382  * @r{before proceeding.}
383  */
384
385 void init_shell (void)
386 @{
387   
388   /* @r{See if we are running interactively.}  */
389   shell_terminal = STDIN_FILENO;
390   shell_is_interactive = isatty (shell_terminal);
391
392   if (shell_is_interactive) @{
393
394     /* @r{Loop until we are in the foreground.}  */
395     while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
396       kill (-shell_pgid, SIGTTIN);
397   
398     /* @r{Ignore interactive and job-control signals.}  */
399     signal (SIGINT, SIG_IGN);
400     signal (SIGQUIT, SIG_IGN);
401     signal (SIGTSTP, SIG_IGN);
402     signal (SIGTTIN, SIG_IGN);
403     signal (SIGTTOU, SIG_IGN);
404     signal (SIGCHLD, SIG_IGN);
405     
406     /* @r{Put ourselves in our own process group.}  */
407     shell_pgid = getpid ();
408     if (setpgid (shell_pgid, shell_pgid) < 0) @{
409       fprintf (stderr, "Couldn't put the shell in its own process group.\n");
410       exit (errno);
411     @}
412     
413     /* @r{Grab control of the terminal.}  */
414     tcsetpgrp (shell_terminal, shell_pgid);
415   
416     /* @r{Save default terminal attributes for shell.}  */
417     tcgetattr (shell_terminal, &shell_tmodes);
418   @}
419 @}
420 @end example
421
422
423 @node Launching Jobs
424 @subsection Launching Jobs
425 @cindex launching jobs
426
427 Once the shell has taken responsibility for performing job control on
428 its controlling terminal, it can launch jobs in response to commands
429 typed by the user.
430
431 To create the processes in a process group, you use the same @code{fork}
432 and @code{exec} functions described in @ref{Creating New Processes}.
433 Since there are multiple child processes involved, though, things are a
434 little more complicated and you need to take extra care to do things in
435 the correct order and coordinate which process is doing what.
436 Otherwise, nasty race conditions can result.
437
438 You can either make all the processes in the process group be children
439 of the shell process, or you can make one process in group be the
440 ancestor of all the other processes in that group.  The sample shell
441 program presented in this chapter uses the first approach because it
442 makes bookkeeping somewhat simpler.
443
444 @cindex process group leader
445 @cindex process group ID
446 As each process is forked, it should put itself in the new process group
447 by calling @code{setpgid}; @pxref{Process Group Functions}.  The first
448 process in the new group becomes its @dfn{process group leader}, and its
449 process ID becomes the @dfn{process group ID} for the group.
450
451 @cindex race conditions, relating to job control
452 The shell should also call @code{setpgid} to put each of its child
453 processes into the new process group.  This is because there is a
454 potential timing problem: each child process must be put in the process
455 group before it begins executing a new program, and the shell depends on
456 having all the child processes in the group before it continues
457 executing.  Having both the child processes and the shell call
458 @code{setpgid} ensures that the right things happen no matter which
459 process gets to it first.
460
461 If the job is being launched as a foreground job, the new process group
462 also needs to be put into the foreground on the controlling terminal
463 using @code{tcsetpgrp}.  Again, this should be done by the shell as well
464 as by each of its child processes, to avoid race conditions.
465
466 The next thing that has to be done by each child process is to reset its
467 signal actions.
468
469 During initialization, the shell process set itself to ignore job
470 control signals; @pxref{Initializing the Shell}.  As a result, any child
471 processes it creates also ignore these signals by inheritance.  This is
472 definitely undesirable, so each child process should explicitly set the
473 actions for these signals back to @code{SIG_DFL} just after it is forked.
474
475 @cindex stop signals, handling of
476 (Applications also have a responsibility not to mess up the handling of
477 stop signals.  In general, an application should assume that it inherits
478 the correct handling of these signals from the shell.  Some applications
479 disable the normal interpretation of the SUSP character; @pxref{Special
480 Characters}.  If you are writing a program that does this, you can make your
481 application be a ``good citizen'' by providing some other mechanism for
482 users to interactively stop the job.  Implementationally, this involves
483 sending a @code{SIGTSTP} signal to the process group of the process, not
484 just to the process itself.)
485
486 Finally, each child process should call @code{exec} in the normal way.
487 This is also the point at which redirection of the standard input and 
488 output channels should be handled.  @xref{Duplicating Descriptors},
489 for an explanation of how to do this.
490
491 Here is the function from the sample shell program that is responsible
492 for launching a program.  The function is executed by each child process
493 immediately after it has been forked by the shell, and never returns.
494
495 @example
496 void launch_process (Process *p, pid_t pgid,
497                      int infile, int outfile, int errfile,
498                      int foreground)
499 @{
500   pid_t pid;
501
502   if (shell_is_interactive) @{
503   
504     /* @r{Put the process into the process group and give the process group}
505      * @r{the terminal, if appropriate.}
506      * @r{This has to be done both by the shell and in the individual}
507      * @r{child processes because of potential race conditions.}
508      */
509     pid = getpid ();
510     if (pgid == 0) pgid = pid;
511     setpgid (pid, pgid);
512     if (foreground)
513       tcsetpgrp (shell_terminal, pgid);
514   
515     /* @r{Set the handling for these signals back to the default.}  */
516     signal (SIGINT, SIG_DFL);
517     signal (SIGQUIT, SIG_DFL);
518     signal (SIGTSTP, SIG_DFL);
519     signal (SIGTTIN, SIG_DFL);
520     signal (SIGTTOU, SIG_DFL);
521     signal (SIGCHLD, SIG_DFL);
522   @}
523
524   /* @r{Set the standard input/output channels of the new process.}  */
525   if (infile != STDIN_FILENO) @{
526     dup2 (infile, STDIN_FILENO);
527     close (infile);
528   @}
529   if (outfile != STDOUT_FILENO) @{
530     dup2 (outfile, STDOUT_FILENO);
531     close (outfile);
532   @}
533   if (errfile != STDERR_FILENO) @{
534     dup2 (errfile, STDERR_FILENO);
535     close (errfile);
536   @}    
537   
538   /* @r{Exec the new process.  Make sure we exit.}  */ 
539   execvp (p->argv[0], p->argv);
540   perror ("exec");
541   exit (errno);
542 @}
543 @end example
544
545 If the shell is not running interactively, this function does not do
546 anything with process groups or signals.  Remember that a shell not
547 performing job control must keep all of its subprocesses in the same
548 process group as the shell itself.
549
550 Next, here is the function that actually launches a complete job.
551 After creating the child processes, this function calls some other
552 functions to put the newly created job into the foreground or background;
553 these are discussed in @ref{Foreground and Background Jobs}.
554
555 @example
556 void launch_job (Job *j, int foreground)
557 @{
558   Process *p;
559   pid_t pid;
560   int mypipe[2], infile, outfile;
561   
562   infile = j->stdin;
563   for (p = j->first_process; p; p = p->next) @{
564     
565     /* @r{Set up pipes, if necessary.}  */
566     if (p->next) @{
567       if (pipe (mypipe) < 0) @{
568         perror ("pipe");
569         exit (errno);
570       @}
571       outfile = mypipe[1];
572     @}
573     else
574       outfile = j->stdout;
575     
576     /* @r{Fork the child processes.}  */
577     pid = fork ();
578     if (pid == 0)
579       /* @r{This is the child process.}  */
580       launch_process (p, j->pgid, infile, outfile, j->stderr, foreground);
581     else if (pid < 0) @{
582       /* @r{The fork failed.}  */
583       perror ("fork");
584       exit (pid);
585     @}
586     else @{
587       /* @r{This is the parent process.}  */
588       p->pid = pid;
589       if (shell_is_interactive) @{
590         if (!j->pgid) j->pgid = pid;
591         setpgid (pid, j->pgid);
592       @}
593     @}
594     
595     /* @r{Clean up after pipes.}  */
596     if (infile != j->stdin)
597       close (infile);
598     if (outfile != j->stdout)
599       close (outfile);
600     infile = mypipe[0];
601   @}
602   
603   format_job_info (j, "launched");
604
605   if (!shell_is_interactive)
606     wait_for_job (j);
607   else if (foreground)
608     put_job_in_foreground (j, 0);
609   else
610     put_job_in_background (j, 0);
611 @}
612 @end example
613
614
615 @node Foreground and Background Jobs
616 @subsection Foreground and Background Jobs
617
618 Now let's consider what actions must be taken by the shell when it
619 launches a job into the foreground, and how this differs from what
620 must be done when a background job is launched.
621
622 @cindex foreground job, launching
623 When a foreground job is launched, the shell must first give it access
624 to the controlling terminal by calling @code{tcsetpgrp}.  Then, the
625 shell should wait for processes in that process group to terminate or
626 stop.  This is discussed in more detail in @ref{Stopped and Terminated
627 Jobs}.
628
629 When all of the processes in the group have either completed or stopped,
630 the shell should regain control of the terminal for its own process
631 group by calling @code{tcsetpgrp} again.  Since stop signals caused by
632 I/O from a background process or a SUSP character typed by the user
633 are sent to the process group, normally all the processes in the job
634 stop together.
635
636 The foreground job may have left the terminal in a strange state, so the
637 shell should restore its own saved terminal modes before continuing.  In
638 case the job is merely been stopped, the shell should first save the
639 current terminal modes so that it can restore them later if the job is
640 continued.  The functions for dealing with terminal modes are
641 @code{tcgetattr} and @code{tcsetattr}; these are described in
642 @ref{Terminal Modes}.
643
644
645 Here is the sample shell's function for doing all of this.
646
647 @example
648 /* @r{Put job `j' in the foreground.  If `cont' is nonzero,}
649  * @r{restore the saved terminal modes and send the process group a}
650  * @r{SIGCONT signal to wake it up before we block.}
651  */
652
653 void put_job_in_foreground (Job *j, int cont)
654 @{
655   /* @r{Put the job into the foreground.}  */
656   tcsetpgrp (shell_terminal, j->pgid);
657
658   /* @r{Send the job a continue signal, if necessary.}  */
659   if (cont) @{
660     tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
661     if (kill (-j->pgid, SIGCONT) < 0)
662       perror ("kill (SIGCONT)");
663   @}
664   
665   /* @r{Wait for it to report.}  */
666   wait_for_job (j);
667     
668   /* @r{Put the shell back in the foreground.}  */
669   tcsetpgrp (shell_terminal, shell_pgid);
670     
671   /* @r{Restore the shell's terminal modes.}  */
672   tcgetattr (shell_terminal, &j->tmodes);
673   tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
674 @}
675 @end example
676
677 @cindex background job, launching
678 If the process group is launched as a background job, the shell should
679 remain in the foreground itself and continue to read commands from
680 the terminal.  
681
682 In the sample shell, there is not much that needs to be done to put
683 a job into the background.  Here is the function it uses:
684
685 @example
686 /* @r{Put a job in the background.  If the cont argument is true, send}
687  * @r{the process group a SIGCONT signal to wake it up.}
688  */
689
690 void put_job_in_background (Job *j, int cont)
691 @{
692   /* @r{Send the job a continue signal, if necessary.}  */
693   if (cont)
694     if (kill (-j->pgid, SIGCONT) < 0)
695       perror ("kill (SIGCONT)");
696 @}
697 @end example
698
699
700 @node Stopped and Terminated Jobs
701 @subsection Stopped and Terminated Jobs
702
703 @cindex stopped jobs, detecting
704 @cindex terminated jobs, detecting
705 When a foreground process is launched, the shell must block until all of
706 the processes in that job have either terminated or stopped.  It can do
707 this by calling the @code{waitpid} function; @pxref{Process Completion}.
708 The @code{WUNTRACED} option should be specified so that status is
709 reported for processes that are stopped as well as processes that have
710 completed.
711
712 The shell must also check on the status of background jobs so that it
713 can report terminated and stopped jobs to the user; this can be done by
714 calling @code{waitpid} with the @code{WNOHANG} option.  A good place to
715 put a such a check for terminated and stopped jobs is just before
716 prompting for a new command.
717
718 @cindex @code{SIGCHLD}, handling of
719 You can also receive asynchronous notification that there is status
720 information available for a child process by establishing a handler for
721 @code{SIGCHLD} signals.  @xref{Signal Handling}.
722
723 In the sample shell program, the @code{SIGCHLD} signal is normally
724 ignored.  This is to avoid reentrancy problems involving the global data
725 structures the shell manipulates.  But at specific times when the shell
726 is not using these data structures --- such as when it is waiting for
727 input on the terminal --- it makes sense to enable a handler for
728 @code{SIGCHLD}.  The same function that is used to do the synchronous
729 status checks (@code{do_job_notification}, in this case) can also be
730 called from within this handler.
731
732 Here are the parts of the sample shell program that deal with checking
733 the status of jobs and reporting the information to the user.
734
735 @example
736 /* @r{Store the status of the process `pid' that was returned by waitpid.}
737  * @r{Return 0 if all went well, nonzero otherwise.}
738  */
739
740 int mark_process_status (pid_t pid, int status)
741 @{
742   Job *j;
743   Process *p;
744
745   if (pid > 0) @{
746     /* @r{Update the record for the process.}  */
747     for (j = first_job; j; j = j->next)
748       for (p = j->first_process; p; p = p->next)
749         if (p->pid == pid) @{
750           p->status = status;
751           if (WIFSTOPPED (status))
752             p->stopped = 1;
753           else @{
754             p->completed = 1;
755             if (WIFSIGNALED (status))
756               fprintf (stderr, "%ld: Terminated by signal %d.\n",
757                        (long)pid, WTERMSIG (p->status));
758           @}
759           return 0;
760          @}
761     fprintf (stderr, "No child process %d.\n", pid);
762     return -1;
763   @}
764   else if (pid == 0 || errno == ECHILD)
765     /* @r{No processes ready to report.}  */
766     return -1;
767   else @{
768     /* @r{Other weird errors.}  */
769     perror ("waitpid");
770     return -1;
771   @}
772 @}
773
774
775 /* @r{Check for processes that have status information available, without}
776  * @r{blocking.}
777  */
778
779 void update_status (void)
780 @{
781   int status;
782   pid_t pid;
783   
784   do @{
785     pid = waitpid (-1, &status, WUNTRACED|WNOHANG);
786   @} while (!mark_process_status (pid, status));
787 @}
788
789
790 /* @r{Check for processes that have status information available, blocking}
791  * @r{until all processes in the given job have reported.}
792  */
793
794 void wait_for_job (Job *j)
795 @{
796   int status;
797   pid_t pid;
798   
799   do @{
800     pid = waitpid (-1, &status, WUNTRACED);
801   @} while (!mark_process_status (pid, status) &&
802            !job_is_stopped (j) &&
803            !job_is_completed (j));
804 @}
805
806
807 /* @r{Format information about job status for the user to look at.}  */
808
809 void format_job_info (Job *j, const char *status)
810 @{
811   fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
812 @}
813
814 /* @r{Notify the user about stopped or terminated jobs.}
815  * @r{Delete terminated jobs from the active job list.}
816  */
817
818 void do_job_notification (void)
819 @{
820   Job *j, *jlast, *jnext;
821   Process *p;
822
823   /* @r{Update status information for child processes.}  */
824   update_status ();
825   
826   jlast = NULL;
827   for (j = first_job; j; j = jnext) @{
828     jnext = j->next;
829     
830     /* @r{If all processes have completed, tell the user the job has}
831      * @r{completed and delete it from the list of active jobs.}
832      */
833     if (job_is_completed (j)) @{
834       format_job_info (j, "completed");
835       if (jlast)
836         jlast->next = jnext;
837       else
838         first_job = jnext;
839       free_job (j);
840     @}
841     
842     /* @r{Notify the user about stopped jobs, marking them so that we won't}
843      * @r{do this more than once.}
844      */
845     else if (job_is_stopped (j) && !j->notified) @{
846       format_job_info (j, "stopped");
847       j->notified = 1;
848       jlast = j;
849     @}
850     
851     /* @r{Don't say anything about jobs that are still running.}  */
852     else
853       jlast = j;
854   @}
855 @}
856 @end example
857
858
859 @node Continuing Stopped Jobs
860 @subsection Continuing Stopped Jobs
861
862 Next, let's consider how the shell implements a mechanism for restarting
863 stopped jobs.
864
865 Jobs can be stopped in several different ways.  When a process in a
866 background job tries to access the terminal, its job is normally stopped
867 by the terminal driver.  Both foreground and background jobs can also be
868 stopped explicitly by sending them a stop signal.  And, the terminal
869 driver stops the current foreground process when the user types the
870 SUSP character (usually @kbd{C-z}); @pxref{Special Characters}.
871
872 @cindex stopped jobs, continuing
873 The shell can continue a stopped job by sending a @code{SIGCONT} signal
874 to its process group.  If the job is being continued in the foreground,
875 the shell should first invoke @code{tcsetgrp} first to give the job
876 access to the terminal, restore the saved terminal settings, and then
877 wait for the job to stop or complete.  This is similar to what must be
878 done when initially launching a foreground job.
879
880 The sample shell program uses the same set of functions ---
881 @code{put_job_in_foreground} and @code{put_job_in_background} --- to
882 handle both newly created and continued jobs.  The definitions of these
883 functions were given in @ref{Foreground and Background Jobs}.  When
884 continuing a stopped job, a nonzero value is passed as the @var{cont}
885 argument to ensure that the @code{SIGCONT} signal is sent and the
886 terminal modes reset, as appropriate.
887
888 This leaves only a function for updating the shell's internal bookkeeping
889 about the job being continued:
890
891 @example
892
893 /* @r{Mark a stopped job `j' as being running again.}  */
894
895 void mark_job_as_running (Job *j)
896 @{
897   Process *p;
898
899   for (p = j->first_process; p; p = p->next)
900     p->stopped = 0;
901   j->notified = 0;
902 @}
903
904
905 /* @r{Continue the job `j'.}  */
906
907 void continue_job (Job *j, int foreground)
908 @{
909   mark_job_as_running (j);
910   if (foreground)
911     put_job_in_foreground (j, 1);
912   else
913     put_job_in_background (j, 1);
914 @}
915 @end example
916
917
918 @node The Missing Pieces
919 @subsection The Missing Pieces
920
921 The code extracts for the sample shell included in this chapter are only
922 a part of the entire shell program.  In particular, nothing at all has
923 been said about how @code{Job} and @code{Program} data structures are
924 allocated and initialized.
925
926 Most real shells provide a complex user interface that has support for
927 a command language; variables; abbreviations, substitutions, and pattern
928 matching on file names; and the like.  All of this is far too complicated
929 to explain here!  Instead, we have concentrated on showing how to 
930 implement the core process creation and job control functions that can
931 be called from such a shell.
932
933 Here is a table summarizing the major entry points we have presented:
934
935 @table @code
936 @item void init_shell (void)
937 Called to initialize the shell's internal state.  @xref{Initializing the
938 Shell}.
939
940 @item void launch_job (Job *@var{j}, int @var{foreground})
941 Launch the job @var{j} as either a foreground or background job.
942 @xref{Launching Jobs}.
943
944 @item void do_job_notification (void)
945 Check for and report any jobs that have terminated or stopped.  Can be
946 called synchronously or within a handler for @code{SIGCHLD} signals.
947 @xref{Stopped and Terminated Jobs}.
948
949 @item void continue_job (Job *@var{j}, int @var{foreground})
950 Continue the job @var{j}.  @xref{Continuing Stopped Jobs}.
951 @end table
952
953 Of course, a real shell would also want to provide other functions for
954 managing jobs.  For example, it would be useful to have commands to list
955 all active jobs or to send a signal (such as @code{SIGKILL}) to a job.
956
957
958 @node Job Control Functions
959 @section Job Control Functions
960 @cindex process group functions
961 @cindex job control functions
962
963 This section contains detailed descriptions of the functions relating
964 to job control.
965
966 @menu
967 * Controlling Terminal Identification:: Determining the controlling terminal.
968 * Process Group Functions::             Functions for manipulating process
969                                          groups.
970 * Foreground Process Group Functions::  How to inquire about and modify the 
971                                          foreground process group of a
972                                          terminal.
973 @end menu
974
975
976 @node Controlling Terminal Identification
977 @subsection Controlling Terminal Identification
978 @cindex controlling terminal, determining
979
980 You can use the @code{ctermid} function to get a file name that
981 corresponds to the controlling terminal for the current process.  This
982 function is declared in the header file @file{stdio.h}.
983 @pindex stdio.h
984
985 @comment stdio.h
986 @comment POSIX.1
987 @deftypefun {char *} ctermid (char *@var{string})
988 The @code{ctermid} function returns a string containing the file name of
989 the controlling terminal for the current process.  If @var{string} is
990 not a null pointer, it should be an array that can hold at least
991 @code{L_ctermid} characters; the string is returned in this array.
992 Otherwise, a pointer to a string in a static area is returned, which
993 might get overwritten on subsequent calls to this function.
994
995 An empty string is returned if the file name cannot be determined for
996 any reason.  Even if a file name is returned, access to the file it
997 represents is not guaranteed.
998 @end deftypefun
999
1000 @comment stdio.h
1001 @comment POSIX.1
1002 @deftypevr Macro int L_ctermid
1003 The value of this macro is an integer constant expression that
1004 represents the size of a string large enough to hold the file name
1005 returned by @code{ctermid}.
1006 @end deftypevr
1007
1008 See also the @code{isatty} and @code{ttyname} functions, in 
1009 @ref{Is It a Terminal}.
1010
1011
1012 @node Process Group Functions
1013 @subsection Process Group Functions
1014
1015 Here are descriptions of the functions for manipulating process groups.
1016 Your program should include the header files @file{sys/types.h} and
1017 @file{unistd.h} to use these functions.
1018 @pindex unistd.h
1019 @pindex sys/types.h
1020
1021 @comment unistd.h
1022 @comment POSIX.1
1023 @deftypefun pid_t setsid (void)
1024 The @code{setsid} function creates a new session.  The calling process
1025 becomes the session leader, and is put in a new process group.  The
1026 process group ID is the same as the process ID of the current process.
1027 There are no other processes in the new process group, and no other
1028 process groups in the new session.
1029
1030 This function also makes the calling process have no controlling terminal.
1031
1032 The @code{setsid} function returns the process group ID of the calling
1033 process if successful.  A return value of @code{-1} indicates an error.
1034 The following @code{errno} error conditions are defined for this function:
1035
1036 @table @code
1037 @item EPERM
1038 The calling process is already a process group leader, or there is
1039 already another process group around that has the same process group ID.
1040 @end table
1041 @end deftypefun
1042
1043 The @code{getpgrp} function has two definitions:  one derived from BSD
1044 Unix, and one from the POSIX.1 standard.  The feature test macros you
1045 have selected (@pxref{Feature Test Macros}) determine which definition
1046 you get.  The default is the POSIX.1 version.
1047
1048 @comment unistd.h
1049 @comment POSIX.1
1050 @deftypefun pid_t getpgrp (void)
1051 This is the POSIX.1 definition of @code{getpgrp}.  It returns
1052 the process group ID of the calling process.
1053 @end deftypefun
1054
1055 @comment unistd.h
1056 @comment BSD
1057 @deftypefun pid_t getpgrp (pid_t @var{pid})
1058 This is the BSD definition of @code{getpgrp}.  It returns the process
1059 group ID of the process @var{pid}.  You can supply a value of @code{0}
1060 for the @code{pid} argument to get information about the calling process.
1061 @end deftypefun
1062
1063 @comment unistd.h
1064 @comment POSIX.1
1065 @deftypefun int setpgid (pid_t @var{pid}, pid_t @var{pgid})
1066 The @code{setpgid} function sets the process group ID of the process
1067 named by @var{pid} to @var{pgid}.  As a special case, both @var{pid}
1068 and @var{pgid} can be zero to indicate the process ID of the calling
1069 process.
1070
1071 This function fails on a system that does not support job control.
1072 @xref{Job Control is Optional}, for more information.
1073
1074 If the operation is successful, @code{setpgid} returns zero.  Otherwise
1075 a value of @code{-1} is returned.  The following @code{errno} error
1076 conditions are defined for this function:
1077
1078 @table @code
1079 @item EACCES
1080 The child process named by @var{pid} has already executed an @code{exec}
1081 function.
1082
1083 @item EINVAL
1084 The value of the @var{pgid} is not valid.
1085
1086 @item ENOSYS
1087 The system doesn't support job control.
1088
1089 @item EPERM
1090 The process indicated by the @var{pid} argument is a session leader,
1091 or is not in the same session as the calling process, or the value of
1092 the @var{pgid} argument doesn't match a process group ID in the same
1093 session as the calling process.
1094
1095 @item ESRCH
1096 The process indicated by the @var{pid} argument is not the calling
1097 process or a child of the calling process.
1098 @end table
1099 @end deftypefun
1100
1101 @comment unistd.h
1102 @comment BSD
1103 @deftypefun int setpgrp (pid_t @var{pid}, pid_t @var{pgid})
1104 This is the BSD Unix name for @code{setpgid}.  Both functions do exactly
1105 the same thing.
1106 @end deftypefun
1107
1108
1109 @node Foreground Process Group Functions
1110 @subsection Foreground Process Group Functions
1111
1112 These are the functions for inquiring about or modifying the foreground
1113 process group of a terminal.  You should include the header files
1114 @file{sys/types.h} and @file{unistd.h} in your application to use
1115 these functions.
1116 @pindex unistd.h
1117 @pindex sys/types.h
1118
1119 Although these functions take a file descriptor argument to specify
1120 the terminal device, the foreground job is associated with the terminal
1121 file itself and not a particular open file descriptor.
1122
1123 @comment unistd.h
1124 @comment POSIX.1
1125 @deftypefun pid_t tcgetpgrp (int @var{filedes})
1126 This function returns the process group ID of the foreground process
1127 group associated with the terminal file with descriptor @var{filedes}.
1128
1129 If there is no foreground process group, the return value is a number
1130 greater than @code{1} that does not match the process group ID of any
1131 existing process group.  This can happen if all of the processes in the
1132 job that was formerly the foreground job have terminated, and not other
1133 job has yet been moved into the foreground.
1134
1135 In case of an error, a value of @code{-1} is returned.  The
1136 following @code{errno} error conditions are defined for this function:
1137
1138 @table @code
1139 @item EBADF
1140 The @var{filedes} argument is not a valid file descriptor.
1141
1142 @item ENOSYS
1143 The system doesn't support job control.
1144
1145 @item ENOTTY
1146 The terminal file associated with the @var{filedes} argument isn't the
1147 controlling terminal of the calling process.
1148 @end table
1149 @end deftypefun
1150
1151 @comment unistd.h
1152 @comment POSIX.1
1153 @deftypefun int tcsetpgrp (int @var{filedes}, pid_t @var{pgid})
1154 This function is used to set the foreground process group ID associated
1155 with the terminal file @var{filedes} to @var{pgid}.  The calling process
1156 must be a member of the same session as @var{pgid} and must have the
1157 same controlling terminal.
1158
1159 If this function is called from a background process on its controlling
1160 terminal, normally all processes in the process group are sent a
1161 @code{SIGTTOU} signal, as if an attempt were being made to write to the
1162 terminal.  The exception is if the calling process itself is ignoring or
1163 blocking @code{SIGTTOU} signals, in which case the operation is
1164 performed and no signal is sent.
1165
1166 If successful, @code{tcsetpgrp} returns @code{0}.  A return value of
1167 @code{-1} indicates an error.  The following @code{errno} error
1168 conditions are defined for this function:
1169
1170 @table @code
1171 @item EBADF
1172 The @var{filedes} argument is not a valid file descriptor.
1173
1174 @item EINVAL
1175 The @var{pgid} argument is not valid.
1176
1177 @item ENOSYS
1178 The system doesn't support job control.
1179
1180 @item ENOTTY
1181 The @var{filedes} isn't the controlling terminal of the calling process.
1182
1183 @item EPERM
1184 The @var{pgid} isn't a process group in the same session as the calling
1185 process.
1186 @end table
1187 @end deftypefun