Error message output
dpchrist at holgerdanske.com
Wed Sep 23 03:21:48 UTC 2020
On 2020-09-22 08:31, Polytropon wrote:
> On Mon, 21 Sep 2020 23:33:50 -0700, David Christensen wrote:
>> On 2020-09-21 15:55, Polytropon wrote:
>>> On Mon, 21 Sep 2020 15:33:40 -0700, David Christensen wrote:
>>>> On 2020-09-21 04:21, Polytropon wrote:
>>>>> On Sun, 20 Sep 2020 22:12:24 -0700, David Christensen wrote:
>>>>>> On 2020-09-20 10:11, Polytropon wrote:
>>>>>>> I have a general question. Is it still considered useful to
>>>>>>> output error messages of a script to standard error?
> Programs that operate on a set of
> files typically get them via command line, while programs that
> operate on _one_ file from a set of file often have their "list
> generator" prefixed, like "something | xargs -n 1 progname".
>> My scripts emit '+' in the first position only when they have invoked
>> sh(1) with xtrace enabled. Outputting '+' otherwise is confusing.
> Never heared of that concept...
2020-09-22 17:07:49 dpchrist at f3 ~/sandbox/sh
$ freebsd-version; uname -a
FreeBSD f3.tracy.holgerdanske.com 12.1-RELEASE-p8 FreeBSD
12.1-RELEASE-p8 GENERIC amd64
2020-09-22 17:07:57 dpchrist at f3 ~/sandbox/sh
$ man sh | grep -A 4 xtrace
Write each command (preceded by the value of the PS4
variable subjected to parameter expansion and arithmetic
expansion) to standard error before it is executed. Useful
2020-09-22 17:08:06 dpchrist at f3 ~/sandbox/sh
$ echo $PS4
2020-09-22 17:08:11 dpchrist at f3 ~/sandbox/sh
$ cat freebsd-questions-polytropon-20200922-0831.sh
echo "invoking echo from script"
/bin/sh -x -c 'echo "invoking /bin/sh with xtrace to invoke echo"'
2020-09-22 17:08:17 dpchrist at f3 ~/sandbox/sh
$ /bin/sh freebsd-questions-polytropon-20200922-0831.sh
invoking echo from script
+ echo 'invoking /bin/sh with xtrace to invoke echo'
invoking /bin/sh with xtrace to invoke echo
Things get more interesting when you have scripts calling scripts
calling scripts, etc.. I avoid obfuscating $PS4 / '+'.
> I thought it was good to use "+" for "adding", and "->" for "to
> the result"; maybe "=" or even ":=" would have been possible too,
> even though I tried hard to unlearn ":=". ;-)
Using punctuation for computer code, commands, input, output, etc., is a
mixed blessing. It is concise, but:
1. Too many people have created too many "punctuated languages", each
with different meaning and semantics. A new reader must learn each new
language and an old reader must remember many. Trying to understand one
listing that contains several such languages is a good way to get a
2. Punctuation usually prevents using the output of one program as the
input to another program -- thus breaking the Unix filter/ pipeline model.
Thus, my suggestions of textual/ word prefaces, sending verbose messages
to stderr, and printing bare output file names to stdout. Now you can
pipe the output of png2pdf to xargs(1), which invokes another program
that operates on PDF files.
>> If I wanted to see the input file names as they were processed, I would
>> add a verbose option and preface each input file name with "reading".
>> The messages would to to stderr.
> Or the opposite approach: -q (quiet) if you don't want those.
> Or compare cp to cp -v.
2020-09-22 16:35:29 dpchrist at f3 ~/sandbox/sh
$ touch foo
2020-09-22 16:35:32 dpchrist at f3 ~/sandbox/sh
$ cp foo bar
2020-09-22 16:35:46 dpchrist at f3 ~/sandbox/sh
$ cp -v foo baz
foo -> baz
So, non-verbose cp(1) displays nothing and verbose cp(1) displays both
input and output file names.
But, cp(1) is one-to-one and png2pdf is many-to-one. Emulating the
style of cp(1) with a lot of input files would produce very long lines.
I will stick with my suggestions, above.
>> For exit value, I use 0 for correct operation and 1 for everything else.
> As suggested by sysexits.h, it's possible to signal the kind
> of error to the caller. This is not standard in sh scripts,
> but can be used there.
I use Bourne shell scripts for simple tasks and Perl when I need more.
Generating an error message, dumping the relevant variables, and exiting
with non-zero is usually enough in both cases.
>> Usage: png2pdf.sh [-v] [-q] infile... outfile
>> png2pdf.sh [-v] [-q] [-O outfile] infile...
> That is correct, and the system tools tend to follow that
> convention. Existing man pages and the templates suggest
> this style. Oh, and I should probably write a manpage, too. :-)
FreeBSD usage messages seem to be terse reminders -- the explanations
and details are in the manual pages. I like that style.
If I need a manual page, I don't mind a non-compliant shell script usage
message with extra information. If the program needs a manual page,
it's probably already Perl and I'll use Pod::Usage.
> Thank you for inspiration and further education. It's
> always nice to learn something new or reconsider something
> learned and / or long forgotten.
It's good to discuss these things. :-)
More information about the freebsd-questions