* Fw: Suggestion for edit
[not found] <MN2PR04MB6157E89BBF15AD9D70DDEA48B9C30@MN2PR04MB6157.namprd04.prod.outlook.com>
@ 2020-04-07 7:07 ` Andrew Micallef
2020-04-07 8:25 ` Ponnuvel Palaniyappan
2020-04-07 9:17 ` AW: " Walter Harms
2020-04-09 9:50 ` Michael Kerrisk (man-pages)
1 sibling, 2 replies; 6+ messages in thread
From: Andrew Micallef @ 2020-04-07 7:07 UTC (permalink / raw)
To: linux-man
Hi,
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)). 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)). 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.
Regards
Andrew
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Fw: Suggestion for edit
2020-04-07 7:07 ` Fw: Suggestion for edit Andrew Micallef
@ 2020-04-07 8:25 ` Ponnuvel Palaniyappan
2020-04-07 9:17 ` AW: " Walter Harms
1 sibling, 0 replies; 6+ messages in thread
From: Ponnuvel Palaniyappan @ 2020-04-07 8:25 UTC (permalink / raw)
To: Andrew Micallef; +Cc: linux-man
Hi,
That part of the description is directly taken from the C standard
(nearly verbatim). It's terse but quite clear though.
Thanks,
Ponnuvel
On Tue, Apr 7, 2020 at 8:08 AM Andrew Micallef
<andrew.micallef@live.com.au> wrote:
>
> Hi,
>
>
> 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)). 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)). 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.
>
>
> Regards
> Andrew
>
--
Regards,
Ponnuvel P
^ permalink raw reply [flat|nested] 6+ messages in thread
* AW: Suggestion for edit
2020-04-07 7:07 ` Fw: Suggestion for edit Andrew Micallef
2020-04-07 8:25 ` Ponnuvel Palaniyappan
@ 2020-04-07 9:17 ` Walter Harms
2020-04-07 9:45 ` Andrew Micallef
1 sibling, 1 reply; 6+ messages in thread
From: Walter Harms @ 2020-04-07 9:17 UTC (permalink / raw)
To: Andrew Micallef, linux-man
hi Andrew, i have to admit that i dropped over the last sentence. And it should be *very* clear what the return means,
ehre my idea:
If both strings are equal the function returns 0.
Otherwises it returns the differences between the last compared characters.
The last feature is important for sorting. I never found a good wording for that.
re,
wh
________________________________________
Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Andrew Micallef <andrew.micallef@live.com.au>
Gesendet: Dienstag, 7. April 2020 09:07:50
An: linux-man@vger.kernel.org
Betreff: Fw: Suggestion for edit
Hi,
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)). 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)). 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.
Regards
Andrew
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Suggestion for edit
2020-04-07 9:17 ` AW: " Walter Harms
@ 2020-04-07 9:45 ` Andrew Micallef
2020-04-07 10:52 ` AW: " Walter Harms
0 siblings, 1 reply; 6+ messages in thread
From: Andrew Micallef @ 2020-04-07 9:45 UTC (permalink / raw)
To: Walter Harms, linux-man
Hi Walter
Actually that new phrasing on the last sentence is much clearer. I was scratching my head over what it meant for a string to be less than (or greater than) another string.
Cheers
Andrew
From: Walter Harms <wharms@bfs.de>
Sent: Tuesday, 7 April 2020 7:17 PM
To: Andrew Micallef <andrew.micallef@live.com.au>; linux-man@vger.kernel.org <linux-man@vger.kernel.org>
Subject: AW: Suggestion for edit
hi Andrew, i have to admit that i dropped over the last sentence. And it should be *very* clear what the return means,
ehre my idea:
If both strings are equal the function returns 0.
Otherwises it returns the differences between the last compared characters.
The last feature is important for sorting. I never found a good wording for that.
re,
wh
________________________________________
Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Andrew Micallef <andrew.micallef@live.com.au>
Gesendet: Dienstag, 7. April 2020 09:07:50
An: linux-man@vger.kernel.org
Betreff: Fw: Suggestion for edit
Hi,
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)). 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)). 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.
Regards
Andrew
^ permalink raw reply [flat|nested] 6+ messages in thread
* AW: Suggestion for edit
2020-04-07 9:45 ` Andrew Micallef
@ 2020-04-07 10:52 ` Walter Harms
0 siblings, 0 replies; 6+ messages in thread
From: Walter Harms @ 2020-04-07 10:52 UTC (permalink / raw)
To: Andrew Micallef, linux-man
the posix page is more direct about 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."
re,
wh
________________________________________
Von: Andrew Micallef <andrew.micallef@live.com.au>
Gesendet: Dienstag, 7. April 2020 11:45:03
An: Walter Harms; linux-man@vger.kernel.org
Betreff: Re: Suggestion for edit
Hi Walter
Actually that new phrasing on the last sentence is much clearer. I was scratching my head over what it meant for a string to be less than (or greater than) another string.
Cheers
Andrew
From: Walter Harms <wharms@bfs.de>
Sent: Tuesday, 7 April 2020 7:17 PM
To: Andrew Micallef <andrew.micallef@live.com.au>; linux-man@vger.kernel.org <linux-man@vger.kernel.org>
Subject: AW: Suggestion for edit
hi Andrew, i have to admit that i dropped over the last sentence. And it should be *very* clear what the return means,
ehre my idea:
If both strings are equal the function returns 0.
Otherwises it returns the differences between the last compared characters.
The last feature is important for sorting. I never found a good wording for that.
re,
wh
________________________________________
Von: linux-man-owner@vger.kernel.org <linux-man-owner@vger.kernel.org> im Auftrag von Andrew Micallef <andrew.micallef@live.com.au>
Gesendet: Dienstag, 7. April 2020 09:07:50
An: linux-man@vger.kernel.org
Betreff: Fw: Suggestion for edit
Hi,
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)). 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)). 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.
Regards
Andrew
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Suggestion for edit
[not found] <MN2PR04MB6157E89BBF15AD9D70DDEA48B9C30@MN2PR04MB6157.namprd04.prod.outlook.com>
2020-04-07 7:07 ` Fw: Suggestion for edit Andrew Micallef
@ 2020-04-09 9:50 ` Michael Kerrisk (man-pages)
1 sibling, 0 replies; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-04-09 9:50 UTC (permalink / raw)
To: Andrew Micallef
Cc: mtk.manpages, linux-man, mtk, Ponnuvel Palaniyappan, walter harms
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/
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-04-09 9:50 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <MN2PR04MB6157E89BBF15AD9D70DDEA48B9C30@MN2PR04MB6157.namprd04.prod.outlook.com>
2020-04-07 7:07 ` Fw: Suggestion for edit Andrew Micallef
2020-04-07 8:25 ` Ponnuvel Palaniyappan
2020-04-07 9:17 ` AW: " Walter Harms
2020-04-07 9:45 ` Andrew Micallef
2020-04-07 10:52 ` AW: " Walter Harms
2020-04-09 9:50 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.