readlink

readlink

[Jonny Grant]

Seasons greetings Michael,

May I ask, could readlink be updated to use the same wording for null termination like on sprintf, scanf etc?

https://man7.org/linux/man-pages/man2/readlink.2.html

It says:
 "readlink() does not append a null byte to buf"

Perhaps it should say:
 "readlink() does not append a terminating null byte to buf ('\0')"

In addition, is it worth adding a BUGS section to remind that there is no terminating null byte?

"readlink() assumes the caller understands that no terminating null byte ('\0') will be written in the provided buf. If the caller didn't memset the buffer to ('\0') or allocate an extra byte for the terminating null byte, there is a risk the caller could overrun the end of the buffer, or use uninitialised values in the buf."

Finally, perhaps also the EXAMPLES program could be updated to clarify this:

"/* print only nbytes of buf, as it doesn't contain a terminating null byte ('\0') */
printf("'%s' points to '%.*s'\n", argv[1], (int) nbytes, buf);
"

Kind regards
Jonny

Re: readlink

[Michael Kerrisk (man-pages)]

Hello Jonny,

On 12/24/20 6:52 PM, Jonny Grant wrote:
> Seasons greetings Michael,
> 
> May I ask, could readlink be updated to use the same wording for null
> termination like on sprintf, scanf etc?
> 
> https://man7.org/linux/man-pages/man2/readlink.2.html
> 
> It says:
>  "readlink() does not append a null byte to buf"
> 
> Perhaps it should say:
>  "readlink() does not append a terminating null byte to buf ('\0')"
> 
> In addition, is it worth adding a BUGS section to remind that there
> is no terminating null byte?
> 
> "readlink() assumes the caller understands that no terminating null
> byte ('\0') will be written in the provided buf. If the caller didn't
> memset the buffer to ('\0') or allocate an extra byte for the
> terminating null byte, there is a risk the caller could overrun the
> end of the buffer, or use uninitialised values in the buf."

> 
> Finally, perhaps also the EXAMPLES program could be updated to clarify this:
> 
> "/* print only nbytes of buf, as it doesn't contain a terminating null byte ('\0') */
> printf("'%s' points to '%.*s'\n", argv[1], (int) nbytes, buf);
> "

I think that having (1) the existing statement at the start of the 
DESCRIPTION, (2) adding a comment to the code, and (3) adding a BUGS
section all to cover the same point seems a little excessive.
I've gone for 2 out of 3.

Thanks,

Michael

--- a/man2/readlink.2
+++ b/man2/readlink.2
@@ -93,7 +93,7 @@ in the buffer
 which has size
 .IR bufsiz .
 .BR readlink ()
-does not append a null byte to
+does not append a terminating null byte to
 .IR buf .
 It will (silently) truncate the contents (to a length of
 .I bufsiz
@@ -332,6 +332,8 @@ main(int argc, char *argv[])
         exit(EXIT_FAILURE);
     }
 
+    /* Print only \(aqnbytes\(aq of \(aqbuf\(aq, as it doesn't contain a terminating
+       null byte (\(aq\e0\(aq). */
     printf("\(aq%s\(aq points to \(aq%.*s\(aq\en", argv[1], (int) nbytes, buf);
 
     /* If the return value was equal to the buffer size, then the


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

Re: readlink

[Jonny Grant]

On 30/12/2020 13:56, Michael Kerrisk (man-pages) wrote:
> Hello Jonny,
> 
> On 12/24/20 6:52 PM, Jonny Grant wrote:
>> Seasons greetings Michael,
>>
>> May I ask, could readlink be updated to use the same wording for null
>> termination like on sprintf, scanf etc?
>>
>> https://man7.org/linux/man-pages/man2/readlink.2.html
>>
>> It says:
>>  "readlink() does not append a null byte to buf"
>>
>> Perhaps it should say:
>>  "readlink() does not append a terminating null byte to buf ('\0')"
>>
>> In addition, is it worth adding a BUGS section to remind that there
>> is no terminating null byte?
>>
>> "readlink() assumes the caller understands that no terminating null
>> byte ('\0') will be written in the provided buf. If the caller didn't
>> memset the buffer to ('\0') or allocate an extra byte for the
>> terminating null byte, there is a risk the caller could overrun the
>> end of the buffer, or use uninitialised values in the buf."
> 
>>
>> Finally, perhaps also the EXAMPLES program could be updated to clarify this:
>>
>> "/* print only nbytes of buf, as it doesn't contain a terminating null byte ('\0') */
>> printf("'%s' points to '%.*s'\n", argv[1], (int) nbytes, buf);
>> "
> 
> I think that having (1) the existing statement at the start of the 
> DESCRIPTION, (2) adding a comment to the code, and (3) adding a BUGS
> section all to cover the same point seems a little excessive.
> I've gone for 2 out of 3.
> 
> Thanks,
> 
> Michael
> 
> --- a/man2/readlink.2
> +++ b/man2/readlink.2
> @@ -93,7 +93,7 @@ in the buffer
>  which has size
>  .IR bufsiz .
>  .BR readlink ()
> -does not append a null byte to
> +does not append a terminating null byte to
>  .IR buf .
>  It will (silently) truncate the contents (to a length of
>  .I bufsiz
> @@ -332,6 +332,8 @@ main(int argc, char *argv[])
>          exit(EXIT_FAILURE);
>      }
>  
> +    /* Print only \(aqnbytes\(aq of \(aqbuf\(aq, as it doesn't contain a terminating
> +       null byte (\(aq\e0\(aq). */
>      printf("\(aq%s\(aq points to \(aq%.*s\(aq\en", argv[1], (int) nbytes, buf);
>  
>      /* If the return value was equal to the buffer size, then the
> 
> 

Looks good, thank you.
Jonny