Re: Suggestion for edit

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hello Andrew,

On 4/7/20 6:06 AM, Andrew Micallef wrote:
> Hi Michael,
> 
> I'd like to suggest an edit to the description of `strcmp` in the standard C library man page.
> I found this description to be kind of confusing, and think the language could be a bit more
> straight forward.
>  At present the description reads as follows:
> 
> The strcmp() function compares the two strings s1 and s2.  The locale
>        is not taken into account (for a locale-aware comparison, see
>        strcoll(3)<http://man7.org/linux/man-pages/man3/strcoll.3.html>).
>        It returns an integer less than, equal to, or greater
>        than zero if s1 is found, respectively, to be less than, to match, or
>        be greater than s2.
> 
> I am suggesting the following edits:
> 
> The strcmp() function compares the two strings s1 and s2.  The locale
>        is not taken into account (for a locale-aware comparison, see
>        strcoll(3)<http://man7.org/linux/man-pages/man3/strcoll.3.html>).
>        It returns an integer, which is 0 if the strings
>        match. Otherwise, a negative integer indicates s1 is less than s2,
>        while a positive integer indicates s1 is greater than s2.

As Ponnuvel points out, the text pretty much matches POSIX. It is terse,
and clear. But also not so easy to parse, at least for some of us.

Furthermore, the text is essentially repeated twice in the page,
once in DESCRIPTION and then again in RETURN VALUE. Let's fix one of
those in the direction you suggest.

Also, I like Walter's suggestion of mentioning the arithmetic
difference.

How about this:

DESCRIPTION
       The  strcmp()  function  compares  the two strings s1 and s2.  The
       locale is not taken into account (for a  locale-aware  comparison,
       see  strcoll(3)).   The  comparison is done using unsigned charac‐
       ters.

*      strcmp() returns an integer indicating the result of the  compari‐
*       son, as follows:
*
*      · 0, if the s1 and s2 are equal;
*
*      · a negative value if s1 is less than s2;
*
*      · a positive value if s1 is greater than s2;

       The  strncmp()  function  is  similar, except it compares only the
       first (at most) n bytes of s1 and s2.

RETURN VALUE
       The strcmp() and strncmp() functions return an integer less  than,
       equal  to,  or  greater  than  zero  if  s1  (or the first n bytes
       thereof) is found, respectively, to be less than, to match, or  be
       greater than s2.

...

NOTES
*      POSIX.1 specifies only that:
*            The sign of a non-zero return value shall be determined  by
*             the  sign of the difference between the values of the first
*             pair of bytes (both interpreted as type unsigned char) that
*             differ in the strings being compared.
*
*      In  glibc,  as  in most other implementations, the return value is
*      the arithmetic result of subtracting the last  compared  character
*      in s2 from the last compared character in s1.  (If the two charac‐
*      ters are equal, this difference is 0.)

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/