* readlink
@ 2020-12-24 17:52 Jonny Grant
2020-12-30 13:56 ` readlink Michael Kerrisk (man-pages)
0 siblings, 1 reply; 3+ messages in thread
From: Jonny Grant @ 2020-12-24 17:52 UTC (permalink / raw)
To: linux-man; +Cc: Michael Kerrisk
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
^ permalink raw reply [flat|nested] 3+ messages in thread* Re: readlink 2020-12-24 17:52 readlink Jonny Grant @ 2020-12-30 13:56 ` Michael Kerrisk (man-pages) 2021-01-02 21:15 ` readlink Jonny Grant 0 siblings, 1 reply; 3+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-12-30 13:56 UTC (permalink / raw) To: Jonny Grant, linux-man; +Cc: mtk.manpages 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/ ^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: readlink 2020-12-30 13:56 ` readlink Michael Kerrisk (man-pages) @ 2021-01-02 21:15 ` Jonny Grant 0 siblings, 0 replies; 3+ messages in thread From: Jonny Grant @ 2021-01-02 21:15 UTC (permalink / raw) To: Michael Kerrisk (man-pages), linux-man 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 ^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2021-01-02 21:16 UTC | newest] Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-12-24 17:52 readlink Jonny Grant 2020-12-30 13:56 ` readlink Michael Kerrisk (man-pages) 2021-01-02 21:15 ` readlink Jonny Grant
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).