job.texi

一个C源代码分析器

  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;

  /* @r{Update status information for child processes.}  */
  update_status ();
  
  jlast = NULL;
  for (j = first_job; j; j = jnext)
    @{
      jnext = j->next;

      /* @r{If all processes have completed, tell the user the job has}
         @r{completed and delete it from the list of active jobs.}  */
      if (job_is_completed (j)) @{
        format_job_info (j, "completed");
        if (jlast)
          jlast->next = jnext;
        else
          first_job = jnext;
        free_job (j);
      @}

      /* @r{Notify the user about stopped jobs,}
         @r{marking them so that we won't do this more than once.}  */
      else if (job_is_stopped (j) && !j->notified) @{
        format_job_info (j, "stopped");
        j->notified = 1;
        jlast = j;
      @}

      /* @r{Don't say anything about jobs that are still running.}  */
      else
        jlast = j;
    @}
@}
@end group
@end smallexample

@node Continuing Stopped Jobs, Missing Pieces, Stopped and Terminated Jobs, Implementing a Shell
@subsection Continuing Stopped Jobs

@cindex stopped jobs, continuing
The shell can continue a stopped job by sending a @code{SIGCONT} signal
to its process group.  If the job is being continued in the foreground,
the shell should first invoke @code{tcsetpgrp} to give the job access to
the terminal, and restore the saved terminal settings.  After continuing
a job in the foreground, the shell should wait for the job to stop or
complete, as if the job had just been launched in the foreground.

The sample shell program handles both newly created and continued jobs
with the same pair of functions, @w{@code{put_job_in_foreground}} and
@w{@code{put_job_in_background}}.  The definitions of these functions
were given in @ref{Foreground and Background}.  When continuing a
stopped job, a nonzero value is passed as the @var{cont} argument to
ensure that the @code{SIGCONT} signal is sent and the terminal modes
reset, as appropriate.

This leaves only a function for updating the shell's internal bookkeeping
about the job being continued:

@smallexample
@group
/* @r{Mark a stopped job J as being running again.}  */

void
mark_job_as_running (job *j)
@{
  Process *p;

  for (p = j->first_process; p; p = p->next)
    p->stopped = 0;
  j->notified = 0;
@}
@end group

@group
/* @r{Continue the job J.}  */

void
continue_job (job *j, int foreground)
@{
  mark_job_as_running (j);
  if (foreground)
    put_job_in_foreground (j, 1);
  else
    put_job_in_background (j, 1);
@}
@end group
@end smallexample

@node Missing Pieces,  , Continuing Stopped Jobs, Implementing a Shell
@subsection The Missing Pieces

The code extracts for the sample shell included in this chapter are only
a part of the entire shell program.  In particular, nothing at all has
been said about how @code{job} and @code{program} data structures are
allocated and initialized.

Most real shells provide a complex user interface that has support for
a command language; variables; abbreviations, substitutions, and pattern
matching on file names; and the like.  All of this is far too complicated
to explain here!  Instead, we have concentrated on showing how to 
implement the core process creation and job control functions that can
be called from such a shell.

Here is a table summarizing the major entry points we have presented:

@table @code
@item void init_shell (void)
Initialize the shell's internal state.  @xref{Initializing the
Shell}.

@item void launch_job (job *@var{j}, int @var{foreground})
Launch the job @var{j} as either a foreground or background job.
@xref{Launching Jobs}.

@item void do_job_notification (void)
Check for and report any jobs that have terminated or stopped.  Can be
called synchronously or within a handler for @code{SIGCHLD} signals.
@xref{Stopped and Terminated Jobs}.

@item void continue_job (job *@var{j}, int @var{foreground})
Continue the job @var{j}.  @xref{Continuing Stopped Jobs}.
@end table

Of course, a real shell would also want to provide other functions for
managing jobs.  For example, it would be useful to have commands to list
all active jobs or to send a signal (such as @code{SIGKILL}) to a job.


@node Functions for Job Control,  , Implementing a Shell, Job Control
@section Functions for Job Control
@cindex process group functions
@cindex job control functions

This section contains detailed descriptions of the functions relating
to job control.

@menu
* Identifying the Terminal::    Determining the controlling terminal's name.
* Process Group Functions::     Functions for manipulating process groups.
* Terminal Access Functions::   Functions for controlling terminal access.
@end menu


@node Identifying the Terminal, Process Group Functions,  , Functions for Job Control
@subsection Identifying the Controlling Terminal
@cindex controlling terminal, determining

You can use the @code{ctermid} function to get a file name that you can
use to open the controlling terminal.  In the GNU library, it returns
the same string all the time: @code{"/dev/tty"}.  That is a special
``magic'' file name that refers to the controlling terminal of the
current process (if it has one).  To find the name of the specific
terminal device, use @code{ttyname}; @pxref{Is It a Terminal}.

The function @code{ctermid} is declared in the header file
@file{stdio.h}.
@pindex stdio.h

@comment stdio.h
@comment POSIX.1
@deftypefun {char *} ctermid (char *@var{string})
The @code{ctermid} function returns a string containing the file name of
the controlling terminal for the current process.  If @var{string} is
not a null pointer, it should be an array that can hold at least
@code{L_ctermid} characters; the string is returned in this array.
Otherwise, a pointer to a string in a static area is returned, which
might get overwritten on subsequent calls to this function.

An empty string is returned if the file name cannot be determined for
any reason.  Even if a file name is returned, access to the file it
represents is not guaranteed.
@end deftypefun

@comment stdio.h
@comment POSIX.1
@deftypevr Macro int L_ctermid
The value of this macro is an integer constant expression that
represents the size of a string large enough to hold the file name
returned by @code{ctermid}.
@end deftypevr

See also the @code{isatty} and @code{ttyname} functions, in 
@ref{Is It a Terminal}.


@node Process Group Functions, Terminal Access Functions, Identifying the Terminal, Functions for Job Control
@subsection Process Group Functions

Here are descriptions of the functions for manipulating process groups.
Your program should include the header files @file{sys/types.h} and
@file{unistd.h} to use these functions.
@pindex unistd.h
@pindex sys/types.h

@comment unistd.h
@comment POSIX.1
@deftypefun pid_t setsid (void)
The @code{setsid} function creates a new session.  The calling process
becomes the session leader, and is put in a new process group whose
process group ID is the same as the process ID of that process.  There
are initially no other processes in the new process group, and no other
process groups in the new session.

This function also makes the calling process have no controlling terminal.

The @code{setsid} function returns the new process group ID of the
calling process if successful.  A return value of @code{-1} indicates an
error.  The following @code{errno} error conditions are defined for this
function:

@table @code
@item EPERM
The calling process is already a process group leader, or there is
already another process group around that has the same process group ID.
@end table
@end deftypefun

The @code{getpgrp} function has two definitions: one derived from BSD
Unix, and one from the POSIX.1 standard.  The feature test macros you
have selected (@pxref{Feature Test Macros}) determine which definition
you get.  Specifically, you get the BSD version if you define
@code{_BSD_SOURCE}; otherwise, you get the POSIX version if you define
@code{_POSIX_SOURCE} or @code{_GNU_SOURCE}.  Programs written for old
BSD systems will not include @file{unistd.h}, which defines
@code{getpgrp} specially under @code{_BSD_SOURCE}.  You must link such
programs with the @code{-lbsd-compat} option to get the BSD definition.@refill
@pindex -lbsd-compat
@pindex bsd-compat
@cindex BSD compatibility library

@comment unistd.h
@comment POSIX.1
@deftypefn {POSIX.1 Function} pid_t getpgrp (void)
The POSIX.1 definition of @code{getpgrp} returns the process group ID of
the calling process.
@end deftypefn

@comment unistd.h
@comment BSD
@deftypefn {BSD Function} pid_t getpgrp (pid_t @var{pid})
The BSD definition of @code{getpgrp} returns the process group ID of the
process @var{pid}.  You can supply a value of @code{0} for the @var{pid}
argument to get information about the calling process.
@end deftypefn

@comment unistd.h
@comment POSIX.1
@deftypefun int setpgid (pid_t @var{pid}, pid_t @var{pgid})
The @code{setpgid} function puts the process @var{pid} into the process
group @var{pgid}.  As a special case, either @var{pid} or @var{pgid} can
be zero to indicate the process ID of the calling process.

This function fails on a system that does not support job control.
@xref{Job Control is Optional}, for more information.

If the operation is successful, @code{setpgid} returns zero.  Otherwise
it returns @code{-1}.  The following @code{errno} error conditions are
defined for this function:

@table @code
@item EACCES
The child process named by @var{pid} has executed an @code{exec}
function since it was forked.

@item EINVAL
The value of the @var{pgid} is not valid.

@item ENOSYS
The system doesn't support job control.

@item EPERM
The process indicated by the @var{pid} argument is a session leader,
or is not in the same session as the calling process, or the value of
the @var{pgid} argument doesn't match a process group ID in the same
session as the calling process.

@item ESRCH
The process indicated by the @var{pid} argument is not the calling
process or a child of the calling process.
@end table
@end deftypefun

@comment unistd.h
@comment BSD
@deftypefun int setpgrp (pid_t @var{pid}, pid_t @var{pgid})
This is the BSD Unix name for @code{setpgid}.  Both functions do exactly
the same thing.
@end deftypefun


@node Terminal Access Functions,  , Process Group Functions, Functions for Job Control
@subsection Functions for Controlling Terminal Access

These are the functions for reading or setting the foreground
process group of a terminal.  You should include the header files
@file{sys/types.h} and @file{unistd.h} in your application to use
these functions.
@pindex unistd.h
@pindex sys/types.h

Although these functions take a file descriptor argument to specify
the terminal device, the foreground job is associated with the terminal
file itself and not a particular open file descriptor.

@comment unistd.h
@comment POSIX.1
@deftypefun pid_t tcgetpgrp (int @var{filedes})
This function returns the process group ID of the foreground process
group associated with the terminal open on descriptor @var{filedes}.

If there is no foreground process group, the return value is a number
greater than @code{1} that does not match the process group ID of any
existing process group.  This can happen if all of the processes in the
job that was formerly the foreground job have terminated, and no other
job has yet been moved into the foreground.

In case of an error, a value of @code{-1} is returned.  The
following @code{errno} error conditions are defined for this function:

@table @code
@item EBADF
The @var{filedes} argument is not a valid file descriptor.

@item ENOSYS
The system doesn't support job control.

@item ENOTTY
The terminal file associated with the @var{filedes} argument isn't the
controlling terminal of the calling process.
@end table
@end deftypefun

@comment unistd.h
@comment POSIX.1
@deftypefun int tcsetpgrp (int @var{filedes}, pid_t @var{pgid})
This function is used to set a terminal's foreground process group ID.
The argument @var{filedes} is a descriptor which specifies the terminal;
@var{pgid} specifies the process group.  The calling process must be a
member of the same session as @var{pgid} and must have the same
controlling terminal.

For terminal access purposes, this function is treated as output.  If it
is called from a background process on its controlling terminal,
normally all processes in the process group are sent a @code{SIGTTOU}
signal.  The exception is if the calling process itself is ignoring or
blocking @code{SIGTTOU} signals, in which case the operation is
performed and no signal is sent.

If successful, @code{tcsetpgrp} returns @code{0}.  A return value of
@code{-1} indicates an error.  The following @code{errno} error
conditions are defined for this function:

@table @code
@item EBADF
The @var{filedes} argument is not a valid file descriptor.

@item EINVAL
The @var{pgid} argument is not valid.

@item ENOSYS
The system doesn't support job control.

@item ENOTTY
The @var{filedes} isn't the controlling terminal of the calling process.

@item EPERM
The @var{pgid} isn't a process group in the same session as the calling
process.
@end table
@end deftypefun