grep: Misleading Description of '-s' Option in Man Page

[MARSHALL Keith]

Here's the description of grep's '-s' option, abstracted from the
man page on my Mandrake 8.2 system.

    -s, --no-messages
           Suppress   error   messages  about  nonexistent  or
           unreadable files.   Portability  note:  unlike  GNU
           grep,  traditional grep did not conform to POSIX.2,
           because traditional grep lacked a -q option and its
           -s option behaved like GNU grep's -q option.  Shell
           scripts intended to be portable to traditional grep
           should  avoid  both  -q  and -s and should redirect
           output to /dev/null instead.

Alas, this is both inaccurate and misleading.

In UNIX System V Release 3, which has a traditional implementation
of grep, the -s option does nothing more than suppress any error
messages relating to nonexistent or unreadable files; it does *not*
behave, in any other way, like GNU grep's -q option; the *only* way
to suppress output from traditional grep is to redirect both stdout
and stderr to /dev/null.

Here's an example of why this misleading documentation needs to be
corrected.  From the configure script shipped with man-1.5m2 ...

    echo $n "Testing whether grep needs -s or -q ... " $c
    ogrep=`echo hoi | grep -s hoi`
    if [ -z "$ogrep" ]
    then
        grepsilent=s
    else
        grepsilent=q
    fi
    echo "-$grepsilent"

The presumption here is that 'grep -s hoi' will produce no visible
output, when -s behaves as GNU grep's -q, in which case 'grep -s'
will be a silent grep, otherwise 'grep -q' should be used. Seems
a reasonable assumption, on the basis of the 'portability note' in
the man page, but unfortunately, it just doesn't work like this with
traditional grep. On SunOS 5.5.1, which I believe actually conforms
to SVR4, but still appears to have a traditional grep ...

    ogrep=`echo hoi | grep -s hoi`

sets 'ogrep=hoi'.  Thus

    if [ -z "$ogrep" ]

tests 'false', resulting in the assignment

    grepsilent=q

and the silent grep becomes 'grep -q' -- not good, since this grep
does not support the -q option, and *always* aborts with an 'invalid
option' exception, and a non-zero exit code, which is in no way
related to the test we were actually trying to perform.

Best regards,
Keith.