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