Re: readlink

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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/