mirror of https://github.com/GnoConsortium/gno.git
145 lines
4.0 KiB
Groff
145 lines
4.0 KiB
Groff
.\"
|
|
.\" $Id: jobcontrol.2,v 1.1 1997/02/27 07:32:14 gdr Exp $
|
|
.\"
|
|
.TH "JOBCONTROL" 2 "19 January 1997" GNO "System Calls"
|
|
.SH NAME
|
|
.BR settpgrp ,
|
|
.BR tcnewpgrp ,
|
|
.BR tctpgrp
|
|
\- interface for the new job control model
|
|
.SH SYNOPSIS
|
|
#include <gno/gno.h>
|
|
.sp 1
|
|
int
|
|
\fBtcnewpgrp\fR(int \fIfdtty\fR);
|
|
.br
|
|
int
|
|
\fBsettpgrp\fR(int \fIfdtty\fR);
|
|
.br
|
|
int
|
|
\fBtctpgrp\fR(int \fIfdtty\fR, int \fIpid\fR);
|
|
.SH DESCRIPTION
|
|
The job control interface is used to control what processes are 'in
|
|
the foreground' on a particular terminal. Every tty has a process group.
|
|
Each process is a member of a process group. A process is a foreground
|
|
process on a tty if and only if that process and the terminal belong
|
|
to the same process group. Certain characters (such as ^C) typed on a
|
|
tty with a non-zero process group produce signals sent to every process
|
|
which is a member of the group.
|
|
.LP
|
|
A process is suspended (stopped) if it performs a sufficiently invasive
|
|
operation on a tty with a different process group. This includes these
|
|
job control calls, reads from a terminal, and writes to a terminal if
|
|
it is configured to do so with
|
|
.BR ioctl (2).
|
|
When a tty file is first opened, it is assigned process group zero
|
|
.RB ( init (8)
|
|
has process group zero). As
|
|
.BR init
|
|
launches login processes on various ttys, it assigns process groups
|
|
to those ttys and processes.
|
|
.LP
|
|
.BR tcnewpgrp
|
|
allocates a new process group and assigns it to the terminal referred
|
|
to by
|
|
.IR fdtty .
|
|
If the calling process is not in the foreground, it is sent
|
|
.BR SIGTTOU .
|
|
.LP
|
|
.BR settpgrp
|
|
sets the current process to have the process group as
|
|
.IR fdtty .
|
|
.LP
|
|
.BR tctpgrp
|
|
sets the tty referred to by
|
|
.IR fdtty
|
|
to the same process group as the process
|
|
.IR pid ,
|
|
where
|
|
.IR pid
|
|
is the current process or a descendant of it.
|
|
.SH RETURN VALUE
|
|
These calls will return zero on success, otherwise they'll return -1
|
|
and set
|
|
.BR errno
|
|
accordingly.
|
|
.SH ERRORS
|
|
.IP \fBEBADF\fR
|
|
.IR fdtty
|
|
is not a valid file descriptor.
|
|
.IP \fBENOTTY\fR
|
|
.IR fdtty
|
|
does not refer to a terminal file.
|
|
.IP \fBESRCH\fR
|
|
.IR pid
|
|
is not a valid process identifier.
|
|
.SH EXAMPLES
|
|
The following are some example uses of the job control interface.
|
|
.RS
|
|
.LP
|
|
Forking a pipeline in a job-control shell: The shell starts with
|
|
.BR tcnewpgrp
|
|
so that the tty is in the new process group before there are even any
|
|
children. It then
|
|
.BR fork s
|
|
each process in the pipeline. Each process does
|
|
.BR settpgrp ,
|
|
thus joining the new process group.
|
|
.LP
|
|
Handling a stopped child process: When the shell sees that a pipeline
|
|
has stopped or exited, it does
|
|
.BR tctpgrp
|
|
to set the tty to its own process group. To resume the pipeline it does
|
|
.BR tctpgrp
|
|
where
|
|
.IR pid
|
|
is one of the child processes, then sends
|
|
.BR SIGCONT .
|
|
.LP
|
|
Starting a process under a new tty: When, for instance,
|
|
telnetd (8)
|
|
wants to grap a pseudo-tty, it opens the pty and
|
|
.BR fork s
|
|
a child process. The child does
|
|
.BR tcnewpgrp
|
|
to give the tty a real process group, then
|
|
.BR settpgrp
|
|
to place itself into the foregroup.
|
|
.RE
|
|
Security under this scheme is trivial. there is no way a process can join
|
|
a process group except by
|
|
.BR settpgrp ,
|
|
and that requires a descriptor open to a tty with that
|
|
.IR pgrp .
|
|
To make a tty have that
|
|
.Ir pgrp
|
|
requires either
|
|
.BR tcnewpgrp
|
|
(in which case nobody else is using the
|
|
.IR pgrp ),
|
|
or
|
|
.BR tctpgrp
|
|
(which reduces to the first problem of having a process in the process
|
|
group).
|
|
.LP
|
|
Note that 'using' must be defined as use both by ttys and by processes; the
|
|
kernel keeps a table of
|
|
.IR pgrp s,
|
|
each with a total tty and process reference count. When the reference
|
|
count reaches zero, the
|
|
.IR pgrp
|
|
is automatically deallocated.
|
|
.SH SEE ALSO
|
|
.BR ioctl (2),
|
|
.BR kill (2),
|
|
.BR signal (2),
|
|
.BR tty (4),
|
|
.IR "GNO Shell Reference Manual" .
|
|
.SH CREDITS
|
|
This job control interface was designed by Dan Bernstein
|
|
<brnstnd@kramden.acf.nyu.edu>. He was inspired by Chris Torek, and
|
|
dedicated the system to Mark Teitelbaum. The text of this manpage is
|
|
derived from his original specifications.
|
|
.LP
|
|
The GNO implementation was written strictly from specs.
|