From da929c450532a79a54e125400a475a26a4c58c65 Mon Sep 17 00:00:00 2001 From: Martijn Dekker Date: Thu, 4 Nov 2021 15:43:50 +0000 Subject: [PATCH] Comments: document job control flags (re: 41ebb55a) The functions of the three flags controlling job control are crucial to understand in order to maintain the code, so they should be documented in the comments and not just in the git log. This commit does not change any code. --- src/cmd/ksh93/include/jobs.h | 2 +- src/cmd/ksh93/sh/jobs.c | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/src/cmd/ksh93/include/jobs.h b/src/cmd/ksh93/include/jobs.h index b9dabac35..d1945352e 100644 --- a/src/cmd/ksh93/include/jobs.h +++ b/src/cmd/ksh93/include/jobs.h @@ -97,7 +97,7 @@ struct jobs int suspend; /* suspend character */ int linedisc; /* line discipline */ #endif /* JOBS */ - char jobcontrol; /* turned on for real job control */ + char jobcontrol; /* turned on for interactive shell with control of terminal */ char waitsafe; /* wait will not block */ char waitall; /* wait for all jobs in pipe */ char toclear; /* job table needs clearing */ diff --git a/src/cmd/ksh93/sh/jobs.c b/src/cmd/ksh93/sh/jobs.c index 55e244af9..060194b55 100644 --- a/src/cmd/ksh93/sh/jobs.c +++ b/src/cmd/ksh93/sh/jobs.c @@ -29,6 +29,26 @@ * Rewritten April, 1988 * Revised January, 1992 * Mended February, 2021 + * + * Aspects of job control are (de)activated using a global flag variable, + * a state bit, and a shell option bit. It is important to understand the + * difference and set/check them in a manner consistent with their purpose. + * + * 1. The job.jobcontrol flag is for job control on interactive shells. + * It is set to nonzero by job_init() if, and only if, the shell is + * interactive *and* managed to get control of the terminal. Therefore, + * any changing of terminal settings (tcsetpgrp(3), tty_set()) should + * only be done if job.jobcontrol is nonzero. + * + * 2. The state flag, sh_isstate(SH_MONITOR), determines whether the bits + * of job control that are relevant for both scripts and interactive + * shells are active, which is mostly making sure that a background job + * gets its own process group (setpgid(3)). + * + * 3. The -m (-o monitor) shell option, sh_isoption(SH_MONITOR), is just + * that. When the user turns it on or off, the state flag is synched + * with it. It should usually not be directly checked for, as the state + * may be temporarily turned off without turning off the option. */ #include "defs.h"