@node Job Control, Name Service Switch, Inter-Process Communication, Top

@c %MENU% All about process groups and sessions

@chapter Job Control

@cindex process groups

@cindex job control

@cindex job

@cindex session

@dfn{Job control} refers to the protocol for allowing a user to move

between multiple @dfn{process groups} (or @dfn{jobs}) within a single

@dfn{login session}.  The job control facilities are set up so that

appropriate behavior for most programs happens automatically and they

need not do anything special about job control.  So you can probably

ignore the material in this chapter unless you are writing a shell or

login program.

You need to be familiar with concepts relating to process creation

(@pxref{Process Creation Concepts}) and signal handling (@pxref{Signal

Handling}) in order to understand this material presented in this

chapter.

@menu

* Concepts of Job Control::     Jobs can be controlled by a shell.

* Job Control is Optional::     Not all POSIX systems support job control.

* Controlling Terminal::        How a process gets its controlling terminal.

* Access to the Terminal::      How processes share the controlling terminal.

* Orphaned Process Groups::     Jobs left after the user logs out.

* Implementing a Shell::        What a shell must do to implement job control.

* Functions for Job Control::   Functions to control process groups.

@end menu

@node Concepts of Job Control, Job Control is Optional,  , Job Control

@section Concepts of Job Control

@cindex shell

The fundamental purpose of an interactive shell is to read

commands from the user's terminal and create processes to execute the

programs specified by those commands.  It can do this using the

@code{fork} (@pxref{Creating a Process}) and @code{exec}

(@pxref{Executing a File}) functions.

A single command may run just one process---but often one command uses

several processes.  If you use the @samp{|} operator in a shell command,

you explicitly request several programs in their own processes.  But

even if you run just one program, it can use multiple processes

internally.  For example, a single compilation command such as @samp{cc

-c foo.c} typically uses four processes (though normally only two at any

given time).  If you run @code{make}, its job is to run other programs

in separate processes.

The processes belonging to a single command are called a @dfn{process

group} or @dfn{job}.  This is so that you can operate on all of them at

once.  For example, typing @kbd{C-c} sends the signal @code{SIGINT} to

terminate all the processes in the foreground process group.

@cindex session

A @dfn{session} is a larger group of processes.  Normally all the

processes that stem from a single login belong to the same session.

Every process belongs to a process group.  When a process is created, it

becomes a member of the same process group and session as its parent

process.  You can put it in another process group using the

@code{setpgid} function, provided the process group belongs to the same

session.

@cindex session leader

The only way to put a process in a different session is to make it the

initial process of a new session, or a @dfn{session leader}, using the

@code{setsid} function.  This also puts the session leader into a new

process group, and you can't move it out of that process group again.

Usually, new sessions are created by the system login program, and the

session leader is the process running the user's login shell.

@cindex controlling terminal

A shell that supports job control must arrange to control which job can

use the terminal at any time.  Otherwise there might be multiple jobs

trying to read from the terminal at once, and confusion about which

process should receive the input typed by the user.  To prevent this,

the shell must cooperate with the terminal driver using the protocol

described in this chapter.

@cindex foreground job

@cindex background job

The shell can give unlimited access to the controlling terminal to only

one process group at a time.  This is called the @dfn{foreground job} on

that controlling terminal.  Other process groups managed by the shell

that are executing without such access to the terminal are called

@dfn{background jobs}.

@cindex stopped job

If a background job needs to read from its controlling

terminal, it is @dfn{stopped} by the terminal driver; if the

@code{TOSTOP} mode is set, likewise for writing.  The user can stop

a foreground job by typing the SUSP character (@pxref{Special

Characters}) and a program can stop any job by sending it a

@code{SIGSTOP} signal.  It's the responsibility of the shell to notice

when jobs stop, to notify the user about them, and to provide mechanisms

for allowing the user to interactively continue stopped jobs and switch

jobs between foreground and background.

@xref{Access to the Terminal}, for more information about I/O to the

controlling terminal.

@node Job Control is Optional, Controlling Terminal, Concepts of Job Control , Job Control

@section Job Control is Optional

@cindex job control is optional

Not all operating systems support job control.  @gnusystems{} do

support job control, but if you are using @theglibc{} on some other

system, that system may not support job control itself.

You can use the @code{_POSIX_JOB_CONTROL} macro to test at compile-time

whether the system supports job control.  @xref{System Options}.

If job control is not supported, then there can be only one process

group per session, which behaves as if it were always in the foreground.

The functions for creating additional process groups simply fail with

the error code @code{ENOSYS}.

The macros naming the various job control signals (@pxref{Job Control

Signals}) are defined even if job control is not supported.  However,

the system never generates these signals, and attempts to send a job

control signal or examine or specify their actions report errors or do

nothing.

@node Controlling Terminal, Access to the Terminal, Job Control is Optional, Job Control

@section Controlling Terminal of a Process

One of the attributes of a process is its controlling terminal.  Child

processes created with @code{fork} inherit the controlling terminal from

their parent process.  In this way, all the processes in a session

inherit the controlling terminal from the session leader.  A session

leader that has control of a terminal is called the @dfn{controlling

process} of that terminal.

@cindex controlling process

You generally do not need to worry about the exact mechanism used to

allocate a controlling terminal to a session, since it is done for you

by the system when you log in.

@c ??? How does GNU system let a process get a ctl terminal.

An individual process disconnects from its controlling terminal when it

calls @code{setsid} to become the leader of a new session.

@xref{Process Group Functions}.

@c !!! explain how it gets a new one (by opening any terminal)

@c ??? How you get a controlling terminal is system-dependent.

@c We should document how this will work in the GNU system when it is decided.

@c What Unix does is not clean and I don't think GNU should use that.

@node Access to the Terminal, Orphaned Process Groups, Controlling Terminal, Job Control

@section Access to the Controlling Terminal

@cindex controlling terminal, access to

Processes in the foreground job of a controlling terminal have

unrestricted access to that terminal; background processes do not.  This

section describes in more detail what happens when a process in a

background job tries to access its controlling terminal.

@cindex @code{SIGTTIN}, from background job

When a process in a background job tries to read from its controlling

terminal, the process group is usually sent a @code{SIGTTIN} signal.

This normally causes all of the processes in that group to stop (unless

they handle the signal and don't stop themselves).  However, if the

reading process is ignoring or blocking this signal, then @code{read}

fails with an @code{EIO} error instead.

@cindex @code{SIGTTOU}, from background job

Similarly, when a process in a background job tries to write to its

controlling terminal, the default behavior is to send a @code{SIGTTOU}

signal to the process group.  However, the behavior is modified by the

@code{TOSTOP} bit of the local modes flags (@pxref{Local Modes}).  If

this bit is not set (which is the default), then writing to the

controlling terminal is always permitted without sending a signal.

Writing is also permitted if the @code{SIGTTOU} signal is being ignored

or blocked by the writing process.

Most other terminal operations that a program can do are treated as

reading or as writing.  (The description of each operation should say

which.)

For more information about the primitive @code{read} and @code{write}

functions, see @ref{I/O Primitives}.

@node Orphaned Process Groups, Implementing a Shell, Access to the Terminal, Job Control

@section Orphaned Process Groups

@cindex orphaned process group

When a controlling process terminates, its terminal becomes free and a

new session can be established on it.  (In fact, another user could log

in on the terminal.)  This could cause a problem if any processes from

the old session are still trying to use that terminal.

To prevent problems, process groups that continue running even after the

session leader has terminated are marked as @dfn{orphaned process

groups}.

When a process group becomes an orphan, its processes are sent a

@code{SIGHUP} signal.  Ordinarily, this causes the processes to

terminate.  However, if a program ignores this signal or establishes a

handler for it (@pxref{Signal Handling}), it can continue running as in

the orphan process group even after its controlling process terminates;

but it still cannot access the terminal any more.

@node Implementing a Shell, Functions for Job Control, Orphaned Process Groups, Job Control

@section Implementing a Job Control Shell

This section describes what a shell must do to implement job control, by

presenting an extensive sample program to illustrate the concepts

involved.

@iftex

@itemize @bullet

@item

@ref{Data Structures}, introduces the example and presents

its primary data structures.

@item

@ref{Initializing the Shell}, discusses actions which the shell must

perform to prepare for job control.

@item

@ref{Launching Jobs}, includes information about how to create jobs

to execute commands.

@item

@ref{Foreground and Background}, discusses what the shell should

do differently when launching a job in the foreground as opposed to

a background job.

@item

@ref{Stopped and Terminated Jobs}, discusses reporting of job status

back to the shell.

@item

@ref{Continuing Stopped Jobs}, tells you how to continue jobs that

have been stopped.

@item

@ref{Missing Pieces}, discusses other parts of the shell.

@end itemize

@end iftex

@menu

* Data Structures::             Introduction to the sample shell.

* Initializing the Shell::      What the shell must do to take

				 responsibility for job control.

* Launching Jobs::              Creating jobs to execute commands.

* Foreground and Background::   Putting a job in foreground of background.

* Stopped and Terminated Jobs::  Reporting job status.

* Continuing Stopped Jobs::     How to continue a stopped job in

				 the foreground or background.

* Missing Pieces::              Other parts of the shell.

@end menu

@node Data Structures, Initializing the Shell,  , Implementing a Shell

@subsection Data Structures for the Shell

All of the program examples included in this chapter are part of

a simple shell program.  This section presents data structures

and utility functions which are used throughout the example.

The sample shell deals mainly with two data structures.  The

@code{job} type contains information about a job, which is a

set of subprocesses linked together with pipes.  The @code{process} type

holds information about a single subprocess.  Here are the relevant

data structure declarations:

@smallexample

@group

/* @r{A process is a single process.}  */

typedef struct process

@{

  struct process *next;       /* @r{next process in pipeline} */

  char **argv;                /* @r{for exec} */

  pid_t pid;                  /* @r{process ID} */

  char completed;             /* @r{true if process has completed} */

  char stopped;               /* @r{true if process has stopped} */

  int status;                 /* @r{reported status value} */

@} process;

@end group

@group

/* @r{A job is a pipeline of processes.}  */

typedef struct job

@{

  struct job *next;           /* @r{next active job} */

  char *command;              /* @r{command line, used for messages} */

  process *first_process;     /* @r{list of processes in this job} */

  pid_t pgid;                 /* @r{process group ID} */

  char notified;              /* @r{true if user told about stopped job} */

  struct termios tmodes;      /* @r{saved terminal modes} */

  int stdin, stdout, stderr;  /* @r{standard i/o channels} */

@} job;

/* @r{The active jobs are linked into a list.  This is its head.}   */

job *first_job = NULL;

@end group

@end smallexample

Here are some utility functions that are used for operating on @code{job}

objects.

@smallexample

@group

/* @r{Find the active job with the indicated @var{pgid}.}  */

job *

find_job (pid_t pgid)

@{

  job *j;

  for (j = first_job; j; j = j->next)

    if (j->pgid == pgid)

      return j;

  return NULL;

@}

@end group

@group

/* @r{Return true if all processes in the job have stopped or completed.}  */

int

job_is_stopped (job *j)

@{

  process *p;

  for (p = j->first_process; p; p = p->next)

    if (!p->completed && !p->stopped)

      return 0;

  return 1;

@}

@end group

@group

/* @r{Return true if all processes in the job have completed.}  */

int

job_is_completed (job *j)

@{

  process *p;

  for (p = j->first_process; p; p = p->next)

    if (!p->completed)

      return 0;

  return 1;

@}

@end group

@end smallexample

@node Initializing the Shell, Launching Jobs, Data Structures, Implementing a Shell

@subsection Initializing the Shell

@cindex job control, enabling

@cindex subshell

When a shell program that normally performs job control is started, it

has to be careful in case it has been invoked from another shell that is

already doing its own job control.

A subshell that runs interactively has to ensure that it has been placed

in the foreground by its parent shell before it can enable job control

itself.  It does this by getting its initial process group ID with the

@code{getpgrp} function, and comparing it to the process group ID of the

current foreground job associated with its controlling terminal (which

can be retrieved using the @code{tcgetpgrp} function).

If the subshell is not running as a foreground job, it must stop itself

by sending a @code{SIGTTIN} signal to its own process group.  It may not

arbitrarily put itself into the foreground; it must wait for the user to

tell the parent shell to do this.  If the subshell is continued again,

it should repeat the check and stop itself again if it is still not in

the foreground.

@cindex job control, enabling

Once the subshell has been placed into the foreground by its parent

shell, it can enable its own job control.  It does this by calling

@code{setpgid} to put itself into its own process group, and then

calling @code{tcsetpgrp} to place this process group into the

foreground.

When a shell enables job control, it should set itself to ignore all the

job control stop signals so that it doesn't accidentally stop itself.

You can do this by setting the action for all the stop signals to

@code{SIG_IGN}.

A subshell that runs non-interactively cannot and should not support job

control.  It must leave all processes it creates in the same process

group as the shell itself; this allows the non-interactive shell and its

child processes to be treated as a single job by the parent shell.  This

is easy to do---just don't use any of the job control primitives---but

you must remember to make the shell do it.

Here is the initialization code for the sample shell that shows how to

do all of this.

@smallexample

/* @r{Keep track of attributes of the shell.}  */

#include <sys/types.h>

#include <termios.h>

#include <unistd.h>

pid_t shell_pgid;

struct termios shell_tmodes;

int shell_terminal;

int shell_is_interactive;

/* @r{Make sure the shell is running interactively as the foreground job}

   @r{before proceeding.} */

void

init_shell ()

@{

  /* @r{See if we are running interactively.}  */

  shell_terminal = STDIN_FILENO;

  shell_is_interactive = isatty (shell_terminal);

  if (shell_is_interactive)

    @{

      /* @r{Loop until we are in the foreground.}  */

      while (tcgetpgrp (shell_terminal) != (shell_pgid = getpgrp ()))

        kill (- shell_pgid, SIGTTIN);

      /* @r{Ignore interactive and job-control signals.}  */

      signal (SIGINT, SIG_IGN);

      signal (SIGQUIT, SIG_IGN);

      signal (SIGTSTP, SIG_IGN);

      signal (SIGTTIN, SIG_IGN);

      signal (SIGTTOU, SIG_IGN);

      signal (SIGCHLD, SIG_IGN);

      /* @r{Put ourselves in our own process group.}  */

      shell_pgid = getpid ();

      if (setpgid (shell_pgid, shell_pgid) < 0)

        @{

          perror ("Couldn't put the shell in its own process group");

          exit (1);

        @}

      /* @r{Grab control of the terminal.}  */

      tcsetpgrp (shell_terminal, shell_pgid);

      /* @r{Save default terminal attributes for shell.}  */

      tcgetattr (shell_terminal, &shell_tmodes);

    @}

@}

@end smallexample

@node Launching Jobs, Foreground and Background, Initializing the Shell, Implementing a Shell

@subsection Launching Jobs

@cindex launching jobs

Once the shell has taken responsibility for performing job control on

its controlling terminal, it can launch jobs in response to commands

typed by the user.

To create the processes in a process group, you use the same @code{fork}

and @code{exec} functions described in @ref{Process Creation Concepts}.

Since there are multiple child processes involved, though, things are a

little more complicated and you must be careful to do things in the

right order.  Otherwise, nasty race conditions can result.

You have two choices for how to structure the tree of parent-child

relationships among the processes.  You can either make all the

processes in the process group be children of the shell process, or you

can make one process in group be the ancestor of all the other processes

in that group.  The sample shell program presented in this chapter uses

the first approach because it makes bookkeeping somewhat simpler.

@cindex process group leader

@cindex process group ID

As each process is forked, it should put itself in the new process group

by calling @code{setpgid}; see @ref{Process Group Functions}.  The first

process in the new group becomes its @dfn{process group leader}, and its

process ID becomes the @dfn{process group ID} for the group.

@cindex race conditions, relating to job control

The shell should also call @code{setpgid} to put each of its child

processes into the new process group.  This is because there is a

potential timing problem: each child process must be put in the process

group before it begins executing a new program, and the shell depends on

having all the child processes in the group before it continues

executing.  If both the child processes and the shell call

@code{setpgid}, this ensures that the right things happen no matter which

process gets to it first.

If the job is being launched as a foreground job, the new process group

also needs to be put into the foreground on the controlling terminal

using @code{tcsetpgrp}.  Again, this should be done by the shell as well

as by each of its child processes, to avoid race conditions.

The next thing each child process should do is to reset its signal

actions.

During initialization, the shell process set itself to ignore job

control signals; see @ref{Initializing the Shell}.  As a result, any child

processes it creates also ignore these signals by inheritance.  This is

definitely undesirable, so each child process should explicitly set the

actions for these signals back to @code{SIG_DFL} just after it is forked.

Since shells follow this convention, applications can assume that they

inherit the correct handling of these signals from the parent process.

But every application has a responsibility not to mess up the handling

of stop signals.  Applications that disable the normal interpretation of

the SUSP character should provide some other mechanism for the user to

stop the job.  When the user invokes this mechanism, the program should

send a @code{SIGTSTP} signal to the process group of the process, not

just to the process itself.  @xref{Signaling Another Process}.

Finally, each child process should call @code{exec} in the normal way.

This is also the point at which redirection of the standard input and

output channels should be handled.  @xref{Duplicating Descriptors},

for an explanation of how to do this.

Here is the function from the sample shell program that is responsible

for launching a program.  The function is executed by each child process

immediately after it has been forked by the shell, and never returns.

@smallexample

void

launch_process (process *p, pid_t pgid,

                int infile, int outfile, int errfile,

                int foreground)

@{

  pid_t pid;

  if (shell_is_interactive)

    @{

      /* @r{Put the process into the process group and give the process group}

         @r{the terminal, if appropriate.}

         @r{This has to be done both by the shell and in the individual}

         @r{child processes because of potential race conditions.}  */

      pid = getpid ();

      if (pgid == 0) pgid = pid;

      setpgid (pid, pgid);

      if (foreground)

        tcsetpgrp (shell_terminal, pgid);

      /* @r{Set the handling for job control signals back to the default.}  */

      signal (SIGINT, SIG_DFL);

      signal (SIGQUIT, SIG_DFL);

      signal (SIGTSTP, SIG_DFL);

      signal (SIGTTIN, SIG_DFL);

      signal (SIGTTOU, SIG_DFL);

      signal (SIGCHLD, SIG_DFL);

    @}

  /* @r{Set the standard input/output channels of the new process.}  */

  if (infile != STDIN_FILENO)

    @{

      dup2 (infile, STDIN_FILENO);

      close (infile);

    @}

  if (outfile != STDOUT_FILENO)

    @{

      dup2 (outfile, STDOUT_FILENO);

      close (outfile);

    @}

  if (errfile != STDERR_FILENO)

    @{

      dup2 (errfile, STDERR_FILENO);

      close (errfile);

    @}

  /* @r{Exec the new process.  Make sure we exit.}  */

  execvp (p->argv[0], p->argv);

  perror ("execvp");

  exit (1);

@}

@end smallexample

If the shell is not running interactively, this function does not do

anything with process groups or signals.  Remember that a shell not

performing job control must keep all of its subprocesses in the same

process group as the shell itself.

Next, here is the function that actually launches a complete job.

After creating the child processes, this function calls some other

functions to put the newly created job into the foreground or background;

these are discussed in @ref{Foreground and Background}.

@smallexample

void

launch_job (job *j, int foreground)

@{

  process *p;

  pid_t pid;

  int mypipe[2], infile, outfile;

  infile = j->stdin;

  for (p = j->first_process; p; p = p->next)

    @{

      /* @r{Set up pipes, if necessary.}  */

      if (p->next)

        @{

          if (pipe (mypipe) < 0)

            @{

              perror ("pipe");

              exit (1);

            @}

          outfile = mypipe[1];

        @}

      else

        outfile = j->stdout;

      /* @r{Fork the child processes.}  */

      pid = fork ();

      if (pid == 0)

        /* @r{This is the child process.}  */

        launch_process (p, j->pgid, infile,

                        outfile, j->stderr, foreground);

      else if (pid < 0)

        @{

          /* @r{The fork failed.}  */

          perror ("fork");

          exit (1);

        @}

      else

        @{

          /* @r{This is the parent process.}  */

          p->pid = pid;

          if (shell_is_interactive)

            @{

              if (!j->pgid)

                j->pgid = pid;

              setpgid (pid, j->pgid);

            @}

        @}

      /* @r{Clean up after pipes.}  */

      if (infile != j->stdin)

        close (infile);

      if (outfile != j->stdout)

        close (outfile);

      infile = mypipe[0];

    @}

  format_job_info (j, "launched");

  if (!shell_is_interactive)

    wait_for_job (j);

  else if (foreground)

    put_job_in_foreground (j, 0);

  else

    put_job_in_background (j, 0);

@}

@end smallexample

@node Foreground and Background, Stopped and Terminated Jobs, Launching Jobs, Implementing a Shell

@subsection Foreground and Background

Now let's consider what actions must be taken by the shell when it

launches a job into the foreground, and how this differs from what

must be done when a background job is launched.

@cindex foreground job, launching

When a foreground job is launched, the shell must first give it access

to the controlling terminal by calling @code{tcsetpgrp}.  Then, the

shell should wait for processes in that process group to terminate or

stop.  This is discussed in more detail in @ref{Stopped and Terminated

Jobs}.

When all of the processes in the group have either completed or stopped,

the shell should regain control of the terminal for its own process

group by calling @code{tcsetpgrp} again.  Since stop signals caused by

I/O from a background process or a SUSP character typed by the user

are sent to the process group, normally all the processes in the job

stop together.

The foreground job may have left the terminal in a strange state, so the

shell should restore its own saved terminal modes before continuing.  In

case the job is merely stopped, the shell should first save the current

terminal modes so that it can restore them later if the job is

continued.  The functions for dealing with terminal modes are

@code{tcgetattr} and @code{tcsetattr}; these are described in

@ref{Terminal Modes}.

Here is the sample shell's function for doing all of this.

@smallexample

@group

/* @r{Put job @var{j} in the foreground.  If @var{cont} is nonzero,}

   @r{restore the saved terminal modes and send the process group a}

   @r{@code{SIGCONT} signal to wake it up before we block.}  */

void

put_job_in_foreground (job *j, int cont)

@{

  /* @r{Put the job into the foreground.}  */

  tcsetpgrp (shell_terminal, j->pgid);

@end group

@group

  /* @r{Send the job a continue signal, if necessary.}  */

  if (cont)

    @{

      tcsetattr (shell_terminal, TCSADRAIN, &j->tmodes);

      if (kill (- j->pgid, SIGCONT) < 0)

        perror ("kill (SIGCONT)");

    @}

@end group

  /* @r{Wait for it to report.}  */

  wait_for_job (j);

  /* @r{Put the shell back in the foreground.}  */

  tcsetpgrp (shell_terminal, shell_pgid);

@group

  /* @r{Restore the shell's terminal modes.}  */

  tcgetattr (shell_terminal, &j->tmodes);

  tcsetattr (shell_terminal, TCSADRAIN, &shell_tmodes);

@}

@end group

@end smallexample

@cindex background job, launching

If the process group is launched as a background job, the shell should

remain in the foreground itself and continue to read commands from

the terminal.

In the sample shell, there is not much that needs to be done to put

a job into the background.  Here is the function it uses:

@smallexample

/* @r{Put a job in the background.  If the cont argument is true, send}

   @r{the process group a @code{SIGCONT} signal to wake it up.}  */

void

put_job_in_background (job *j, int cont)

@{

  /* @r{Send the job a continue signal, if necessary.}  */

  if (cont)

    if (kill (-j->pgid, SIGCONT) < 0)

      perror ("kill (SIGCONT)");

@}

@end smallexample

@node Stopped and Terminated Jobs, Continuing Stopped Jobs, Foreground and Background, Implementing a Shell

@subsection Stopped and Terminated Jobs

@cindex stopped jobs, detecting

@cindex terminated jobs, detecting

When a foreground process is launched, the shell must block until all of

the processes in that job have either terminated or stopped.  It can do

this by calling the @code{waitpid} function; see @ref{Process

Completion}.  Use the @code{WUNTRACED} option so that status is reported

for processes that stop as well as processes that terminate.

The shell must also check on the status of background jobs so that it

can report terminated and stopped jobs to the user; this can be done by

calling @code{waitpid} with the @code{WNOHANG} option.  A good place to

put a such a check for terminated and stopped jobs is just before

prompting for a new command.

@cindex @code{SIGCHLD}, handling of

The shell can also receive asynchronous notification that there is

status information available for a child process by establishing a

handler for @code{SIGCHLD} signals.  @xref{Signal Handling}.

In the sample shell program, the @code{SIGCHLD} signal is normally

ignored.  This is to avoid reentrancy problems involving the global data

structures the shell manipulates.  But at specific times when the shell

is not using these data structures---such as when it is waiting for

input on the terminal---it makes sense to enable a handler for

@code{SIGCHLD}.  The same function that is used to do the synchronous

status checks (@code{do_job_notification}, in this case) can also be

called from within this handler.

Here are the parts of the sample shell program that deal with checking

the status of jobs and reporting the information to the user.

@smallexample

@group

/* @r{Store the status of the process @var{pid} that was returned by waitpid.}

   @r{Return 0 if all went well, nonzero otherwise.}  */

int

mark_process_status (pid_t pid, int status)

@{

  job *j;

  process *p;

@end group

@group

  if (pid > 0)

    @{

      /* @r{Update the record for the process.}  */

      for (j = first_job; j; j = j->next)

        for (p = j->first_process; p; p = p->next)

          if (p->pid == pid)

            @{

              p->status = status;

              if (WIFSTOPPED (status))

                p->stopped = 1;

              else

                @{

                  p->completed = 1;

                  if (WIFSIGNALED (status))

                    fprintf (stderr, "%d: Terminated by signal %d.\n",

                             (int) pid, WTERMSIG (p->status));

                @}

              return 0;

             @}

      fprintf (stderr, "No child process %d.\n", pid);

      return -1;

    @}

@end group

@group

  else if (pid == 0 || errno == ECHILD)

    /* @r{No processes ready to report.}  */

    return -1;

  else @{

    /* @r{Other weird errors.}  */

    perror ("waitpid");

    return -1;

  @}

@}

@end group

@group

/* @r{Check for processes that have status information available,}

   @r{without blocking.}  */

void

update_status (void)

@{

  int status;

  pid_t pid;

  do

    pid = waitpid (WAIT_ANY, &status, WUNTRACED|WNOHANG);

  while (!mark_process_status (pid, status));

@}

@end group

@group

/* @r{Check for processes that have status information available,}

   @r{blocking until all processes in the given job have reported.}  */

void

wait_for_job (job *j)

@{

  int status;

  pid_t pid;

  do

    pid = waitpid (WAIT_ANY, &status, WUNTRACED);

  while (!mark_process_status (pid, status)

         && !job_is_stopped (j)

         && !job_is_completed (j));

@}

@end group

@group

/* @r{Format information about job status for the user to look at.}  */

void

format_job_info (job *j, const char *status)

@{

  fprintf (stderr, "%ld (%s): %s\n", (long)j->pgid, status, j->command);

@}

@end group

@group

/* @r{Notify the user about stopped or terminated jobs.}

   @r{Delete terminated jobs from the active job list.}  */

void

do_job_notification (void)

@{

  job *j, *jlast, *jnext;

  process *p;