From 187712b97b04f3ee6c2137f5b045970d76bb01f0 Mon Sep 17 00:00:00 2001
From: =?utf8?q?P=C3=A1draig=20Brady?= <P@draigBrady.com>
Date: Tue, 26 Jul 2022 14:10:59 +0100
Subject: [PATCH] doc: env: clarify that empty signal args are ignored

It's useful to treat empty and missing arguments differently.
Missing means all signals, while empty means no signals and
so is a no-op.  It's useful to treat empty arguments like
this, so that dynamically specified arguments like the following
are supported

  env --ignore-signals "$SIGS_TO_IGNORE"

Note `env --ignore-signals=` is treated as an empty argument.

* doc/coreutils.texi (env invocation): Empty args are treated
differently to missing arguments, so call that out explicitly.
* src/env.c (usage): Likewise.
Addresses https://bugs.debian.org/1016049
---
 doc/coreutils.texi | 16 +++++++++-------
 src/env.c          |  2 +-
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 53257f7d9f..d441012737 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -17574,9 +17574,9 @@ env --chdir=/build FOO=bar timeout 5 true
 @item --default-signal[=@var{sig}]
 Unblock and reset signal @var{sig} to its default signal handler.
 Without @var{sig} all known signals are unblocked and reset to their defaults.
-Multiple signals can be comma-separated.  The following command runs
-@command{seq} with SIGINT and SIGPIPE set to their default
-(which is to terminate the program):
+Multiple signals can be comma-separated. An empty @var{sig} argument is a no-op.
+The following command runs @command{seq} with SIGINT and SIGPIPE set to their
+default (which is to terminate the program):
 
 @example
 env --default-signal=PIPE,INT seq 1000 | head -n1
@@ -17603,9 +17603,9 @@ trap '' PIPE && sh -c 'env --default-signal=PIPE seq inf | head -n1'
 
 @item --ignore-signal[=@var{sig}]
 Ignore signal @var{sig} when running a program.  Without @var{sig} all
-known signals are set to ignore.  Multiple signals can be
-comma-separated.  The following command runs @command{seq} with SIGINT set
-to be ignored - pressing @kbd{Ctrl-C} will not terminate it:
+known signals are set to ignore.  Multiple signals can be comma-separated.
+An empty @var{sig} argument is a no-op. The following command runs @command{seq}
+with SIGINT set to be ignored - pressing @kbd{Ctrl-C} will not terminate it:
 
 @example
 env --ignore-signal=INT seq inf > /dev/null
@@ -17627,7 +17627,9 @@ env --default-signal=INT,PIPE --ignore-signal=INT
 @end example
 
 @item --block-signal[=@var{sig}]
-Block signal(s) @var{sig} from being delivered.
+Block signal(s) @var{sig} from being delivered.  Without @var{sig} all
+known signals are set to blocked.  Multiple signals can be comma-separated.
+An empty @var{sig} argument is a no-op.
 
 @item --list-signal-handling
 List blocked or ignored signals to standard error, before executing a command.
diff --git a/src/env.c b/src/env.c
index f7ef297e7f..1bd2163da7 100644
--- a/src/env.c
+++ b/src/env.c
@@ -158,7 +158,7 @@ A mere - implies -i.  If no COMMAND, print the resulting environment.\n\
 \n\
 SIG may be a signal name like 'PIPE', or a signal number like '13'.\n\
 Without SIG, all known signals are included.  Multiple signals can be\n\
-comma-separated.\n\
+comma-separated.  An empty SIG argument is a no-op.\n\
 "), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
-- 
2.47.2