aboutsummaryrefslogtreecommitdiffstats
path: root/man7/string_copying.7
AgeCommit message (Collapse)AuthorFilesLines
2024-05-02man/, share/mk/: Move man*/ to man/Alejandro Colomar1-767/+0
This is a scripted change: $ mkdir man/; $ mv man* man/; $ ln -st . man/man*; $ find share/mk/ -type f \ | xargs grep -l '^MANDIR *:=' \ | xargs sed -i '/^MANDIR *:=/s,$,/man,'; $ find share/mk/dist/ -type f \ | xargs grep -l man \ | xargs sed -i 's,man%,man/%,g'; Link: <https://lore.kernel.org/linux-man/YxcV4h+Xn7cd6+q2@pevik/T/> Cc: Petr Vorel <pvorel@suse.cz> Cc: Jakub Wilk <jwilk@jwilk.net> Cc: Stefan Puiu <stefan.puiu@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-17string_copying.7: EXAMPLES: st[rp]ncpy(3): Use fwrite(3) instead of a loopAlejandro Colomar1-4/+2
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-17string_copying.7: Use NITEMS() instead of sizeof()Alejandro Colomar1-14/+14
For these byte functions, sizeof() works as well as NITEMS(), since CHAR_BIT == 1. However, equivalent wide-character functions need NITEMS(), which is semantically more appropriate, and also safer (it cannot be applied to pointers). Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-17string_copying.7: EXAMPLES: Update stpecpy() exampleAlejandro Colomar1-2/+2
The function was changed recently to return NULL on truncation; update the example of use accordingly. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-17string_copying.7: stpecpy(): Reimplement as a wrapper of strtcpy()Alejandro Colomar1-16/+3
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-17string_copying.7: stpecpy(): Return NULL on truncationAlejandro Colomar1-19/+19
This makes it simpler to test the return value, and since it sets errno to find out the reason, we don't need a complex return value. Now that (dst == end) shouldn't happen, use ENOBUFS to report that error. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-17string_copying.7: stpecpy(), strtcpy(): Set errno on failureAlejandro Colomar1-4/+36
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-05string_copying.7: wfixAlejandro Colomar1-1/+3
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-05string_copying.7: Generalize null-padded character sequences with strnlen(3)Alejandro Colomar1-12/+7
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Be consistent in the use of null byte and null characterAlejandro Colomar1-12/+13
Null character, for the terminating character of a string. Null byte, for the padding. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Don't say 'size' when 'len' is meantAlejandro Colomar1-6/+6
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Say 'known-length' for character sequences whose length is ↵Alejandro Colomar1-10/+10
known Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Don't say 'width' when 'size' is meantAlejandro Colomar1-9/+9
Reported-by: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: RETURN VALUE: Remove some confusing text about stpncpy(3)Alejandro Colomar1-7/+2
That text could lead someone to think that it's possible to check truncation from the return value, but it isn't. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Consistently list strtcpy() after stpecpy()Alejandro Colomar1-43/+43
And put it next to strlcpy(3bsd), which is very similar to strtcpy(). Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: stpecpy() and strtcpy() don't exist in man3Alejandro Colomar1-19/+19
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Use fwrite(3) to print character sequencesAlejandro Colomar1-2/+2
Suggested-by: Paul Eggert <eggert@cs.ucla.edu> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: tfixAlejandro Colomar1-1/+1
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Use real examples with utmp(5)Alejandro Colomar1-22/+16
For the functions that are designed to be used with utmp(5) or similar APIs, use utmp(5) in the example, which results in a clearer example, and also more realistic. It better clarifies how these functions are to be used. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Improve strncat(3) exampleAlejandro Colomar1-4/+5
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Reimplement stpecpy()Alejandro Colomar1-8/+9
This implementation resembles more strtcpy(), so the differences are more visible. Also, it has no -1's, so it's a bit easier to implement correctly. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Remove zustr2stp()Alejandro Colomar1-46/+13
Instead, document how to use mempcpy(3) well in that case. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-04string_copying.7: Remove zustr2ustp()Alejandro Colomar1-39/+10
Instead, document how to use mempcpy(3) well in that case. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-03string_copying.7: Remove ustr2stp() and ustpcpy()Alejandro Colomar1-67/+23
Users reported complains about having so many invented functions, and the complexity of remembering all of them. In these two cases, open-coding mempcpy(3) isn't so bad. In fact, it's quite readable. It has the problem of type safety, since this function accepts almost everything, but let users come up with a wrapper if they need it; it's not like you would be calling these functions often. Document how to use mempcpy(3) well in those cases. Cc: "Serge E. Hallyn" <serge@hallyn.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-12-03string_copying.7: Fortify source of some functionsAlejandro Colomar1-17/+4
By setting the terminating null byte via a stpcpy(dst, "") call, the last byte is also protected by _FORTIFY_SOURCE. Reported-by: "Serge E. Hallyn" <serge@hallyn.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-13string_copying.7: Recommend failing instead of truncatingAlejandro Colomar1-1/+4
Especially for validating input, code should fail, not truncate. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-13string_copying.7: Use 'dsize' and 'ssize' for 'dst size' and 'src size'Alejandro Colomar1-25/+25
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: Add strtcpy(3)Alejandro Colomar1-29/+68
Add this new truncating string-copying function. It intends to fully replace strlcpy(3), which has important bugs (documented in the preceeding commit). It is almost identical to Linux kernel's strscpy(9), so reduce the documentation of strscpy(9) in this page to the minimum, giving preference to strtcpy(3). Provide a reference implementation, since no libc provides it. Providing an easy, safe, and relatively fast truncating string-copying function should prevent users from rolling their own, in which they might introduce bugs accidentally. We already made enough mistakes while discussing these functions, so it's certainly not something that should be written often. Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Stefan Puiu <stefan.puiu@gmail.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Cc: Guillem Jover <guillem@hadrons.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: BUGS: Document strl{cpy,cat}(3)'s performance problemsAlejandro Colomar1-1/+17
Also point to BUGS from other sections that talk about these functions. These functions are doomed due to the design decision of mirroring snprintf(3)'s return value. They must return strlen(src), which makes them terribly slow, and vulnerable to DoS if an attacker can control strlen(src). A better design would have been to return -1 when truncating. Reported-by: Paul Eggert <eggert@cs.ucla.edu> Cc: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Stefan Puiu <stefan.puiu@gmail.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Cc: Guillem Jover <guillem@hadrons.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: BUGS: *cat(3) functions aren't always badAlejandro Colomar1-0/+6
The compiler will sometimes optimize them to normal *cpy(3) functions, since the length of dst is usually known, if the previous *cpy(3) is visible to the compiler. And they provide for cleaner code. If you know that they'll get optimized, you could use them. Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Stefan Puiu <stefan.puiu@gmail.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: wfixAlejandro Colomar1-4/+4
Don't start this paragraph with a fragment. Also, remove "by nature", which is superfluous. Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: DESCRIPTION::Functions: ustpcpy() and ustr2stp() are not ↵Alejandro Colomar1-0/+6
provided by any libc Reported-by: Jonny Grant <jg@jguk.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: RETURN VALUE: ffixAlejandro Colomar1-42/+28
Put the text after the function names, like the rest of the page. Suggested-by: Jonny Grant <jg@jguk.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-12string_copying.7: wfixAlejandro Colomar1-15/+15
Remove superfluous words. Suggested-by: Jonny Grant <jg@jguk.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-09stpncpy.3, string.3, string_copying.7: Clarify that st[rp]ncpy() pad with ↵Alejandro Colomar1-1/+2
null bytes The previous wording could be interpreted as if the nulls were already in place. Clarify that it's this function which pads with null bytes. Also, it copies "characters" from the src string. That's a bit more specific than copying "bytes", and makes it clearer that the terminating null byte in src is not part of the copy. Suggested-by: Jonny Grant <jg@jguk.org> Cc: DJ Delorie <dj@redhat.com> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Xi Ruoyao <xry111@xry111.site> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-11-09stpncpy.3, string_copying.7: Clarify that st[rp]ncpy() do NOT produce a stringAlejandro Colomar1-10/+10
These copy *from* a string. But the destination is a simple character sequence within an array; not a string. Suggested-by: DJ Delorie <dj@redhat.com> Acked-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Cc: Jonny Grant <jg@jguk.org> Cc: Matthew House <mattlloydhouse@gmail.com> Cc: Thorsten Kukuk <kukuk@suse.com> Cc: Adhemerval Zanella Netto <adhemerval.zanella@linaro.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Xi Ruoyao <xry111@xry111.site> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-10-31man*/: srcfix (Use .P instead of .PP or .LP)Alejandro Colomar1-32/+32
We're trying to "standardize" on a paragraphing macro from the three equivalent ones (P, PP, LP). We (somewhat arbitrarily) agreed on P. Scripted change: $ find man* -type f | xargs sed -i '/\.PP/s/PP/P/' $ find man* -type f | xargs sed -i '/\.LP/s/LP/P/' Suggested-by: "G. Branden Robinson" <branden@debian.org> Cc: Ingo Schwarze <schwarze@openbsd.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-10-12string_copying.7: Clarify 'ustr' and 'zustr'Alejandro Colomar1-0/+7
Suggested-by: "Serge E. Hallyn" <serge@hallyn.com> Acked-by: "Serge E. Hallyn" <serge@hallyn.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-08-29strcpy.3, strncat.3, string_copying.7: tfixAlejandro Colomar1-1/+1
Remove non-breaking space (0xC2A0) that accidentally landed in the source of some string pages. Replace by a normal space (0x20). Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-07-29string_copying.7: tfixLennart Jablonka1-11/+11
On some of the commas: There are a few of instances of Subject verb object partclause, advphrase. For example: This function catenates the input character sequence | subject | verb | object | contained in a null-padded wixed-width buffer, | participial clause | into a destination string. | adverbial phrase | Imagining the participial clause away, there shouldn't be a comma preceding the restrictive adverbial phrase: The input character sequence is really, always catenated into a destination string; that is essential. For example: This function catenates the input character sequence into a destination string. The participial clause, being non-restrictive---there is but one input character sequence that could be meant---, should be enclosed by commas. That is the existing comma's purpose and doesn't work without the added, first comma. Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Lennart Jablonka <humm@ljabl.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-07-29string_copying.7: don't grant strl{cpy,cat} magicLennart Jablonka1-5/+1
A function can't check whether a pointer points to the start of a string. What it certainly can do is to keep reading until you either find a null byte or read the secret key that lies adjacent in memory and post it to your favorite mailing list. strlcpy and strlcat behave the exact same way any other function accepting a string behaves: If you don't pass a string, the behavior is undefined. And that, I believe, does not deserve a special mention here, seeing as all the other string functions don't get such a mention either. Link: <https://lore.kernel.org/linux-man/ZMQVYtquNN-s0IJr@beryllium/T/#u> Signed-off-by: Lennart Jablonka <humm@ljabl.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-07-28man*/: srcfixG. Branden Robinson1-2/+2
[Clean up in preparation for "MR sed".] Drop spurious, nilpotent uses of *roff `\c` escape sequence. Quoting groff_man_style(7): \c End a text line without inserting space or attempting a break. Normally, if filling is enabled, the end of a text line is treated like a space; an output line _may_ be broken there (if not, an adjustable space is inserted); if filling is disabled, the line _will_ be broken there, as in .EX/.EE examples. The next line is interpreted as usual and can include a macro call (contrast with \newline). \c is useful when three font styles are needed in a single word, as in a command synopsis. Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-05-03man*/, man.ignore.grep: srcfix; warn about blank linesAlejandro Colomar1-12/+12
- Use the dummy character to avoid warnings in examples. - Re-enable the warning. Suggested-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-04-29man*/: srcfixAlejandro Colomar1-1/+1
Reported-by: groff(1) (`make build-catman-troff`) Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-03-08string_copying.7: Modify implementation of stpecpy()Alejandro Colomar1-3/+2
- Don't crash on invalid input. That should be done in a wrapper, if wanted. - Accept NULL as input, since that allows chaining with stpeprintf(). Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-03-08string_copying.7: srcfix (unmatched RE)Alejandro Colomar1-1/+0
Reported-by: mandoc(1) (make lint-man-mandoc) Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-02-05Many pages: Use \[bu] instead of \(buAlejandro Colomar1-25/+25
Signed-off-by: Alejandro Colomar <alx@kernel.org>
2023-02-05Many pages: Use \[aq] instead of \(aqAlejandro Colomar1-6/+6
This improves readability in the source code, since it delimits where the escape sequence ends. Cc: наб <nabijaczleweli@nabijaczleweli.xyz> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Brian Inglis <Brian.Inglis@Shaw.ca> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2022-12-30bpf-helpers.7, open_how.2type, string_copying.7: tfixSamanta Navarro1-1/+1
Typos found with codespell. Signed-off-by: Samanta Navarro <ferivoz@riseup.net> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2022-12-24string_copying.7: Remove stpecpyx()Alejandro Colomar1-49/+16
And give stpecpy() with the semantics of stpecpyx(). Signed-off-by: Alejandro Colomar <alx@kernel.org>
2022-12-22string_copying.7: tfixAlejandro Colomar1-1/+1
Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2022-12-20string_copying.7: tfixAlejandro Colomar1-1/+1
Reported-by: Stefan Puiu <stefan.puiu@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
2022-12-20string_copying.7: Add page to document all string-copying functionsAlejandro Colomar1-0/+855
This is an opportunity to use consistent language across the documentation for all string-copying functions. It is also easier to show the similarities and differences between all of the functions, so that a reader can use this page to know which function is needed for a given task. Alternative functions not provided by libc have been given in the same page, with reference implementations. Cc: Martin Sebor <msebor@redhat.com> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Douglas McIlroy <douglas.mcilroy@dartmouth.edu> Cc: Jakub Wilk <jwilk@jwilk.net> Cc: Serge Hallyn <serge@hallyn.com> Cc: Iker Pedrosa <ipedrosa@redhat.com> Cc: Andrew Pinski <pinskia@gmail.com> Cc: Stefan Puiu <stefan.puiu@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
generated by cgit 1.2.3-korg (git 2.43.0) at 2025-11-30 07:05:38 +0000