continued jobs.  The definitions of these functions were given in
section <A HREF="library_24.html#SEC421" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC421">Foreground and Background</A>.  When continuing a stopped job, a
nonzero value is passed as the <VAR>cont</VAR> argument to ensure that the
<CODE>SIGCONT</CODE> signal is sent and the terminal modes reset, as
appropriate.
<P>
This leaves only a function for updating the shell's internal bookkeeping
about the job being continued:
<P>
<PRE>
/* Mark a stopped job J as being running again.  */

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

  for (p = j-&#62;first_process; p; p = p-&#62;next)
    p-&#62;stopped = 0;
  j-&#62;notified = 0;
}

/* 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);
}
</PRE>
<P>
<H3><A NAME="SEC424" HREF="library_toc.html#SEC424" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC424">The Missing Pieces</A></H3>
<P>
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</CODE> and <CODE>program</CODE> data structures are
allocated and initialized.
<P>
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.
<P>
Here is a table summarizing the major entry points we have presented:
<P>
<DL COMPACT>
<DT><CODE>void init_shell (void)</CODE>
<DD>Initialize the shell's internal state.  See section <A HREF="library_24.html#SEC419" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC419">Initializing the Shell</A>.
<P>
<DT><CODE>void launch_job (job *<VAR>j</VAR>, int <VAR>foreground</VAR>)</CODE>
<DD>Launch the job <VAR>j</VAR> as either a foreground or background job.
See section <A HREF="library_24.html#SEC420" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC420">Launching Jobs</A>.
<P>
<DT><CODE>void do_job_notification (void)</CODE>
<DD>Check for and report any jobs that have terminated or stopped.  Can be
called synchronously or within a handler for <CODE>SIGCHLD</CODE> signals.
See section <A HREF="library_24.html#SEC422" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC422">Stopped and Terminated Jobs</A>.
<P>
<DT><CODE>void continue_job (job *<VAR>j</VAR>, int <VAR>foreground</VAR>)</CODE>
<DD>Continue the job <VAR>j</VAR>.  See section <A HREF="library_24.html#SEC423" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC423">Continuing Stopped Jobs</A>.
</DL>
<P>
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</CODE>) to a job.
<P>
<A NAME="IDX1759"></A>
<A NAME="IDX1760"></A>
<H2><A NAME="SEC425" HREF="library_toc.html#SEC425" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC425">Functions for Job Control</A></H2>
<P>
This section contains detailed descriptions of the functions relating
to job control.
<P>
<A NAME="IDX1761"></A>
<H3><A NAME="SEC426" HREF="library_toc.html#SEC426" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC426">Identifying the Controlling Terminal</A></H3>
<P>
You can use the <CODE>ctermid</CODE> 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"</CODE>.  That is a special
"magic" file name that refers to the controlling terminal of the
current process (if it has one).  The function <CODE>ctermid</CODE> is
declared in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX1762"></A>
<P>
<A NAME="IDX1763"></A>
<U>Function:</U> char * <B>ctermid</B> <I>(char *<VAR>string</VAR>)</I><P>
The <CODE>ctermid</CODE> function returns a string containing the file name of
the controlling terminal for the current process.  If <VAR>string</VAR> is
not a null pointer, it should be an array that can hold at least
<CODE>L_ctermid</CODE> 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.
<P>
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.
<P>
<A NAME="IDX1764"></A>
<U>Macro:</U> int <B>L_ctermid</B><P>
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</CODE>.
<P>
See also the <CODE>isatty</CODE> and <CODE>ttyname</CODE> functions, in 
section <A HREF="library_16.html#SEC269" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_16.html#SEC269">Identifying Terminals</A>.
<P>
<H3><A NAME="SEC427" HREF="library_toc.html#SEC427" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC427">Process Group Functions</A></H3>
<P>
Here are descriptions of the functions for manipulating process groups.
Your program should include the header files <TT>`sys/types.h'</TT> and
<TT>`unistd.h'</TT> to use these functions.
<A NAME="IDX1766"></A>
<A NAME="IDX1765"></A>
<P>
<A NAME="IDX1767"></A>
<U>Function:</U> pid_t <B>setsid</B> <I>(void)</I><P>
The <CODE>setsid</CODE> 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.
<P>
This function also makes the calling process have no controlling terminal.
<P>
The <CODE>setsid</CODE> function returns the new process group ID of the
calling process if successful.  A return value of <CODE>-1</CODE> indicates an
error.  The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EPERM</CODE>
<DD>The calling process is already a process group leader, or there is
already another process group around that has the same process group ID.
</DL>
<P>
The <CODE>getpgrp</CODE> function has two definitions: one derived from BSD
Unix, and one from the POSIX.1 standard.  The feature test macros you
have selected (see section <A HREF="library_1.html#SEC12" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_1.html#SEC12">Feature Test Macros</A>) determine which definition
you get.  Specifically, you get the BSD version if you define
<CODE>_BSD_SOURCE</CODE>; otherwise, you get the POSIX version if you define
<CODE>_POSIX_SOURCE</CODE> or <CODE>_GNU_SOURCE</CODE>.  Programs written for old
BSD systems will not include <TT>`unistd.h'</TT>, which defines
<CODE>getpgrp</CODE> specially under <CODE>_BSD_SOURCE</CODE>.  You must link such
programs with the <CODE>-lbsd-compat</CODE> option to get the BSD definition.<A NAME="IDX1769"></A>
<A NAME="IDX1770"></A>
<A NAME="IDX1768"></A>
<P>
<A NAME="IDX1771"></A>
<U>POSIX.1 Function:</U> pid_t <B>getpgrp</B> <I>(void)</I><P>
The POSIX.1 definition of <CODE>getpgrp</CODE> returns the process group ID of
the calling process.
<P>
<A NAME="IDX1772"></A>
<U>BSD Function:</U> pid_t <B>getpgrp</B> <I>(pid_t <VAR>pid</VAR>)</I><P>
The BSD definition of <CODE>getpgrp</CODE> returns the process group ID of the
process <VAR>pid</VAR>.  You can supply a value of <CODE>0</CODE> for the <VAR>pid</VAR>
argument to get information about the calling process.
<P>
<A NAME="IDX1773"></A>
<U>Function:</U> int <B>setpgid</B> <I>(pid_t <VAR>pid</VAR>, pid_t <VAR>pgid</VAR>)</I><P>
The <CODE>setpgid</CODE> function puts the process <VAR>pid</VAR> into the process
group <VAR>pgid</VAR>.  As a special case, either <VAR>pid</VAR> or <VAR>pgid</VAR> can
be zero to indicate the process ID of the calling process.
<P>
This function fails on a system that does not support job control.
See section <A HREF="library_24.html#SEC413" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html#SEC413">Job Control is Optional</A>, for more information.
<P>
If the operation is successful, <CODE>setpgid</CODE> returns zero.  Otherwise
it returns <CODE>-1</CODE>.  The following <CODE>errno</CODE> error conditions are
defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>The child process named by <VAR>pid</VAR> has executed an <CODE>exec</CODE>
function since it was forked.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The value of the <VAR>pgid</VAR> is not valid.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The system doesn't support job control.
<P>
<DT><CODE>EPERM</CODE>
<DD>The process indicated by the <VAR>pid</VAR> argument is a session leader,
or is not in the same session as the calling process, or the value of
the <VAR>pgid</VAR> argument doesn't match a process group ID in the same
session as the calling process.
<P>
<DT><CODE>ESRCH</CODE>
<DD>The process indicated by the <VAR>pid</VAR> argument is not the calling
process or a child of the calling process.
</DL>
<P>
<A NAME="IDX1774"></A>
<U>Function:</U> int <B>setpgrp</B> <I>(pid_t <VAR>pid</VAR>, pid_t <VAR>pgid</VAR>)</I><P>
This is the BSD Unix name for <CODE>setpgid</CODE>.  Both functions do exactly
the same thing.
<P>
<H3><A NAME="SEC428" HREF="library_toc.html#SEC428" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC428">Functions for Controlling Terminal Access</A></H3>
<P>
These are the functions for reading or setting the foreground
process group of a terminal.  You should include the header files
<TT>`sys/types.h'</TT> and <TT>`unistd.h'</TT> in your application to use
these functions.
<A NAME="IDX1776"></A>
<A NAME="IDX1775"></A>
<P>
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.
<P>
<A NAME="IDX1777"></A>
<U>Function:</U> pid_t <B>tcgetpgrp</B> <I>(int <VAR>filedes</VAR>)</I><P>
This function returns the process group ID of the foreground process
group associated with the terminal open on descriptor <VAR>filedes</VAR>.
<P>
If there is no foreground process group, the return value is a number
greater than <CODE>1</CODE> 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.
<P>
In case of an error, a value of <CODE>-1</CODE> is returned.  The
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The system doesn't support job control.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The terminal file associated with the <VAR>filedes</VAR> argument isn't the
controlling terminal of the calling process.
</DL>
<P>
<A NAME="IDX1778"></A>
<U>Function:</U> int <B>tcsetpgrp</B> <I>(int <VAR>filedes</VAR>, pid_t <VAR>pgid</VAR>)</I><P>
This function is used to set a terminal's foreground process group ID.
The argument <VAR>filedes</VAR> is a descriptor which specifies the terminal;
<VAR>pgid</VAR> specifies the process group.  The calling process must be a
member of the same session as <VAR>pgid</VAR> and must have the same
controlling terminal.
<P>
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</CODE>
signal.  The exception is if the calling process itself is ignoring or
blocking <CODE>SIGTTOU</CODE> signals, in which case the operation is
performed and no signal is sent.
<P>
If successful, <CODE>tcsetpgrp</CODE> returns <CODE>0</CODE>.  A return value of
<CODE>-1</CODE> indicates an error.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>filedes</VAR> argument is not a valid file descriptor.
<P>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>pgid</VAR> argument is not valid.
<P>
<DT><CODE>ENOSYS</CODE>
<DD>The system doesn't support job control.
<P>
<DT><CODE>ENOTTY</CODE>
<DD>The <VAR>filedes</VAR> isn't the controlling terminal of the calling process.
<P>
<DT><CODE>EPERM</CODE>
<DD>The <VAR>pgid</VAR> isn't a process group in the same session as the calling
process.
</DL>
<P>
<P>Go to the <A HREF="library_23.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html">previous</A>, <A HREF="library_25.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html">next</A> section.<P>