Proposed change to str*.3 man pages

Proposed change to str*.3 man pages

[Keith Thompson]

A number of man pages refer to char* arguments as "strings" rather than as
"pointers to strings".

For example, here's an excerpt from man3/strcmp.3:

    The strcmp() function compares the two strings s1 and s2. 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.

Compare the wording in the ISO C standard:

    The strcmp function compares the string pointed to by s1 to the string
    pointed to by s2.
    ...
    The strcmp function returns an integer greater than, equal to,
    or less than zero, accordingly as the string pointed to by s1 is
    greater than, equal to, or less than the string pointed to by s2.

The Solaris strcmp(3) man page also correctly refers to the arguments
as pointers to strings.

There is a widespread misconception that a char* pointer value
is itself a string, rather than a pointer to a string. See the
definitions in the C standard draft, N1570 7.1.1 paragraph 1,
http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf :

    A *string* is a contiguous sequence of characters terminated by and
    including the first null character. [...] A *pointer to a string*
    is a pointer to its initial (lowest addressed) character.

I haven't checked, but it's likely that there are man pages other than
the str*.3 pages that have this problem. However, I note that man3/fopen.3
correctly refers to "the string pointed to by path".

I'd like to volunteer to produce a patch that correctly refers to these
pointers as pointers rather than as strings -- but it would take a
while, and I don't want to spend the time if the patch is unlikely to
be accepted.

What say you?

-- 
Keith Thompson <Keith.S.Thompson-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Proposed change to str*.3 man pages

[Michael Kerrisk (man-pages)]

Hello Keith,

On 02/16/2016 11:52 PM, Keith Thompson wrote:
> A number of man pages refer to char* arguments as "strings" rather than as
> "pointers to strings".
> 
> For example, here's an excerpt from man3/strcmp.3:
> 
>     The strcmp() function compares the two strings s1 and s2. 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.
> 
> Compare the wording in the ISO C standard:
> 
>     The strcmp function compares the string pointed to by s1 to the string
>     pointed to by s2.
>     ...
>     The strcmp function returns an integer greater than, equal to,
>     or less than zero, accordingly as the string pointed to by s1 is
>     greater than, equal to, or less than the string pointed to by s2.
> 
> The Solaris strcmp(3) man page also correctly refers to the arguments
> as pointers to strings.
> 
> There is a widespread misconception that a char* pointer value
> is itself a string, rather than a pointer to a string.

Is there? Maybe I'm too used to it. But something that declared 
as "type *" seems obviously to me to be a pointer.

> See the
> definitions in the C standard draft, N1570 7.1.1 paragraph 1,
> http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf :
> 
>     A *string* is a contiguous sequence of characters terminated by and
>     including the first null character. [...] A *pointer to a string*
>     is a pointer to its initial (lowest addressed) character.
> 
> I haven't checked, but it's likely that there are man pages other than
> the str*.3 pages that have this problem. However, I note that man3/fopen.3
> correctly refers to "the string pointed to by path".
> 
> I'd like to volunteer to produce a patch that correctly refers to these
> pointers as pointers rather than as strings -- but it would take a
> while, and I don't want to spend the time if the patch is unlikely to
> be accepted.
> 
> What say you?

I suppose that I myself have been guilty of writing such faulty text
as you describe, possibly because it seems obvious to me that "char *"
is a pointer. I'm not so sure this is a big problem, but I 
certainly wouldn't reject patches of this sort, especially for the 
more obvious cases such as described above. And thanks for 
volunteering to look at this. 

I suggest you start by writing one or two patches and sending 
them in, rather than creating a long series at the outset.
Then we can early on determine how far we want to go with this.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html