Re: readlink

[Jonny Grant <jg@jguk.org>]

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