setterm: Document behavior of redirection

Debugging an error of setterm, I realized that setterm --powerdown operates
on stdout but setterm --powersave operates on stdin. Such unexpected
behavior should be documented.

I prefer a less accurate generic "always redirect both stdin and stdout"
over recommending of the correct I/O stream for each option separately.

Signed-off-by: Stanislav Brabec <sbrabec@suse.cz>

diff --git a/term-utils/setterm.1.adoc b/term-utils/setterm.1.adoc
index 880fe10d631bd13e7c4b4c2919a57ae17fdcb12f..365c4bb0092e9720b5fa00f5e6fa4aca3447886a 100644 (file)
--- a/term-utils/setterm.1.adoc
+++ b/term-utils/setterm.1.adoc
@@ -156,6 +156,10 @@ Turns underline mode on or off.
 
 include::man-common/help-version.adoc[]
 
+== WARNING
+
+Use of *setterm* in combination with stdout redirection can have unexpected results, as some options operate on stdin. To prevent problems, always redirect both stdin and stdout to the same device.
+
 == COMPATIBILITY
 
 Since version 2.25 *setterm* has support for long options with two hyphens, for example *--help*, beside the historical long options with a single hyphen, for example *-help*. In scripts it is better to use the backward-compatible single hyphen rather than the double hyphen. Currently there are no plans nor good reasons to discontinue single-hyphen compatibility.