Use standard input instead of stdin, standard output instead of stdout,
and standard error instead of stderr in messages and documentation.
Inspired by coreutils commit:
https://cgit.git.sv.gnu.org/cgit/coreutils.git/commit/?id=c9a30d6781
* cfg.mk (sc_standard_outputs): Add syntax-check rule.
* doc/find.texi: Do the above.
* find/find.1: Likewise.
* locate/locate.1: Likewise.
* locate/locate.c: Likewise.
* xargs/xargs.1: Likewise.
* xargs/xargs.c: Likewise.
---
cfg.mk | 12 ++++++++++++
doc/find.texi | 45 +++++++++++++++++++++++----------------------
find/find.1 | 2 +-
locate/locate.1 | 5 +++--
locate/locate.c | 2 +-
xargs/xargs.1 | 13 ++++++-------
xargs/xargs.c | 12 ++++++------
7 files changed, 52 insertions(+), 39 deletions(-)
diff --git a/cfg.mk b/cfg.mk
index fcac6b5c..4f963639 100644
--- a/cfg.mk
+++ b/cfg.mk
@@ -299,6 +299,18 @@ sc_spaces_not_tabs:
&& { echo '$(ME): Indent C sources with spaces, not tabs (fix with
build-aux/tabs-to-spaces.sh)' 1>&2; exit 1; } \
|| :
+# Enforce standard references "standard input/output/error".
+sc_standard_outputs:
+ @cd $(srcdir) || exit 1; \
+ GIT_PAGER= git grep -En '_\("[^"]*std(in|out|err)' -- '*/*.c' \
+ && { echo '$@: use "standard ....." in translated strings' 1>&2; \
+ fail=1; } || :; \
+ GIT_PAGER= git grep -En '[^/]std(in|out|err)' -- \
+ '*/*.1' '*/*.5' 'doc/*.texi' \
+ && { echo '$@: use "standard ....." in user docs' 1>&2; \
+ fail=1; } || :; \
+ exit $$fail
+
# Now that we have better tests, make this the default.
export VERBOSE = yes
diff --git a/doc/find.texi b/doc/find.texi
index fd0ebc57..af93f9ed 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -1769,7 +1769,7 @@ you are searching might contain a newline, you should use
@c @item -fls
@c Escaped if @samp{how} is @samp{safe}
@c @item -print
-@c Always quoted if stdout is a tty,
+@c Always quoted if standard output is a tty,
@c @samp{-show-control-chars} is ignored
@c @item -print0
@c Always literal, never escaped
@@ -1782,7 +1782,7 @@ you are searching might contain a newline, you should use
@c If the destination is a tty, the @samp{%f},
@c @samp{%F}, @samp{%h}, @samp{%l}, @samp{%p},
@c and @samp{%P} directives produce quoted
-@c strings if stdout is a tty and are treated
+@c strings if standard output is a tty and are treated
@c literally otherwise.
@c @item -printf
@c As for @code{-fprintf}.
@@ -2811,16 +2811,17 @@ if @code{xargs} is running commands that are waiting
for a response from a
distant network connection, running a few in parallel may reduce the
overall latency by overlapping their waiting time.
-If you are running commands in parallel, you need to think about how
-they should arbitrate access to any resources that they share. For
-example, if more than one of them tries to print to stdout, the output
-will be produced in an indeterminate order (and very likely mixed up)
-unless the processes collaborate in some way to prevent this. Using
-some kind of locking scheme is one way to prevent such problems. In
-general, using a locking scheme will help ensure correct output but
-reduce performance. If you don't want to tolerate the performance
-difference, simply arrange for each process to produce a separate output
-file (or otherwise use separate resources).
+If you are running commands in parallel, you need to think about how they
should
+arbitrate access to any resources that they share.
+For example, if more than one of them tries to print to standard output, the
+output will be produced in an indeterminate order (and very likely mixed up)
+unless the processes collaborate in some way to prevent this.
+Using some kind of locking scheme is one way to prevent such problems.
+In general, using a locking scheme will help ensure correct output but reduce
+performance.
+If you don't want to tolerate the performance difference, simply arrange for
+each process to produce a separate output file (or otherwise use separate
+resources).
@code{xargs} also allows ``turning up'' or ``turning down'' its parallelism
in the middle of a run. Suppose you are keeping your four-processor
@@ -3680,7 +3681,7 @@ database file names. You can also use the environment
variable
option overrides the environment variable if both are used. Empty
elements in @var{path} (that is, a leading or trailing colon, or two
colons in a row) are taken to stand for the default database.
-A database can be supplied on stdin, using @samp{-} as an element
+A database can be supplied on standard input, using @samp{-} as an element
of @samp{path}. If more than one element of @samp{path} is @samp{-},
later instances are ignored (but a warning message is printed).
@@ -3930,8 +3931,8 @@ rejecting this as unrecognized option.
@itemx -a @r{@var{inputfile}}
Read names from the file @var{inputfile} instead of standard input.
If you use this option, the standard input stream remains unchanged
-when commands are run. Otherwise, stdin is redirected from
-@file{/dev/null}.
+when commands are run.
+Otherwise, standard input is redirected from @file{/dev/null}.
@item --null
@itemx -0
@@ -4008,7 +4009,7 @@ case @code{xargs} will exit.
@item --open-tty
@itemx -o
-Reopen stdin as @file{/dev/tty} in the child process before executing
+Reopen standard input as @file{/dev/tty} in the child process before executing
the command, thus allowing that command to be associated to the terminal
while @code{xargs} reads from a different stream, e.g. from a pipe.
This is useful if you want @code{xargs} to run an interactive application.
@@ -4077,7 +4078,7 @@ The options @samp{--max-lines} (@samp{-L}, @samp{-l}),
@samp{--replace}
If some of them are specified at the same time, then @code{xargs} will
generally use the option specified last on the command line, i.e., it will
reset the value of the offending option (given before) to its default value.
-Additionally, @code{xargs} will issue a warning diagnostic on @file{stderr}.
+Additionally, @code{xargs} will issue a warning diagnostic on standard error.
@example
$ seq 4 | xargs -L2 -n3
@@ -4177,7 +4178,7 @@ process creation.
Although GNU @code{xargs} and the implementations on some other platforms
like BSD support the @samp{-o} option to achieve the same, the above is
-the portable way to redirect stdin to @file{/dev/tty}.
+the portable way to redirect standard input to @file{/dev/tty}.
Sometimes, though, it can be helpful to keep the shell process around:
@@ -4276,7 +4277,7 @@ they are units of 1024 bytes.
Setting this variable also turns off warning messages (that is, implies
@samp{-nowarn}) by default, because POSIX requires that apart from
-the output for @samp{-ok}, all messages printed on stderr are
+the output for @samp{-ok}, all messages printed on standard error are
diagnostics and must result in a non-zero exit status.
When @env{POSIXLY_CORRECT} is set, the response to the prompt made by the
@@ -4357,7 +4358,7 @@ nothing). The capitalised @samp{Emacs} on the command
line is used as
Please note that the implementations in GNU @code{xargs} and at least BSD
support the @samp{-o} option as extension to achieve the same, while the
-above is the portable way to redirect stdin to @file{/dev/tty}.
+above is the portable way to redirect standard input to @file{/dev/tty}.
@node Archiving
@section Archiving
@@ -5888,8 +5889,8 @@ If you don't plan to send it those signals, this warning
can be ignored
why @code{xargs} is confused by your operating system).
@item failed to redirect standard input of the child process
-@code{xargs} redirects the stdin stream of the command to be run to either
-@file{/dev/null} or to @file{/dev/tty} for the @samp{-o} option.
+@code{xargs} redirects the standard input stream of the command to be run to
+either @file{/dev/null} or to @file{/dev/tty} for the @samp{-o} option.
See the manual of the system call @code{dup2(2)}.
@end table
diff --git a/find/find.1 b/find/find.1
index adc15282..9f9392b3 100644
--- a/find/find.1
+++ b/find/find.1
@@ -2218,7 +2218,7 @@ warning messages (that is, implies
by default, because POSIX requires that apart from
the output for
.BR \-ok ,
-all messages printed on stderr are diagnostics and must result in a
+all messages printed on standard error are diagnostics and must result in a
non-zero exit status.
.IP
When
diff --git a/locate/locate.1 b/locate/locate.1
index 4e963744..b8fce73a 100644
--- a/locate/locate.1
+++ b/locate/locate.1
@@ -91,8 +91,9 @@ to set the list of database files to search.
The option overrides the environment variable if both are used. Empty
elements in the path are taken to be synonyms for the file name of the
default database.
-A database can be supplied on stdin, using `\-' as an element
-of \fIpath\fP. If more than one element of \fIpath\fP is `\-',
+A database can be supplied on standard input, using `\-' as an element
+of \fIpath\fP.
+If more than one element of \fIpath\fP is `\-',
later instances are ignored (and a warning message is printed).
.IP
The file name database format changed starting with GNU
diff --git a/locate/locate.c b/locate/locate.c
index 9b67e0bb..f4540c0a 100644
--- a/locate/locate.c
+++ b/locate/locate.c
@@ -1756,7 +1756,7 @@ dolocate (int argc, char **argv, int secure_db_fd)
if (did_stdin)
{
error (0, 0,
- _("warning: the locate database can only be read from
stdin once."));
+ _("warning: the locate database can only be read from
standard input once."));
return 0;
}
else
diff --git a/xargs/xargs.1 b/xargs/xargs.1
index 02e17da2..017173a0 100644
--- a/xargs/xargs.1
+++ b/xargs/xargs.1
@@ -63,7 +63,7 @@ option does this for you.
If any invocation of the command exits with a status of 255,
.B xargs
will stop immediately without reading any further input.
-An error message is issued on stderr when this happens.
+An error message is issued on standard error when this happens.
.
.SH OPTIONS
.TP
@@ -81,8 +81,8 @@ The GNU find (and from POSIX Issue 8, IEEE Std 1003.1\-2024)
Read items from
.I file
instead of standard input.
-If you use this option, stdin remains unchanged when commands are run.
-Otherwise, stdin is redirected from
+If you use this option, standard input remains unchanged when commands are run.
+Otherwise, standard input is redirected from
.IR /dev/null .
.TP
@@ -243,7 +243,7 @@ was started).
.B Please note
that it is up to the called processes to properly manage parallel
access to shared resources.
-For example, if more than one of them tries to print to stdout,
+For example, if more than one of them tries to print to standard output,
the output will be produced in an indeterminate order (and very
likely mixed up) unless the processes collaborate in some way to
prevent this.
@@ -255,7 +255,7 @@ arrange for each process to produce a separate output file
(or
otherwise use separate resources).
.TP
.B \-o, \-\-open\-tty
-Reopen stdin as
+Reopen standard input as
.I /dev/tty
in the child process before executing the command.
This is useful if you want
@@ -361,8 +361,7 @@ i.e., it will reset the value of the offending option
(given before)
to its default value.
Additionally,
.B xargs
-will issue a warning diagnostic on
-.IR stderr .
+will issue a warning diagnostic on standard error.
The exception to this rule is that the special
.I max-args
value
diff --git a/xargs/xargs.c b/xargs/xargs.c
index 6af333aa..636ed20c 100644
--- a/xargs/xargs.c
+++ b/xargs/xargs.c
@@ -1156,7 +1156,7 @@ print_args (bool ask)
(i == 0 ? "" : " "),
quotearg_n_style (0, shell_escape_quoting_style,
bc_state.cmd_argv[i])) < 0)
- error (EXIT_FAILURE, errno, _("Failed to write to stderr"));
+ error (EXIT_FAILURE, errno, _("Failed to write to standard error"));
}
if (ask)
@@ -1173,13 +1173,13 @@ print_args (bool ask)
}
fputs ("?...", stderr);
if (fflush (stderr) != 0)
- error (EXIT_FAILURE, errno, _("Failed to write to stderr"));
+ error (EXIT_FAILURE, errno, _("Failed to write to standard error"));
c = savec = getc (tty_stream);
while (c != EOF && c != '\n')
c = getc (tty_stream);
if (EOF == c)
- error (EXIT_FAILURE, errno, _("Failed to read from stdin"));
+ error (EXIT_FAILURE, errno, _("Failed to read from standard input"));
if (savec == 'y' || savec == 'Y')
return true;
}
@@ -1759,9 +1759,9 @@ usage (int status)
HTL (_(" -l[MAX-LINES] similar to -L but defaults to at most
one non-\n"
" blank input line if MAX-LINES is
not specified\n"));
HTL (_(" -n, --max-args=MAX-ARGS use at most MAX-ARGS arguments per
command line\n"));
- HTL (_(" -o, --open-tty Reopen stdin as /dev/tty in the child
process\n"
- " before executing the command;
useful to run an\n"
- " interactive application.\n"));
+ HTL (_(" -o, --open-tty Reopen standard input as /dev/tty in
the child\n"
+ " process before executing the
command; useful to\n"
+ " run an interactive
application.\n"));
HTL (_(" -P, --max-procs=MAX-PROCS run at most MAX-PROCS processes at a
time\n"));
HTL (_(" -p, --interactive prompt before running commands\n"));
HTL (_(" --process-slot-var=VAR set environment variable VAR in child
processes\n"));
--
2.51.1
