1 @node Job Control, Name Service Switch, Processes, Top
2 @c %MENU% All about process groups and sessions
9 @dfn{Job control} refers to the protocol for allowing a user to move
10 between multiple @dfn{process groups} (or @dfn{jobs}) within a single
11 @dfn{login session}. The job control facilities are set up so that
12 appropriate behavior for most programs happens automatically and they
13 need not do anything special about job control. So you can probably
14 ignore the material in this chapter unless you are writing a shell or
17 You need to be familiar with concepts relating to process creation
18 (@pxref{Process Creation Concepts}) and signal handling (@pxref{Signal
19 Handling}) in order to understand this material presented in this
23 * Concepts of Job Control:: Jobs can be controlled by a shell.
24 * Job Control is Optional:: Not all POSIX systems support job control.
25 * Controlling Terminal:: How a process gets its controlling terminal.
26 * Access to the Terminal:: How processes share the controlling terminal.
27 * Orphaned Process Groups:: Jobs left after the user logs out.
28 * Implementing a Shell:: What a shell must do to implement job control.
29 * Functions for Job Control:: Functions to control process groups.
32 @node Concepts of Job Control, Job Control is Optional, , Job Control
33 @section Concepts of Job Control
36 The fundamental purpose of an interactive shell is to read
37 commands from the user's terminal and create processes to execute the
38 programs specified by those commands. It can do this using the
39 @code{fork} (@pxref{Creating a Process}) and @code{exec}
40 (@pxref{Executing a File}) functions.
42 A single command may run just one process---but often one command uses
43 several processes. If you use the @samp{|} operator in a shell command,
44 you explicitly request several programs in their own processes. But
45 even if you run just one program, it can use multiple processes
46 internally. For example, a single compilation command such as @samp{cc
47 -c foo.c} typically uses four processes (though normally only two at any
48 given time). If you run @code{make}, its job is to run other programs
49 in separate processes.
51 The processes belonging to a single command are called a @dfn{process
52 group} or @dfn{job}. This is so that you can operate on all of them at
53 once. For example, typing @kbd{C-c} sends the signal @code{SIGINT} to
54 terminate all the processes in the foreground process group.
57 A @dfn{session} is a larger group of processes. Normally all the
58 processes that stem from a single login belong to the same session.
60 Every process belongs to a process group. When a process is created, it
61 becomes a member of the same process group and session as its parent
62 process. You can put it in another process group using the
63 @code{setpgid} function, provided the process group belongs to the same
66 @cindex session leader
67 The only way to put a process in a different session is to make it the
68 initial process of a new session, or a @dfn{session leader}, using the
69 @code{setsid} function. This also puts the session leader into a new
70 process group, and you can't move it out of that process group again.
72 Usually, new sessions are created by the system login program, and the
73 session leader is the process running the user's login shell.
75 @cindex controlling terminal
76 A shell that supports job control must arrange to control which job can
77 use the terminal at any time. Otherwise there might be multiple jobs
78 trying to read from the terminal at once, and confusion about which
79 process should receive the input typed by the user. To prevent this,
80 the shell must cooperate with the terminal driver using the protocol
81 described in this chapter.
83 @cindex foreground job
84 @cindex background job
85 The shell can give unlimited access to the controlling terminal to only
86 one process group at a time. This is called the @dfn{foreground job} on
87 that controlling terminal. Other process groups managed by the shell
88 that are executing without such access to the terminal are called
89 @dfn{background jobs}.
92 If a background job needs to read from its controlling
93 terminal, it is @dfn{stopped} by the terminal driver; if the
94 @code{TOSTOP} mode is set, likewise for writing. The user can stop
95 a foreground job by typing the SUSP character (@pxref{Special
96 Characters}) and a program can stop any job by sending it a
97 @code{SIGSTOP} signal. It's the responsibility of the shell to notice
98 when jobs stop, to notify the user about them, and to provide mechanisms
99 for allowing the user to interactively continue stopped jobs and switch
100 jobs between foreground and background.
102 @xref{Access to the Terminal}, for more information about I/O to the
103 controlling terminal,
105 @node Job Control is Optional, Controlling Terminal, Concepts of Job Control , Job Control
106 @section Job Control is Optional
107 @cindex job control is optional
109 Not all operating systems support job control. The GNU system does
110 support job control, but if you are using the GNU library on some other
111 system, that system may not support job control itself.
113 You can use the @code{_POSIX_JOB_CONTROL} macro to test at compile-time
114 whether the system supports job control. @xref{System Options}.
116 If job control is not supported, then there can be only one process
117 group per session, which behaves as if it were always in the foreground.
118 The functions for creating additional process groups simply fail with
119 the error code @code{ENOSYS}.
121 The macros naming the various job control signals (@pxref{Job Control
122 Signals}) are defined even if job control is not supported. However,
123 the system never generates these signals, and attempts to send a job
124 control signal or examine or specify their actions report errors or do
128 @node Controlling Terminal, Access to the Terminal, Job Control is Optional, Job Control
129 @section Controlling Terminal of a Process
131 One of the attributes of a process is its controlling terminal. Child
132 processes created with @code{fork} inherit the controlling terminal from
133 their parent process. In this way, all the processes in a session
134 inherit the controlling terminal from the session leader. A session
135 leader that has control of a terminal is called the @dfn{controlling
136 process} of that terminal.
138 @cindex controlling process
139 You generally do not need to worry about the exact mechanism used to
140 allocate a controlling terminal to a session, since it is done for you
141 by the system when you log in.
142 @c ??? How does GNU system let a process get a ctl terminal.
144 An individual process disconnects from its controlling terminal when it
145 calls @code{setsid} to become the leader of a new session.
146 @xref{Process Group Functions}.
148 @c !!! explain how it gets a new one (by opening any terminal)
149 @c ??? How you get a controlling terminal is system-dependent.
150 @c We should document how this will work in the GNU system when it is decided.
151 @c What Unix does is not clean and I don't think GNU should use that.
153 @node Access to the Terminal, Orphaned Process Groups, Controlling Terminal, Job Control
154 @section Access to the Controlling Terminal
155 @cindex controlling terminal, access to
157 Processes in the foreground job of a controlling terminal have
158 unrestricted access to that terminal; background processes do not. This
159 section describes in more detail what happens when a process in a
160 background job tries to access its controlling terminal.
162 @cindex @code{SIGTTIN}, from background job
163 When a process in a background job tries to read from its controlling
164 terminal, the process group is usually sent a @code{SIGTTIN} signal.
165 This normally causes all of the processes in that group to stop (unless
166 they handle the signal and don't stop themselves). However, if the
167 reading process is ignoring or blocking this signal, then @code{read}
168 fails with an @code{EIO} error instead.
170 @cindex @code{SIGTTOU}, from background job
171 Similarly, when a process in a background job tries to write to its
172 controlling terminal, the default behavior is to send a @code{SIGTTOU}
173 signal to the process group. However, the behavior is modified by the
174 @code{TOSTOP} bit of the local modes flags (@pxref{Local Modes}). If
175 this bit is not set (which is the default), then writing to the
176 controlling terminal is always permitted without sending a signal.
177 Writing is also permitted if the @code{SIGTTOU} signal is being ignored
178 or blocked by the writing process.
180 Most other terminal operations that a program can do are treated as
181 reading or as writing. (The description of each operation should say
184 For more information about the primitive @code{read} and @code{write}
185 functions, see @ref{I/O Primitives}.
188 @node Orphaned Process Groups, Implementing a Shell, Access to the Terminal, Job Control
189 @section Orphaned Process Groups
190 @cindex orphaned process group
192 When a controlling process terminates, its terminal becomes free and a
193 new session can be established on it. (In fact, another user could log
194 in on the terminal.) This could cause a problem if any processes from
195 the old session are still trying to use that terminal.
197 To prevent problems, process groups that continue running even after the
198 session leader has terminated are marked as @dfn{orphaned process
201 When a process group becomes an orphan, its processes are sent a
202 @code{SIGHUP} signal. Ordinarily, this causes the processes to
203 terminate. However, if a program ignores this signal or establishes a
204 handler for it (@pxref{Signal Handling}), it can continue running as in
205 the orphan process group even after its controlling process terminates;
206 but it still cannot access the terminal any more.
208 @node Implementing a Shell, Functions for Job Control, Orphaned Process Groups, Job Control
209 @section Implementing a Job Control Shell
211 This section describes what a shell must do to implement job control, by
212 presenting an extensive sample program to illustrate the concepts
218 @ref{Data Structures}, introduces the example and presents
219 its primary data structures.
222 @ref{Initializing the Shell}, discusses actions which the shell must
223 perform to prepare for job control.
226 @ref{Launching Jobs}, includes information about how to create jobs
230 @ref{Foreground and Background}, discusses what the shell should
231 do differently when launching a job in the foreground as opposed to
235 @ref{Stopped and Terminated Jobs}, discusses reporting of job status
239 @ref{Continuing Stopped Jobs}, tells you how to continue jobs that
243 @ref{Missing Pieces}, discusses other parts of the shell.
248 * Data Structures:: Introduction to the sample shell.
249 * Initializing the Shell:: What the shell must do to take
250 responsibility for job control.
251 * Launching Jobs:: Creating jobs to execute commands.
252 * Foreground and Background:: Putting a job in foreground of background.
253 * Stopped and Terminated Jobs:: Reporting job status.
254 * Continuing Stopped Jobs:: How to continue a stopped job in
255 the foreground or background.
256 * Missing Pieces:: Other parts of the shell.
259 @node Data Structures, Initializing the Shell, , Implementing a Shell
260 @subsection Data Structures for the Shell
262 All of the program examples included in this chapter are part of
263 a simple shell program. This section presents data structures
264 and utility functions which are used throughout the example.
266 The sample shell deals mainly with two data structures. The
267 @code{job} type contains information about a job, which is a
268 set of subprocesses linked together with pipes. The @code{process} type
269 holds information about a single subprocess. Here are the relevant
270 data structure declarations:
274 /* @r{A process is a single process.} */
275 typedef struct process
277 struct process *next; /* @r{next process in pipeline} */
278 char **argv; /* @r{for exec} */
279 pid_t pid; /* @r{process ID} */
280 char completed; /* @r{true if process has completed} */
281 char stopped; /* @r{true if process has stopped} */
282 int status; /* @r{reported status value} */
287 /* @r{A job is a pipeline of processes.} */
290 struct job *next; /* @r{next active job} */
291 char *command; /* @r{command line, used for messages} */
292 process *first_process; /* @r{list of processes in this job} */
293 pid_t pgid; /* @r{process group ID} */
294 char notified; /* @r{true if user told about stopped job} */
295 struct termios tmodes; /* @r{saved terminal modes} */
296 int stdin, stdout, stderr; /* @r{standard i/o channels} */
299 /* @r{The active jobs are linked into a list. This is its head.} */
300 job *first_job = NULL;
304 Here are some utility functions that are used for operating on @code{job}
309 /* @r{Find the active job with the indicated @var{pgid}.} */
311 find_job (pid_t pgid)
315 for (j = first_job; j; j = j->next)
323 /* @r{Return true if all processes in the job have stopped or completed.} */
325 job_is_stopped (job *j)
329 for (p = j->first_process; p; p = p->next)
330 if (!p->completed && !p->stopped)
337 /* @r{Return true if all processes in the job have completed.} */
339 job_is_completed (job *j)
343 for (p = j->first_process; p; p = p->next)
352 @node Initializing the Shell, Launching Jobs, Data Structures, Implementing a Shell
353 @subsection Initializing the Shell
354 @cindex job control, enabling
357 When a shell program that normally performs job control is started, it
358 has to be careful in case it has been invoked from another shell that is
359 already doing its own job control.
361 A subshell that runs interactively has to ensure that it has been placed
362 in the foreground by its parent shell before it can enable job control
363 itself. It does this by getting its initial process group ID with the
364 @code{getpgrp} function, and comparing it to the process group ID of the
365 current foreground job associated with its controlling terminal (which
366 can be retrieved using the @code{tcgetpgrp} function).
368 If the subshell is not running as a foreground job, it must stop itself
369 by sending a @code{SIGTTIN} signal to its own process group. It may not
370 arbitrarily put itself into the foreground; it must wait for the user to
371 tell the parent shell to do this. If the subshell is continued again,
372 it should repeat the check and stop itself again if it is still not in
375 @cindex job control, enabling
376 Once the subshell has been placed into the foreground by its parent
377 shell, it can enable its own job control. It does this by calling
378 @code{setpgid} to put itself into its own process group, and then
379 calling @code{tcsetpgrp} to place this process group into the
382 When a shell enables job control, it should set itself to ignore all the
383 job control stop signals so that it doesn't accidentally stop itself.
384 You can do this by setting the action for all the stop signals to
387 A subshell that runs non-interactively cannot and should not support job
388 control. It must leave all processes it creates in the same process
389 group as the shell itself; this allows the non-interactive shell and its
390 child processes to be treated as a single job by the parent shell. This
391 is easy to do---just don't use any of the job control primitives---but
392 you must remember to make the shell do it.
395 Here is the initialization code for the sample shell that shows how to
399 /* @r{Keep track of attributes of the shell.} */
401 #include <sys/types.h>
406 struct termios shell_tmodes;
408 int shell_is_interactive;
411 /* @r{Make sure the shell is running interactively as the foreground job}
412 @r{before proceeding.} */
418 /* @r{See if we are running interactively.} */
419 shell_terminal = STDIN_FILENO;
420 shell_is_interactive = isatty (shell_terminal);
422 if (shell_is_interactive)
424 /* @r{Loop until we are in the foreground.} */
425 while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))
426 kill (- shell_pgid, SIGTTIN);
428 /* @r{Ignore interactive and job-control signals.} */
429 signal (SIGINT, SIG_IGN);
430 signal (SIGQUIT, SIG_IGN);
431 signal (SIGTSTP, SIG_IGN);
432 signal (SIGTTIN, SIG_IGN);
433 signal (SIGTTOU, SIG_IGN);
434 signal (SIGCHLD, SIG_IGN);
436 /* @r{Put ourselves in our own process group.} */
437 shell_pgid = getpid ();
438 if (setpgid (shell_pgid, shell_pgid) < 0)
440 perror ("Couldn't put the shell in its own process group");
444 /* @r{Grab control of the terminal.} */
445 tcsetpgrp (shell_terminal, shell_pgid);
447 /* @r{Save default terminal attributes for shell.} */
448 tcgetattr (shell_terminal, &shell_tmodes);
454 @node Launching Jobs, Foreground and Background, Initializing the Shell, Implementing a Shell
455 @subsection Launching Jobs
456 @cindex launching jobs
458 Once the shell has taken responsibility for performing job control on
459 its controlling terminal, it can launch jobs in response to commands
462 To create the processes in a process group, you use the same @code{fork}
463 and @code{exec} functions described in @ref{Process Creation Concepts}.
464 Since there are multiple child processes involved, though, things are a
465 little more complicated and you must be careful to do things in the
466 right order. Otherwise, nasty race conditions can result.
468 You have two choices for how to structure the tree of parent-child
469 relationships among the processes. You can either make all the
470 processes in the process group be children of the shell process, or you
471 can make one process in group be the ancestor of all the other processes
472 in that group. The sample shell program presented in this chapter uses
473 the first approach because it makes bookkeeping somewhat simpler.
475 @cindex process group leader
476 @cindex process group ID
477 As each process is forked, it should put itself in the new process group
478 by calling @code{setpgid}; see @ref{Process Group Functions}. The first
479 process in the new group becomes its @dfn{process group leader}, and its
480 process ID becomes the @dfn{process group ID} for the group.
482 @cindex race conditions, relating to job control
483 The shell should also call @code{setpgid} to put each of its child
484 processes into the new process group. This is because there is a
485 potential timing problem: each child process must be put in the process
486 group before it begins executing a new program, and the shell depends on
487 having all the child processes in the group before it continues
488 executing. If both the child processes and the shell call
489 @code{setpgid}, this ensures that the right things happen no matter which
490 process gets to it first.
492 If the job is being launched as a foreground job, the new process group
493 also needs to be put into the foreground on the controlling terminal
494 using @code{tcsetpgrp}. Again, this should be done by the shell as well
495 as by each of its child processes, to avoid race conditions.
497 The next thing each child process should do is to reset its signal
500 During initialization, the shell process set itself to ignore job
501 control signals; see @ref{Initializing the Shell}. As a result, any child
502 processes it creates also ignore these signals by inheritance. This is
503 definitely undesirable, so each child process should explicitly set the
504 actions for these signals back to @code{SIG_DFL} just after it is forked.
506 Since shells follow this convention, applications can assume that they
507 inherit the correct handling of these signals from the parent process.
508 But every application has a responsibility not to mess up the handling
509 of stop signals. Applications that disable the normal interpretation of
510 the SUSP character should provide some other mechanism for the user to
511 stop the job. When the user invokes this mechanism, the program should
512 send a @code{SIGTSTP} signal to the process group of the process, not
513 just to the process itself. @xref{Signaling Another Process}.
515 Finally, each child process should call @code{exec} in the normal way.
516 This is also the point at which redirection of the standard input and
517 output channels should be handled. @xref{Duplicating Descriptors},
518 for an explanation of how to do this.
520 Here is the function from the sample shell program that is responsible
521 for launching a program. The function is executed by each child process
522 immediately after it has been forked by the shell, and never returns.
526 launch_process (process *p, pid_t pgid,
527 int infile, int outfile, int errfile,
532 if (shell_is_interactive)
534 /* @r{Put the process into the process group and give the process group}
535 @r{the terminal, if appropriate.}
536 @r{This has to be done both by the shell and in the individual}
537 @r{child processes because of potential race conditions.} */
539 if (pgid == 0) pgid = pid;
542 tcsetpgrp (shell_terminal, pgid);
544 /* @r{Set the handling for job control signals back to the default.} */
545 signal (SIGINT, SIG_DFL);
546 signal (SIGQUIT, SIG_DFL);
547 signal (SIGTSTP, SIG_DFL);
548 signal (SIGTTIN, SIG_DFL);
549 signal (SIGTTOU, SIG_DFL);
550 signal (SIGCHLD, SIG_DFL);
553 /* @r{Set the standard input/output channels of the new process.} */
554 if (infile != STDIN_FILENO)
556 dup2 (infile, STDIN_FILENO);
559 if (outfile != STDOUT_FILENO)
561 dup2 (outfile, STDOUT_FILENO);
564 if (errfile != STDERR_FILENO)
566 dup2 (errfile, STDERR_FILENO);
570 /* @r{Exec the new process. Make sure we exit.} */
571 execvp (p->argv[0], p->argv);
577 If the shell is not running interactively, this function does not do
578 anything with process groups or signals. Remember that a shell not
579 performing job control must keep all of its subprocesses in the same
580 process group as the shell itself.
582 Next, here is the function that actually launches a complete job.
583 After creating the child processes, this function calls some other
584 functions to put the newly created job into the foreground or background;
585 these are discussed in @ref{Foreground and Background}.
589 launch_job (job *j, int foreground)
593 int mypipe[2], infile, outfile;
596 for (p = j->first_process; p; p = p->next)
598 /* @r{Set up pipes, if necessary.} */
601 if (pipe (mypipe) < 0)
611 /* @r{Fork the child processes.} */
614 /* @r{This is the child process.} */
615 launch_process (p, j->pgid, infile,
616 outfile, j->stderr, foreground);
619 /* @r{The fork failed.} */
625 /* @r{This is the parent process.} */
627 if (shell_is_interactive)
631 setpgid (pid, j->pgid);
635 /* @r{Clean up after pipes.} */
636 if (infile != j->stdin)
638 if (outfile != j->stdout)
643 format_job_info (j, "launched");
645 if (!shell_is_interactive)
648 put_job_in_foreground (j, 0);
650 put_job_in_background (j, 0);
655 @node Foreground and Background, Stopped and Terminated Jobs, Launching Jobs, Implementing a Shell
656 @subsection Foreground and Background
658 Now let's consider what actions must be taken by the shell when it
659 launches a job into the foreground, and how this differs from what
660 must be done when a background job is launched.
662 @cindex foreground job, launching
663 When a foreground job is launched, the shell must first give it access
664 to the controlling terminal by calling @code{tcsetpgrp}. Then, the
665 shell should wait for processes in that process group to terminate or
666 stop. This is discussed in more detail in @ref{Stopped and Terminated
669 When all of the processes in the group have either completed or stopped,
670 the shell should regain control of the terminal for its own process
671 group by calling @code{tcsetpgrp} again. Since stop signals caused by
672 I/O from a background process or a SUSP character typed by the user
673 are sent to the process group, normally all the processes in the job
676 The foreground job may have left the terminal in a strange state, so the
677 shell should restore its own saved terminal modes before continuing. In
678 case the job is merely stopped, the shell should first save the current
679 terminal modes so that it can restore them later if the job is
680 continued. The functions for dealing with terminal modes are
681 @code{tcgetattr} and @code{tcsetattr}; these are described in
682 @ref{Terminal Modes}.
684 Here is the sample shell's function for doing all of this.
688 /* @r{Put job @var{j} in the foreground. If @var{cont} is nonzero,}
689 @r{restore the saved terminal modes and send the process group a}
690 @r{@code{SIGCONT} signal to wake it up before we block.} */
693 put_job_in_foreground (job *j, int cont)
695 /* @r{Put the job into the foreground.} */
696 tcsetpgrp (shell_terminal, j->pgid);
700 /* @r{Send the job a continue signal, if necessary.} */
703 tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);
704 if (kill (- j->pgid, SIGCONT) < 0)
705 perror ("kill (SIGCONT)");
709 /* @r{Wait for it to report.} */
712 /* @r{Put the shell back in the foreground.} */
713 tcsetpgrp (shell_terminal, shell_pgid);
716 /* @r{Restore the shell's terminal modes.} */
717 tcgetattr (shell_terminal, &j->tmodes);
718 tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);
723 @cindex background job, launching
724 If the process group is launched as a background job, the shell should
725 remain in the foreground itself and continue to read commands from
728 In the sample shell, there is not much that needs to be done to put
729 a job into the background. Here is the function it uses:
732 /* @r{Put a job in the background. If the cont argument is true, send}
733 @r{the process group a @code{SIGCONT} signal to wake it up.} */
736 put_job_in_background (job *j, int cont)
738 /* @r{Send the job a continue signal, if necessary.} */
740 if (kill (-j->pgid, SIGCONT) < 0)
741 perror ("kill (SIGCONT)");
746 @node Stopped and Terminated Jobs, Continuing Stopped Jobs, Foreground and Background, Implementing a Shell
747 @subsection Stopped and Terminated Jobs
749 @cindex stopped jobs, detecting
750 @cindex terminated jobs, detecting
751 When a foreground process is launched, the shell must block until all of
752 the processes in that job have either terminated or stopped. It can do
753 this by calling the @code{waitpid} function; see @ref{Process
754 Completion}. Use the @code{WUNTRACED} option so that status is reported
755 for processes that stop as well as processes that terminate.
757 The shell must also check on the status of background jobs so that it
758 can report terminated and stopped jobs to the user; this can be done by
759 calling @code{waitpid} with the @code{WNOHANG} option. A good place to
760 put a such a check for terminated and stopped jobs is just before
761 prompting for a new command.
763 @cindex @code{SIGCHLD}, handling of
764 The shell can also receive asynchronous notification that there is
765 status information available for a child process by establishing a
766 handler for @code{SIGCHLD} signals. @xref{Signal Handling}.
768 In the sample shell program, the @code{SIGCHLD} signal is normally
769 ignored. This is to avoid reentrancy problems involving the global data
770 structures the shell manipulates. But at specific times when the shell
771 is not using these data structures---such as when it is waiting for
772 input on the terminal---it makes sense to enable a handler for
773 @code{SIGCHLD}. The same function that is used to do the synchronous
774 status checks (@code{do_job_notification}, in this case) can also be
775 called from within this handler.
777 Here are the parts of the sample shell program that deal with checking
778 the status of jobs and reporting the information to the user.
782 /* @r{Store the status of the process @var{pid} that was returned by waitpid.}
783 @r{Return 0 if all went well, nonzero otherwise.} */
786 mark_process_status (pid_t pid, int status)
795 /* @r{Update the record for the process.} */
796 for (j = first_job; j; j = j->next)
797 for (p = j->first_process; p; p = p->next)
801 if (WIFSTOPPED (status))
806 if (WIFSIGNALED (status))
807 fprintf (stderr, "%d: Terminated by signal %d.\n",
808 (int) pid, WTERMSIG (p->status));
812 fprintf (stderr, "No child process %d.\n", pid);
817 else if (pid == 0 || errno == ECHILD)
818 /* @r{No processes ready to report.} */
821 /* @r{Other weird errors.} */
829 /* @r{Check for processes that have status information available,}
830 @r{without blocking.} */
839 pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);
840 while (!mark_process_status (pid, status));
845 /* @r{Check for processes that have status information available,}
846 @r{blocking until all processes in the given job have reported.} */
849 wait_for_job (job *j)
855 pid = waitpid (WAIT_ANY, &status, WUNTRACED);
856 while (!mark_process_status (pid, status)
857 && !job_is_stopped (j)
858 && !job_is_completed (j));
863 /* @r{Format information about job status for the user to look at.} */
866 format_job_info (job *j, const char *status)
868 fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);
873 /* @r{Notify the user about stopped or terminated jobs.}
874 @r{Delete terminated jobs from the active job list.} */
877 do_job_notification (void)
879 job *j, *jlast, *jnext;
882 /* @r{Update status information for child processes.} */
886 for (j = first_job; j; j = jnext)
890 /* @r{If all processes have completed, tell the user the job has}
891 @r{completed and delete it from the list of active jobs.} */
892 if (job_is_completed (j)) @{
893 format_job_info (j, "completed");
901 /* @r{Notify the user about stopped jobs,}
902 @r{marking them so that we won't do this more than once.} */
903 else if (job_is_stopped (j) && !j->notified) @{
904 format_job_info (j, "stopped");
909 /* @r{Don't say anything about jobs that are still running.} */
917 @node Continuing Stopped Jobs, Missing Pieces, Stopped and Terminated Jobs, Implementing a Shell
918 @subsection Continuing Stopped Jobs
920 @cindex stopped jobs, continuing
921 The shell can continue a stopped job by sending a @code{SIGCONT} signal
922 to its process group. If the job is being continued in the foreground,
923 the shell should first invoke @code{tcsetpgrp} to give the job access to
924 the terminal, and restore the saved terminal settings. After continuing
925 a job in the foreground, the shell should wait for the job to stop or
926 complete, as if the job had just been launched in the foreground.
928 The sample shell program handles both newly created and continued jobs
929 with the same pair of functions, @w{@code{put_job_in_foreground}} and
930 @w{@code{put_job_in_background}}. The definitions of these functions
931 were given in @ref{Foreground and Background}. When continuing a
932 stopped job, a nonzero value is passed as the @var{cont} argument to
933 ensure that the @code{SIGCONT} signal is sent and the terminal modes
934 reset, as appropriate.
936 This leaves only a function for updating the shell's internal bookkeeping
937 about the job being continued:
941 /* @r{Mark a stopped job J as being running again.} */
944 mark_job_as_running (job *j)
948 for (p = j->first_process; p; p = p->next)
955 /* @r{Continue the job J.} */
958 continue_job (job *j, int foreground)
960 mark_job_as_running (j);
962 put_job_in_foreground (j, 1);
964 put_job_in_background (j, 1);
969 @node Missing Pieces, , Continuing Stopped Jobs, Implementing a Shell
970 @subsection The Missing Pieces
972 The code extracts for the sample shell included in this chapter are only
973 a part of the entire shell program. In particular, nothing at all has
974 been said about how @code{job} and @code{program} data structures are
975 allocated and initialized.
977 Most real shells provide a complex user interface that has support for
978 a command language; variables; abbreviations, substitutions, and pattern
979 matching on file names; and the like. All of this is far too complicated
980 to explain here! Instead, we have concentrated on showing how to
981 implement the core process creation and job control functions that can
982 be called from such a shell.
984 Here is a table summarizing the major entry points we have presented:
987 @item void init_shell (void)
988 Initialize the shell's internal state. @xref{Initializing the
991 @item void launch_job (job *@var{j}, int @var{foreground})
992 Launch the job @var{j} as either a foreground or background job.
993 @xref{Launching Jobs}.
995 @item void do_job_notification (void)
996 Check for and report any jobs that have terminated or stopped. Can be
997 called synchronously or within a handler for @code{SIGCHLD} signals.
998 @xref{Stopped and Terminated Jobs}.
1000 @item void continue_job (job *@var{j}, int @var{foreground})
1001 Continue the job @var{j}. @xref{Continuing Stopped Jobs}.
1004 Of course, a real shell would also want to provide other functions for
1005 managing jobs. For example, it would be useful to have commands to list
1006 all active jobs or to send a signal (such as @code{SIGKILL}) to a job.
1009 @node Functions for Job Control, , Implementing a Shell, Job Control
1010 @section Functions for Job Control
1011 @cindex process group functions
1012 @cindex job control functions
1014 This section contains detailed descriptions of the functions relating
1018 * Identifying the Terminal:: Determining the controlling terminal's name.
1019 * Process Group Functions:: Functions for manipulating process groups.
1020 * Terminal Access Functions:: Functions for controlling terminal access.
1024 @node Identifying the Terminal, Process Group Functions, , Functions for Job Control
1025 @subsection Identifying the Controlling Terminal
1026 @cindex controlling terminal, determining
1028 You can use the @code{ctermid} function to get a file name that you can
1029 use to open the controlling terminal. In the GNU library, it returns
1030 the same string all the time: @code{"/dev/tty"}. That is a special
1031 ``magic'' file name that refers to the controlling terminal of the
1032 current process (if it has one). To find the name of the specific
1033 terminal device, use @code{ttyname}; @pxref{Is It a Terminal}.
1035 The function @code{ctermid} is declared in the header file
1041 @deftypefun {char *} ctermid (char *@var{string})
1042 The @code{ctermid} function returns a string containing the file name of
1043 the controlling terminal for the current process. If @var{string} is
1044 not a null pointer, it should be an array that can hold at least
1045 @code{L_ctermid} characters; the string is returned in this array.
1046 Otherwise, a pointer to a string in a static area is returned, which
1047 might get overwritten on subsequent calls to this function.
1049 An empty string is returned if the file name cannot be determined for
1050 any reason. Even if a file name is returned, access to the file it
1051 represents is not guaranteed.
1056 @deftypevr Macro int L_ctermid
1057 The value of this macro is an integer constant expression that
1058 represents the size of a string large enough to hold the file name
1059 returned by @code{ctermid}.
1062 See also the @code{isatty} and @code{ttyname} functions, in
1063 @ref{Is It a Terminal}.
1066 @node Process Group Functions, Terminal Access Functions, Identifying the Terminal, Functions for Job Control
1067 @subsection Process Group Functions
1069 Here are descriptions of the functions for manipulating process groups.
1070 Your program should include the header files @file{sys/types.h} and
1071 @file{unistd.h} to use these functions.
1077 @deftypefun pid_t setsid (void)
1078 The @code{setsid} function creates a new session. The calling process
1079 becomes the session leader, and is put in a new process group whose
1080 process group ID is the same as the process ID of that process. There
1081 are initially no other processes in the new process group, and no other
1082 process groups in the new session.
1084 This function also makes the calling process have no controlling terminal.
1086 The @code{setsid} function returns the new process group ID of the
1087 calling process if successful. A return value of @code{-1} indicates an
1088 error. The following @code{errno} error conditions are defined for this
1093 The calling process is already a process group leader, or there is
1094 already another process group around that has the same process group ID.
1100 @deftypefun pid_t getsid (pid_t @var{pid})
1102 The @code{getsid} function returns the process group ID of the session
1103 leader of the specified process. If a @var{pid} is @code{0}, the
1104 process group ID of the session leader of the current process is
1107 In case of error @code{-1} is returned and @code{errno} is set. The
1108 following @code{errno} error conditions are defined for this function:
1112 There is no process with the given process ID @var{pid}.
1114 The calling process and the process specified by @var{pid} are in
1115 different sessions, and the implementation doesn't allow to access the
1116 process group ID of the session leader of the process with ID @var{pid}
1117 from the calling process.
1121 The @code{getpgrp} function has two definitions: one derived from BSD
1122 Unix, and one from the POSIX.1 standard. The feature test macros you
1123 have selected (@pxref{Feature Test Macros}) determine which definition
1124 you get. Specifically, you get the BSD version if you define
1125 @code{_BSD_SOURCE}; otherwise, you get the POSIX version if you define
1126 @code{_POSIX_SOURCE} or @code{_GNU_SOURCE}. Programs written for old
1127 BSD systems will not include @file{unistd.h}, which defines
1128 @code{getpgrp} specially under @code{_BSD_SOURCE}. You must link such
1129 programs with the @code{-lbsd-compat} option to get the BSD definition.@refill
1130 @pindex -lbsd-compat
1132 @cindex BSD compatibility library
1136 @deftypefn {POSIX.1 Function} pid_t getpgrp (void)
1137 The POSIX.1 definition of @code{getpgrp} returns the process group ID of
1138 the calling process.
1143 @deftypefn {BSD Function} pid_t getpgrp (pid_t @var{pid})
1144 The BSD definition of @code{getpgrp} returns the process group ID of the
1145 process @var{pid}. You can supply a value of @code{0} for the @var{pid}
1146 argument to get information about the calling process.
1151 @deftypefn {System V Function} int getpgid (pid_t @var{pid})
1153 @code{getpgid} is the same as the BSD function @code{getpgrp}. It
1154 returns the process group ID of the process @var{pid}. You can supply a
1155 value of @code{0} for the @var{pid} argument to get information about
1156 the calling process.
1158 In case of error @code{-1} is returned and @code{errno} is set. The
1159 following @code{errno} error conditions are defined for this function:
1163 There is no process with the given process ID @var{pid}.
1164 The calling process and the process specified by @var{pid} are in
1165 different sessions, and the implementation doesn't allow to access the
1166 process group ID of the process with ID @var{pid} from the calling
1173 @deftypefun int setpgid (pid_t @var{pid}, pid_t @var{pgid})
1174 The @code{setpgid} function puts the process @var{pid} into the process
1175 group @var{pgid}. As a special case, either @var{pid} or @var{pgid} can
1176 be zero to indicate the process ID of the calling process.
1178 This function fails on a system that does not support job control.
1179 @xref{Job Control is Optional}, for more information.
1181 If the operation is successful, @code{setpgid} returns zero. Otherwise
1182 it returns @code{-1}. The following @code{errno} error conditions are
1183 defined for this function:
1187 The child process named by @var{pid} has executed an @code{exec}
1188 function since it was forked.
1191 The value of the @var{pgid} is not valid.
1194 The system doesn't support job control.
1197 The process indicated by the @var{pid} argument is a session leader,
1198 or is not in the same session as the calling process, or the value of
1199 the @var{pgid} argument doesn't match a process group ID in the same
1200 session as the calling process.
1203 The process indicated by the @var{pid} argument is not the calling
1204 process or a child of the calling process.
1210 @deftypefun int setpgrp (pid_t @var{pid}, pid_t @var{pgid})
1211 This is the BSD Unix name for @code{setpgid}. Both functions do exactly
1216 @node Terminal Access Functions, , Process Group Functions, Functions for Job Control
1217 @subsection Functions for Controlling Terminal Access
1219 These are the functions for reading or setting the foreground
1220 process group of a terminal. You should include the header files
1221 @file{sys/types.h} and @file{unistd.h} in your application to use
1226 Although these functions take a file descriptor argument to specify
1227 the terminal device, the foreground job is associated with the terminal
1228 file itself and not a particular open file descriptor.
1232 @deftypefun pid_t tcgetpgrp (int @var{filedes})
1233 This function returns the process group ID of the foreground process
1234 group associated with the terminal open on descriptor @var{filedes}.
1236 If there is no foreground process group, the return value is a number
1237 greater than @code{1} that does not match the process group ID of any
1238 existing process group. This can happen if all of the processes in the
1239 job that was formerly the foreground job have terminated, and no other
1240 job has yet been moved into the foreground.
1242 In case of an error, a value of @code{-1} is returned. The
1243 following @code{errno} error conditions are defined for this function:
1247 The @var{filedes} argument is not a valid file descriptor.
1250 The system doesn't support job control.
1253 The terminal file associated with the @var{filedes} argument isn't the
1254 controlling terminal of the calling process.
1260 @deftypefun int tcsetpgrp (int @var{filedes}, pid_t @var{pgid})
1261 This function is used to set a terminal's foreground process group ID.
1262 The argument @var{filedes} is a descriptor which specifies the terminal;
1263 @var{pgid} specifies the process group. The calling process must be a
1264 member of the same session as @var{pgid} and must have the same
1265 controlling terminal.
1267 For terminal access purposes, this function is treated as output. If it
1268 is called from a background process on its controlling terminal,
1269 normally all processes in the process group are sent a @code{SIGTTOU}
1270 signal. The exception is if the calling process itself is ignoring or
1271 blocking @code{SIGTTOU} signals, in which case the operation is
1272 performed and no signal is sent.
1274 If successful, @code{tcsetpgrp} returns @code{0}. A return value of
1275 @code{-1} indicates an error. The following @code{errno} error
1276 conditions are defined for this function:
1280 The @var{filedes} argument is not a valid file descriptor.
1283 The @var{pgid} argument is not valid.
1286 The system doesn't support job control.
1289 The @var{filedes} isn't the controlling terminal of the calling process.
1292 The @var{pgid} isn't a process group in the same session as the calling
1299 @deftypefun pid_t tcgetsid (int @var{fildes})
1300 This function is used to obtain the process group ID of the session
1301 for which the terminal specified by @var{fildes} is the controlling terminal.
1302 If the call is successful the group ID is returned. Otherwise the
1303 return value is @code{(pid_t) -1} and the global variable @var{errno}
1304 is set to the following value:
1307 The @var{filedes} argument is not a valid file descriptor.
1310 The calling process does not have a controlling terminal, or the file
1311 is not the controlling terminal.