argz_create

argz_create

[Jonny Grant]

Hello

https://man7.org/linux/man-pages/man3/argz_create.3.html

BUGS         top
       Argz vectors without a terminating null byte may lead to Segmentation
       Faults.

Doesn't feel like this is a BUG to me. Is there a better section to add this? Almost all string handling functions may cause SEGV if passed a string without a null byte. Or even being passed a NULL ptr like strlen(NULL)..  I expect some of these may crash if passed NULL.


May I ask if there is a way to link error_t to the definition, should be in errno.h

Kind regards
Jonny

Re: argz_create

[Michael Kerrisk (man-pages)]

Hello Jonny,

On 10/26/20 3:18 PM, Jonny Grant wrote:
> Hello
> 
> https://man7.org/linux/man-pages/man3/argz_create.3.html
> 
> BUGS         top
>        Argz vectors without a terminating null byte may lead to Segmentation
>        Faults.
> 
> Doesn't feel like this is a BUG to me. Is there a better section to
> add this? Almost all string handling functions may cause SEGV if
> passed a string without a null byte. Or even being passed a NULL ptr
> like strlen(NULL)..  I expect some of these may crash if passed
> NULL.

Take a look at this paragraph:

       An argz vector is a pointer to a character buffer together with  a
       length.  The intended interpretation of the character buffer is an
       array of strings, where the strings are separated  by  null  bytes
       ('\0').   If  the  length  is nonzero, the last byte of the buffer
       must be a null byte.

These functions have a surprising interface. The 'char **argz'
are pointers to pointers to character buffers that have the form:

    ...\0....\0...\0

That is, the buffers are not strings, but a series of strings laid end
to end. The text you referring to is trying to say that there better
be a '\0' t the end of the buffer... I'm not sure how necessary the
sentence is, but this is not like a typical string handling function.
(Probably 

> May I ask if there is a way to link error_t to the definition, should
> be in errno.h

I don't quite understand what you are suggesting. Can you elaborate.

Thanks,

Michael



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

Re: argz_create

[Michael Kerrisk (man-pages)]

> > May I ask if there is a way to link error_t to the definition, should
> > be in errno.h
>
> I don't quite understand what you are suggesting. Can you elaborate.

Perhaps the patch below suffices to address what you meant(?).

Thanks,

Michael

====

commit 43891c16edf44b794b0ee794ff3add948a3fb22e (HEAD -> master)
Author: Michael Kerrisk <mtk.manpages@gmail.com>
Date:   Mon Oct 26 17:13:33 2020 +0100

    argz_add.3, envz_add.3: Point out that 'error_t' is an integer type

    Reported-by: Jonny Grant <jg@jguk.org>
    Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/argz_add.3 b/man3/argz_add.3
index 40b6eaa5d..bf80e906b 100644
--- a/man3/argz_add.3
+++ b/man3/argz_add.3
@@ -191,7 +191,8 @@ all null bytes (\(aq\e0\(aq) except the last by
 .IR sep .
 .SH RETURN VALUE
 All argz functions that do memory allocation have a return type of
-.IR error_t ,
+.IR error_t
+(an integer type),
 and return 0 for success, and
 .B ENOMEM
 if an allocation error occurs.
diff --git a/man3/envz_add.3 b/man3/envz_add.3
index c360c9604..d4ed0a8be 100644
--- a/man3/envz_add.3
+++ b/man3/envz_add.3
@@ -111,7 +111,8 @@ if there was one.
 removes all entries with value NULL.
 .SH RETURN VALUE
 All envz functions that do memory allocation have a return type of
-.IR error_t ,
+.IR error_t
+(an integer type),
 and return 0 for success, and
 .B ENOMEM
 if an allocation error occurs.


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

Re: argz_create

[Jonny Grant]

On 26/10/2020 16:08, Michael Kerrisk (man-pages) wrote:
> Hello Jonny,
> 
> On 10/26/20 3:18 PM, Jonny Grant wrote:
>> Hello
>>
>> https://man7.org/linux/man-pages/man3/argz_create.3.html
>>
>> BUGS         top
>>        Argz vectors without a terminating null byte may lead to Segmentation
>>        Faults.
>>
>> Doesn't feel like this is a BUG to me. Is there a better section to
>> add this? Almost all string handling functions may cause SEGV if
>> passed a string without a null byte. Or even being passed a NULL ptr
>> like strlen(NULL)..  I expect some of these may crash if passed
>> NULL.
> 
> Take a look at this paragraph:
> 
>        An argz vector is a pointer to a character buffer together with  a
>        length.  The intended interpretation of the character buffer is an
>        array of strings, where the strings are separated  by  null  bytes
>        ('\0').   If  the  length  is nonzero, the last byte of the buffer
>        must be a null byte.
> 
> These functions have a surprising interface. The 'char **argz'
> are pointers to pointers to character buffers that have the form:
> 
>     ...\0....\0...\0
> 
> That is, the buffers are not strings, but a series of strings laid end
> to end. The text you referring to is trying to say that there better
> be a '\0' t the end of the buffer... I'm not sure how necessary the
> sentence is, but this is not like a typical string handling function.
> (Probably 

Yes, it's a kind of serialised buffer right? using the '\0' to denote the end of each.
I'm sure everyone would '\0' terminate the end..

I saw strcpy has a similar warning BUGS, so actually that looks fine.

Jonny

Re: argz_create

[Jonny Grant]

On 26/10/2020 16:16, Michael Kerrisk (man-pages) wrote:
>>> May I ask if there is a way to link error_t to the definition, should
>>> be in errno.h
>>
>> I don't quite understand what you are suggesting. Can you elaborate.
> 
> Perhaps the patch below suffices to address what you meant(?).
> 
> Thanks,
> 
> Michael
> 
> ====
> 
> commit 43891c16edf44b794b0ee794ff3add948a3fb22e (HEAD -> master)
> Author: Michael Kerrisk <mtk.manpages@gmail.com>
> Date:   Mon Oct 26 17:13:33 2020 +0100
> 
>     argz_add.3, envz_add.3: Point out that 'error_t' is an integer type
> 
>     Reported-by: Jonny Grant <jg@jguk.org>
>     Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
> 
> diff --git a/man3/argz_add.3 b/man3/argz_add.3
> index 40b6eaa5d..bf80e906b 100644
> --- a/man3/argz_add.3
> +++ b/man3/argz_add.3
> @@ -191,7 +191,8 @@ all null bytes (\(aq\e0\(aq) except the last by
>  .IR sep .
>  .SH RETURN VALUE
>  All argz functions that do memory allocation have a return type of
> -.IR error_t ,
> +.IR error_t
> +(an integer type),
>  and return 0 for success, and
>  .B ENOMEM
>  if an allocation error occurs.
> diff --git a/man3/envz_add.3 b/man3/envz_add.3
> index c360c9604..d4ed0a8be 100644
> --- a/man3/envz_add.3
> +++ b/man3/envz_add.3
> @@ -111,7 +111,8 @@ if there was one.
>  removes all entries with value NULL.
>  .SH RETURN VALUE
>  All envz functions that do memory allocation have a return type of
> -.IR error_t ,
> +.IR error_t
> +(an integer type),
>  and return 0 for success, and
>  .B ENOMEM
>  if an allocation error occurs.
> 
> 

That's all good thank you for making the update.
I had thought errno_t came from errno.h, but it doesn't, it's only in argp.h and argz.h

Jonny

Re: argz_create

[Jonny Grant]

Hello Mtk

I noticed "nonzero" needs a hyphen "non-zero", could that be changed please?

Also there is a word "nonempty" which isn't a word, and isn't needed I feel :-

"Allocation of nonempty argz vectors is done using
malloc(3), so that free(3) can be used to dispose of them again."

May I ask if that be changed to :-

"Allocation of argz vectors is done using
malloc(3), so that free(3) can be used to dispose of them again."


https://man7.org/linux/man-pages/man3/argz_create.3.html


Kind regards
Jonny

Re: argz_create

[Michael Kerrisk (man-pages)]

On 10/27/20 11:43 AM, Jonny Grant wrote:
> Hello Mtk
> 
> I noticed "nonzero" needs a hyphen "non-zero", could that be changed please?
> 
> Also there is a word "nonempty" which isn't a word, and isn't needed I feel :-

Please see man-pages(7).

Thanks,

Michael



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

Re: argz_create

[Jonny Grant]

On 27/10/2020 13:01, Michael Kerrisk (man-pages) wrote:
> On 10/27/20 11:43 AM, Jonny Grant wrote:
>> Hello Mtk
>>
>> I noticed "nonzero" needs a hyphen "non-zero", could that be changed please?
>>
>> Also there is a word "nonempty" which isn't a word, and isn't needed I feel :-

My proposal was to remove the word "nonempty", rather than replace it.

> Please see man-pages(7).
> 

https://man7.org/linux/man-pages/man7/man-pages.7.html

Yes, I can see those listed there.

Google "non-empty" 1Bn  results
Google "nonempty" 6M results

However "nonempty" is not an English, or American English expression we would ever use. Even "non-empty" isn't English, we'd say "not empty", although in this sentence there is no need to have this at all.

Some are sensible, eg "pathname" is actually typically an argument name, so although it's not an English word, we know what it is. Same with "username" "timezone" etc.

Maybe in another 50 years "nonempty" will be a word, but for now it isn't, so the hyphen is needed. Same as "non-NULL"

How to go about proposing this improvement to man-pages?

Jonny

Re: argz_create

[Michael Kerrisk (man-pages)]

Hello Jonny,


> However "nonempty" is not an English, or American English expression
> we would ever use. Even "non-empty" isn't English, we'd say "not
> empty", although in this sentence there is no need to have this at
> all....
> Maybe in another 50 years "nonempty" will be a word,
> but for now it isn't, so the hyphen is needed. Same as "non-NULL"

But "nonempty" has been a word for a long, long time.
As in "nonempty set", a term you'd use in maths any day.

"non-empty" (with a hyphen) occurs dozens of times in the 
POSIX standard, just to take an example close to home.

Now, one may argue the point about the hyphen, but
re "non" vs "non-" see, for example,
https://www.chicagomanualofstyle.org/qanda/data/faq/topics/HyphensEnDashesEmDashes/faq0079.html

Opinions obviously differ, but the tendency in English
is that thyphens are going away in these cases. I think CMoS
has got it right.

Things like "non-NULL" are exceptional, and it's because
"NULL" is a keyword in C.

Now, as to whether that word "nonempty" is even needed
in that sentence, I am not sure. Presumably the point isto
contrast with the "(NULL,0)" tuple mentioned in the
preceding sentence. In that sense, it's possibly a helpful
word, though I'm not sure it's necessary.

Thanks,

Michael


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