![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to jobs.3j CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / manb|
Return to jobs.3j CVS log | Up to [Research Unix] / researchv10dc / man / manb |
1.1 root 1: .TH JOBS 3J
2: .UC 4
3: .SH NAME
4: jobs \- summary of job control facilities
5: .SH SYNOPSIS
6: .nf
7: .B #include <sys/ioctl.h>
8: .B #include <signal.h>
9: .B #include <sys/vtimes.h>
10: .B #include <wait.h>
11: .PP
12: .B int fildes, signo;
13: .B short pid, pgrp;
14: .B union wait status;
15: .B struct vtimes vt;
16: .PP
17: .B ioctl(fildes, TIOCSPGRP, &pgrp)
18: .B ioctl(fildes, TIOCGPGRP, &pgrp)
19: .PP
20: .B setpgrp(pid, pgrp)
21: .B getpgrp(pid)
22: .B killpg(pgrp, signo)
23: .PP
24: .B sigset(signo, action)
25: .B sighold(signo)
26: .B sigrelse(signo)
27: .B sigpause(signo)
28: .B sigsys(signo, action)
29: .PP
30: .B wait3(&status, options, &vt)
31: .PP
32: .B cc ... \-ljobs
33: .fi
34: .SH DESCRIPTION
35: The facilities described here are used to support the job control implemented
36: in
37: .IR csh (1),
38: and may be used in other programs to provide similar facilities.
39: Because these facilities are not standard in UNIX and because the
40: signal mechanisms are also slightly different, the associated
41: routines are not in the standard C library, but rather in the \fB\-ljobs\fR
42: library.
43: .PP
44: For descriptions of the individual routines see the various sections listed
45: in \s-2SEE ALSO\s0 below. This section attempt only to place these facilities
46: in context, not to explain the semantics of the individual calls.
47: .PP
48: .B "Terminal arbitration mechanisms."
49: .PP
50: The job control mechanism works by associating with each process a number
51: called a
52: .I "process group";
53: related processes (e.g. in a pipeline) are given the same process group.
54: The system assigns a single process group number to each terminal.
55: Processes running on a terminal are given read access to that terminal
56: only if they are in the same process group as that terminal.
57: .PP
58: Thus a command interpreter may start several jobs running in different
59: process groups and arbitrate access to the terminal by controlling which,
60: if any, of these processes is in the same process group as the terminal.
61: When a process which is not
62: in the process group of the terminal tries to read from the terminal,
63: all members of the process group of the process receive a SIGTTIN signal,
64: which normally then causes them to stop until they are continued
65: with a SIGCONT signal.
66: (See
67: .IR sigsys (2)
68: for a description of these signals;
69: .IR tty (4)
70: for a description of process groups.)
71: .PP
72: If a process which is not in the process group of the terminal
73: attempts to change the terminals mode,
74: the process group of that process is sent a SIGTTOU signal, causing
75: the process group to stop.
76: A similar mechanism is (optionally) available for output, causing
77: processes to block with SIGTTOU when they attempt to write to the terminal
78: while not in its process group;
79: this is controlled by the LTOSTOP bit in the tty mode
80: word, enabled by \*(lqstty tostop\*(rq and disabled (the default)
81: by \*(lqstty \-tostop.\*(rq
82: (The LTOSTOP bit is described in
83: .IR tty (4)).
84: .LP
85: .B "How the shell manipulates process groups."
86: .PP
87: A shell which is interactive first establishes its own process group
88: and a process group for the terminal; this prevents other processes
89: from being inadvertantly stopped while the terminal is under its control.
90: The shell then assigns each job it creates a distinct process group.
91: When a job is to be run in the foreground,
92: the shell gives the terminal to the process group of the job using
93: the TIOCSPGRP ioctl
94: (See
95: .IR ioctl (2)
96: and
97: .IR tty (4)).
98: When a job stops or completes, the shell reclaims the terminal
99: by resetting the terminals process group to that of the shell using
100: TIOCSPGRP again.
101: .PP
102: Shells which are running shell scripts or running non-interactively do
103: not manipulate process groups of jobs they create. Instead, they
104: leave the process group of sub-processes and the terminal unchanged.
105: This assures that if any sub-process they create blocks for terminal i/o,
106: the shell and all its sub-processes will be blocked
107: (since they are a single process group).
108: The first interactive parent of the non-interactive shell
109: can then be used to deal with the stoppage.
110: .PP
111: Processes which are orphans (whose parents have exited), and descendants
112: of these processes are protected by the system from stopping, since there
113: can be no interactive parent. Rather than blocking, reads from the
114: control terminal return end-of-file and writes to the control
115: terminal are permitted (i.e. LTOSTOP has no effect for these processes.)
116: Similarly processes which ignore or hold the SIGTTIN or SIGTTOU signal are not
117: sent these signals when accessing their control terminal; if they are not in the
118: process group of the control terminal reads simply return end-of-file.
119: Output and mode setting are also allowed.
120: .PP
121: Before a shell
122: .I suspends
123: itself, it places itself back in the process group in which it was
124: created, and then sends this original group a stopping signal, stopping
125: the shell and any other intermediate processes back to an interactive parent.
126: The shell also restores the process group of the terminal when it finishes,
127: as the process which then resumes would not necessarily be in control of
128: the terminal otherwise.
129: .PP
130: .B "Naive processes."
131: .PP
132: A process which does not alter the state of the terminal,
133: and which does no job control can invoke subprocesses normally
134: without worry. If such a process issues a
135: .IR system (3)
136: call and this command is then stopped, both of the processes will stop
137: together. Thus simple processes need not worry about job control, even
138: if they have \*(lqshell escapes\*(rq or invoke other processes.
139: .PP
140: .B "Processes which modify the terminal state."
141: .PP
142: When first setting the terminal into an unusual mode, the process
143: should check, with the stopping signals held,
144: that it is in the foreground. It should then change the state of the
145: terminal, and set the catches for SIGTTIN, SIGTTOU and SIGTSTP.
146: The following is a sample of the code that will be needed, assuming
147: that unit 2 is known to be a terminal.
148: .PP
149: .nf
150: .ft B
151: short tpgrp;
152: \&...
153:
154: retry:
155: sigset(SIGTSTP, SIG_HOLD);
156: sigset(SIGTTIN, SIG_HOLD);
157: sigset(SIGTTOU, SIG_HOLD);
158: if (ioctl(2, TIOCGPGRP, &tpgrp) != 0)
159: goto nottty;
160: if (tpgrp != getpgrp(0)) { /* not in foreground */
161: sigset(SIGTTOU, SIG_DFL);
162: kill(0, SIGTTOU);
163: /* job stops here waiting for SIGCONT */
164: goto retry;
165: }
166: \fI\&...save old terminal modes and set new modes\&...\fB
167: sigset(SIGTTIN, onstop);
168: sigset(SIGTTOU, onstop);
169: sigset(SIGTSTP, onstop);
170: .ft R
171: .fi
172: .PP
173: It is necessary to ignore SIGTSTP in this code because otherwise our process
174: could be moved from the foreground to the background in the middle of checking
175: if it is in the foreground.
176: The process holds all the stopping signals in this critical section so no other
177: process in our process group can mess us up by blocking us on one of these
178: signals in the middle of our check.
179: (This code assumes that the command interpreter will not move a process from
180: foreground to background without stopping it; if it did we would have
181: no way of making the check correctly.)
182: .PP
183: The routine which handles the signal should clear the catch for the stop
184: signal and
185: .IR kill (2)
186: the processes in its process group with the same signal. The statement
187: after this
188: .I kill
189: will be executed when the process is later continued with SIGCONT.
190: .PP
191: Thus the code for the catch routine might look like:
192: .PP
193: .ft B
194: .nf
195: \&...
196: sigset(SIGTSTP, onstop);
197: sigset(SIGTTIN, onstop);
198: sigset(SIGTTOU, onstop);
199: \&...
200:
201: onstop(signo)
202: int signo;
203: {
204: \fI... restore old terminal state ...\fB
205: sigset(signo, SIG_DFL);
206: kill(0, signo);
207: /* stop here until continued */
208: sigset(signo, onstop);
209: \fI... restore our special terminal state ...\fB
210: }
211: .fi
212: .ft R
213: .PP
214: This routine can also be used to simulate a stop signal.
215: .PP
216: If a process does not need to save and restore state when it is stopped,
217: but wishes to be notified when it is continued after a stop it can catch
218: the SIGCONT signal; the SIGCONT handler will be run when the process
219: is continued.
220: .PP
221: Processes which lock data bases such as the password file should ignore
222: SIGTTIN, SIGTTOU, and SIGTSTP signals while the data bases are being
223: manipulated. While a process is ignoring SIGTTIN signals, reads which
224: would normally have hung will return end-of-file; writes which would
225: normally have caused SIGTTOU signals are instead permitted while SIGTTOU
226: is ignored.
227: .PP
228: .B "Interrupt-level process handling."
229: .PP
230: Using the mechanisms of
231: .IR sigset (3)
232: it is possible to handle process state changes as they occur by providing
233: an interrupt-handling routine for the SIGCHLD signal which occurs
234: whenever the status of a child process changes. A signal handler for this
235: signal is established by:
236: .PP
237: .RS
238: .B "sigset(SIGCHLD, onchild);"
239: .RE
240: .LP
241: The shell or other process would then await a change in child status
242: with code of the form:
243: .PP
244: .nf
245: .ft B
246: recheck:
247: sighold(SIGCHLD); /* start critical section */
248: if (\fIno children to process\fB) {
249: sigpause(SIGCHLD); /* release SIGCHLD and pause */
250: goto recheck;
251: }
252: sigrelse(SIGCHLD); /* end critical region */
253: /* now have a child to process */
254: .fi
255: .ft R
256: .PP
257: Here we are using
258: .IR sighold
259: to temporarily block the SIGCHLD signal during the checking of the
260: data structures telling us whether we have a child to process.
261: If we didn't block the signal we would have a race condition since the
262: signal might corrupt our decision by arriving shortly after we had
263: finished checking the condition but before we paused.
264: .PP
265: If we need to wait for something to happen, we call
266: .I sigpause
267: which automically releases the hold on the SIGCHLD signal and waits for a
268: signal to occur by starting a
269: .IR pause (2).
270: Otherwise we simply release the SIGCHLD signal and process the child.
271: .I Sigpause
272: is similar to the PDP-11
273: .I wait
274: instruction, which returns the priority of the processor to the base
275: level and idles waiting for an interrupt.
276: .PP
277: It is important to note that the long-standing bug in the signal mechanism
278: which would have lost a SIGCHLD signal which occurred while the signal
279: was blocked has been fixed. This is because
280: .I sighold
281: uses the SIG_HOLD signal set of
282: .IR sigsys (2)
283: to prevent the signal action from being taken without losing the signal
284: if it occurs. Similarly, a signal action set with
285: .I sigset
286: has the signal held while the action routine is running,
287: much as a the interrupt priority of the processor is raised when
288: a device interrupt is taken.
289: .PP
290: In this interrupt driven style of termination processing it is necessary
291: that the
292: .I wait
293: calls used to retrieve status in the SIGCHLD signal handler not block.
294: This is because a single invocation of the SIGCHLD handler may indicate
295: an arbitrary number of process status changes: signals are not queued.
296: This is similar to the case in a disk driver where several drives on
297: a single controller may report status at once, while there is only
298: one interrupt taken.
299: It is even possible for no children to be ready to report status when
300: the SIGCHLD handler is invoked, if the signal was posted while the SIGCHLD
301: handler was active, and the child was noticed due to a SIGCHLD initially
302: sent for another process.
303: This causes no problem, since the handler will be called whenever there
304: is work to do; the handler just has to collect all information by calling
305: .I wait3
306: until it says no more information is available.
307: Further status changes are guaranteed to be reflected in another SIGCHLD
308: handler call.
309: .PP
310: .B Restarting system calls.
311: .PP
312: In older versions of UNIX
313: \*(lqslow\*(rq system calls
314: were interrupted when signals occurred,
315: returning EINTR.
316: The new signal mechanism
317: .IR sigset (3)
318: normally restarts such calls
319: rather than interrupting them.
320: To summarize:
321: .I pause
322: and
323: .I wait
324: return error EINTR (as before),
325: .I ioctl
326: and
327: .I wait3
328: restart, and
329: .I read
330: and
331: .I write
332: restart unless some data was read or written in which case they
333: return indicating how much data was read or written.
334: In programs which use the older
335: .IR signal (2)
336: mechanisms,
337: all of these calls return EINTR
338: if a signal occurs during the call.
339: .SH SEE ALSO
340: csh(1), ioctl(2), killpg(2), setpgrp(2), sigsys(2), wait3(2), signal(3),
341: tty(4)
342: .SH BUGS
343: The job control facilities are not available in standard version 7 UNIX.
344: These facilities are still under development and may change in future
345: releases of the system as better inter-process communication facilities
346: and support for virtual terminals become available. The options and
347: specifications of these system calls and even the calls themselves
348: are thus subject to change.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.