diff --git a/src/pv/signal.c b/src/pv/signal.c index 33c1d96..dce5406 100644 --- a/src/pv/signal.c +++ b/src/pv/signal.c @@ -26,14 +26,14 @@ void pv_crs_needreinit(pvcursorstate_t); /* - * Ensure that terminal attribute TOSTOP is set. If we have to set it, - * record that fact by setting "clear_tty_tostop_on_exit" to 1, so that in - * pv_sig_fini() we can turn it back off again. + * Check whether the terminal attribute TOSTOP is set. If it is not, set + * it, and record that fact by setting "clear_tty_tostop_on_exit" to true, + * so that pv_sig_fini() knows to clear it again. * - * In "-c" mode with IPC, then if we have to set TOSTOP, we also tell the - * other PV instances about it via the shared "tty_tostop_added" flag, so - * those instances can set their own on-exit flag, meaning that if any of - * the PV instances set it, the last one to exit will clear it. + * In "-c" mode with IPC, that flag is propagated to other PV instances via + * the shared "tty_tostop_added" flag, so those instances can set their own + * on-exit flag, meaning that if any of the PV instances set it, the last + * one to exit will clear it. */ static void pv_sig_ensure_tty_tostop() { @@ -79,15 +79,15 @@ static void pv_sig_ensure_tty_tostop() /* * Handle SIGTTOU (tty output for background process) by setting the flag to - * suspend writes to stderr, so that we can be stopped and backgrounded - * without messing up the terminal. On a subsequent SIGCONT we will try - * writing to the terminal again, in case we get backgrounded and later get - * foregrounded again. + * suspend writes to stderr, to stop the terminal being interfered with when + * pv is stopped and put into the background. On a subsequent SIGCONT, pv + * will try writing to the terminal again, in case it was put into the + * background and later put into the foreground again. * - * When we get backgrounded and cause a SIGTTOU, the rest of the pipeline - * gets stopped too, so transfers involving pipelines need us to send a - * SIGCONT to the rest of the process group here, otherwise backgrounding - * stops transfers involving pipes. + * When a SIGTTOU is raised, the rest of the pipeline gets stopped too, so + * transfers involving pipelines need pv to send a SIGCONT to the rest of + * the process group here, otherwise backgrounding stops transfers involving + * pipes. */ static void pv_sig_ttou( /*@unused@ */ __attribute__((unused)) int s) @@ -157,8 +157,8 @@ static void pv_sig_cont( /*@unused@ */ __attribute__((unused)) pv_sig_state->flags.terminal_resized = 1; /* - * We can only make the time adjustments if this SIGCONT followed a - * SIGTSTP such that we have a stop time. + * Time adjustments can only be made if this SIGCONT followed a + * SIGTSTP, such that there is a stop-time to measure from. */ if (0 != pv_sig_state->signal.when_tstp_arrived.tv_sec) { @@ -167,10 +167,10 @@ static void pv_sig_cont( /*@unused@ */ __attribute__((unused)) pv_elapsedtime_read(¤t_time); - /* time spent stopped = current time - time SIGTSTP received */ + /* time spent stopped = current time - time SIGTSTP received. */ pv_elapsedtime_subtract(&time_spent_stopped, ¤t_time, &(pv_sig_state->signal.when_tstp_arrived)); - /* add time spent stopped the total stopped-time count */ + /* add time spent stopped to the total stopped-time count. */ pv_elapsedtime_add(&(pv_sig_state->signal.total_stoppage_time), &(pv_sig_state->signal.total_stoppage_time), &time_spent_stopped); @@ -204,13 +204,13 @@ static void pv_sig_cont( /*@unused@ */ __attribute__((unused)) } } - /* reset the SIGTSTP receipt time */ + /* reset the SIGTSTP receipt time. */ pv_elapsedtime_zero(&(pv_sig_state->signal.when_tstp_arrived)); } /* - * Try resuming our use of stderr, if we had suspended it, but only - * if we're now in the foreground. + * Try resuming the use of stderr, if it had been suspended, but + * only if pv is now in the foreground. */ if (1 == pv_sig_state->flags.suspend_stderr) { if (pv_in_foreground()) { @@ -258,8 +258,8 @@ static void pv_sig_term( /*@unused@ */ __attribute__((unused)) #ifdef PV_REMOTE_CONTROL /* - * Handle a SIGUSR2 by setting a flag to say we received it, after recording - * the sending PID. + * Handle a SIGUSR2 by recording the PID that sent it, and setting a flag to + * say it was received. */ static void pv_sig_usr2( /*@unused@ */ __attribute__((unused)) int sig, siginfo_t *info, /*@unused@ */ __attribute__((unused)) @@ -292,8 +292,8 @@ bool pv_sigusr2_received(pvstate_t state, pid_t *pid) /* - * Handle a SIGUSR1 by setting a flag to say we received it, after recording - * the sending PID. + * Handle a SIGUSR1 by recording the PID that sent it, and setting a flag to + * say it was received. */ static void pv_sig_usr1( /*@unused@ */ __attribute__((unused)) int sig, siginfo_t *info, /*@unused@ */ __attribute__((unused)) @@ -330,10 +330,10 @@ bool pv_sigusr1_received(pvstate_t state, pid_t *pid) /* * Handle alarm signals by doing nothing. * - * Note that we have to use a signal handler like this, instead of using - * SIG_IGN, because if we ignore the signal entirely, it does nothing, - * including not interrupting blocking write() calls - which is what we're - * using alarm signals for in the first place. + * An empty signal handler is used, instead of SIG_IGN, because ignoring the + * signal with SIG_IGN prevents it from doing anything at all - meaning it + * would not interrupt blocking write() calls, which is what pv uses alarm + * signals for. */ static void pv_sig_alrm( /*@unused@ */ __attribute__((unused)) int s) @@ -353,10 +353,10 @@ void pv_sig_init(pvstate_t state) memset(&sa, 0, sizeof(sa)); /* - * Note that wherever we use a "struct sigaction", we declare it - * static and explicitly zero it before use, because it may contain - * deeper structures (e.g. "sigset_t") which trigger splint - * warnings about potential memory leaks. + * Wherever a "struct sigaction" is used, it is declared static and + * explicitly zeroed before use, because it may contain deeper + * structures (e.g. "sigset_t") which trigger splint warnings about + * potential memory leaks. */ pv_sig_state = state; @@ -366,14 +366,14 @@ void pv_sig_init(pvstate_t state) pv_elapsedtime_zero(&(pv_sig_state->signal.total_stoppage_time)); /* - * Note that we cast all sigemptyset() and sigaction() return values - * to void, because there's nothing we can reasonably do about any - * conceivable error they may return. + * All sigemptyset() and sigaction() return values are ignored, as + * there is no reasonable action to take about any error they + * return. */ /* - * Ignore SIGPIPE, so we don't die if the output is a pipe and the - * other end closes unexpectedly. + * Ignore SIGPIPE, in case the output is a pipe and the other end + * closes unexpectedly. */ sa.sa_handler = SIG_IGN; (void) sigemptyset(&(sa.sa_mask)); @@ -381,8 +381,9 @@ void pv_sig_init(pvstate_t state) (void) sigaction(SIGPIPE, &sa, &(pv_sig_state->signal.old_sigpipe)); /* - * Handle SIGTTOU by continuing with output switched off, so that we - * can be stopped and backgrounded without messing up the terminal. + * Handle SIGTTOU by continuing with the display switched off, to + * allow pv to be stopped and backgrounded without messing up the + * terminal. */ pv_sig_state->flags.skip_next_sigcont = 0; sa.sa_handler = pv_sig_ttou; @@ -469,13 +470,13 @@ void pv_sig_init(pvstate_t state) /* * Ensure that the TOSTOP terminal attribute is set, so that a - * SIGTTOU signal will be raised if we try to write to the terminal - * while backgrounded (see the SIGTTOU handler above). + * SIGTTOU signal will be raised if pv attempts to write to the + * terminal while backgrounded (see the SIGTTOU handler above). */ pv_sig_ensure_tty_tostop(); /* - * Handle SIGALRM by doing nothing, so we can use alarms or interval + * Handle SIGALRM by doing nothing, allowing alarms or interval * timers to interrupt blocking writes (returning EINTR). */ sa.sa_handler = pv_sig_alrm; @@ -486,10 +487,10 @@ void pv_sig_init(pvstate_t state) /* - * Shut down signal handling. If we had set the TOSTOP terminal attribute, - * and we're in the foreground, also turn that off (though if we're in - * cursor "-c" mode, only do that if we're the last PV instance, otherwise - * leave the terminal alone). + * Shut down signal handling. If this pv had set the TOSTOP terminal + * attribute, and is in the foreground, also turn that off (with the + * restriction that if in cursor "-c" mode, only do that if this is the last + * PV instance, otherwise leave the terminal alone). */ void pv_sig_fini( /*@unused@ */ __attribute__((unused)) pvstate_t state) { @@ -519,10 +520,10 @@ void pv_sig_fini( /*@unused@ */ __attribute__((unused)) pvstate_t state) if (pv_sig_state->control.cursor) { #ifdef HAVE_IPC /* - * We won't clear TOSTOP if other "pv -c" instances - * were still running when pv_crs_fini() ran. + * Don't clear TOSTOP if other "pv -c" instances were still + * running when pv_crs_fini() ran. * - * TODO: we need a better way to determine if we're the last + * TODO: find a better way to determine if this is the last * "pv" left. */ if (pv_sig_state->control.cursor && pv_sig_state->cursor.pvcount > 1) { @@ -530,9 +531,9 @@ void pv_sig_fini( /*@unused@ */ __attribute__((unused)) pvstate_t state) } #else /* !HAVE_IPC */ /* - * Without IPC we can't tell whether the other "pv -c" - * instances in the pipeline have finished so we will just - * have to clear TOSTOP anyway. + * Without IPC there's no way to tell whether other "pv -c" + * instances in the pipeline have finished, so clear TOSTOP + * anyway. */ #endif /* !HAVE_IPC */ } @@ -599,9 +600,10 @@ void pv_sig_allowpause(void) /* - * If we have suspended stderr, check every second or so to see whether we - * can write to the terminal again - this is so that if we get backgrounded, - * then foregrounded again, we start writing to the terminal again. + * If output to stderr is suspended, check once a second whether it is safe + * to write to the terminal. This is so that if pv is put into the + * background, and then brought into the foreground again, it can resume + * terminal output. */ void pv_sig_checkbg(void) {