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@xxxxxxxxxxx> Cc: Jonny Grant <jg@xxxxxxxx> Cc: DJ Delorie <dj@xxxxxxxxxx> Cc: Matthew House <mattlloydhouse@xxxxxxxxx> Cc: Oskari Pirhonen <xxc3ncoredxx@xxxxxxxxx> Cc: Thorsten Kukuk <kukuk@xxxxxxxx> Cc: Adhemerval Zanella Netto <adhemerval.zanella@xxxxxxxxxx> Cc: Zack Weinberg <zack@xxxxxxxxxxxx> Cc: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx> Cc: Carlos O'Donell <carlos@xxxxxxxxxx> Cc: Xi Ruoyao <xry111@xxxxxxxxxxx> Cc: Stefan Puiu <stefan.puiu@xxxxxxxxx> Cc: Andreas Schwab <schwab@xxxxxxxxxxxxxx> Cc: Guillem Jover <guillem@xxxxxxxxxxx> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx> --- man3/strtcpy.3 | 1 + man7/string_copying.7 | 97 ++++++++++++++++++++++++++++++------------- 2 files changed, 69 insertions(+), 29 deletions(-) create mode 100644 man3/strtcpy.3 diff --git a/man3/strtcpy.3 b/man3/strtcpy.3 new file mode 100644 index 000000000..beb850746 --- /dev/null +++ b/man3/strtcpy.3 @@ -0,0 +1 @@ +.so man7/string_copying.7 diff --git a/man7/string_copying.7 b/man7/string_copying.7 index cb3910db0..4f609e480 100644 --- a/man7/string_copying.7 +++ b/man7/string_copying.7 @@ -6,8 +6,9 @@ .\" ----- NAME :: -----------------------------------------------------/ .SH NAME stpcpy, strcpy, strcat, +strtcpy, stpecpy, strlcpy, strlcat, stpncpy, strncpy, @@ -30,8 +31,11 @@ .SS Strings // Chain-copy a string with truncation. .BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); .P // Copy/catenate a string with truncation. +.BI "size_t strtcpy(char " dst "[restrict ." sz "], \ +const char *restrict " src , +.BI " size_t " sz ); .BI "size_t strlcpy(char " dst "[restrict ." sz "], \ const char *restrict " src , .BI " size_t " sz ); .BI "size_t strlcat(char " dst "[restrict ." sz "], \ @@ -220,10 +224,10 @@ .SS Truncate or not? .P Functions that truncate: .IP \[bu] 3 .BR stpecpy (3) -is the most efficient string copy function that performs truncation. -It only requires to check for truncation once after all chained calls. +.IP \[bu] +.BR strtcpy (3) .IP \[bu] .BR strlcpy (3bsd) and .BR strlcat (3bsd) @@ -326,8 +330,10 @@ .SS String vs character sequence .IP \[bu] .BR strcpy (3), .BR strcat (3) .IP \[bu] +.BR strtcpy (3) +.IP \[bu] .BR stpecpy (3) .IP \[bu] .BR strlcpy (3bsd), .BR strlcat (3bsd) @@ -390,12 +396,24 @@ .SS Functions The return value is useless. .IP .BR stpcpy (3) is a faster alternative to these functions. +.\" ----- DESCRIPTION :: Functions :: strtcpy(3) ----------------------/ +.TP +.BR strtcpy (3) +Copy the input string into a destination string. +If the destination buffer isn't large enough to hold the copy, +the resulting string is truncated +(but it is guaranteed to be null-terminated). +It returns the length of the string, +or \-1 if it truncated. +.IP +This function is not provided by any library; +see EXAMPLES for a reference implementation. .\" ----- DESCRIPTION :: Functions :: stpecpy(3) ----------------------/ .TP .BR stpecpy (3) -Copy the input string into a destination string. +Chain-copy the input string into a destination string. If the destination buffer, limited by a pointer to its end, isn't large enough to hold the copy, the resulting string is truncated @@ -419,10 +437,12 @@ .SS Functions They return the length of the total string they tried to create. .IP Check BUGS before using these functions. .IP +.BR strtcpy (3) +and .BR stpecpy (3) -is a simpler alternative to these functions. +are better alternatives to these functions. .\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ .TP .BR stpncpy (3) Copy the input string into @@ -542,8 +562,17 @@ .SH RETURN VALUE .BR ustpcpy (3) A pointer to one after the last character in the destination character sequence. .TP +.BR strtcpy (3) +The length of the string. +When truncation occurs, it returns \-1. +When +.I dsize +is +.BR 0 , +it also returns \-1. +.TP .BR strlcpy (3bsd) .TQ .BR strlcat (3bsd) The length of the total string that they tried to create @@ -562,25 +591,14 @@ .SH RETURN VALUE which is useless. .\" ----- NOTES :: strscpy(9) -----------------------------------------/ .SH NOTES The Linux kernel has an internal function for copying strings, -which is similar to -.BR stpecpy (3), -except that it can't be chained: -.TP -.BR strscpy (9) -Copy the input string into a destination string. -If the destination buffer, -limited by its size, -isn't large enough to hold the copy, -the resulting string is truncated -(but it is guaranteed to be null-terminated). -It returns the length of the destination string, or +.BR strscpy (9), +which is identical to +.BR strtcpy (3), +except that it returns .B \-E2BIG -on truncation. -.IP -.BR stpecpy (3) -is a simpler and faster alternative to this function. +instead of \-1. .\" ----- CAVEATS :: --------------------------------------------------/ .SH CAVEATS Don't mix chain calls to truncating and non-truncating functions. It is conceptually wrong @@ -640,8 +658,17 @@ .SH EXAMPLES strcat(buf, "!"); len = strlen(buf); puts(buf); .EE +.\" ----- EXAMPLES :: strtcpy(3) --------------------------------------/ +.TP +.BR strtcpy (3) +.EX +len = strtcpy(buf, "Hello world!", sizeof(buf)); +if (len == \-1) + goto toolong; +puts(buf); +.EE .\" ----- EXAMPLES :: stpecpy(3) --------------------------------------/ .TP .BR stpecpy (3) .EX @@ -671,17 +698,8 @@ .SH EXAMPLES if (len >= sizeof(buf)) goto toolong; puts(buf); .EE -.\" ----- EXAMPLES :: strscpy(9) --------------------------------------/ -.TP -.BR strscpy (9) -.EX -len = strscpy(buf, "Hello world!", sizeof(buf)); -if (len == \-E2BIG) - goto toolong; -puts(buf); -.EE .\" ----- EXAMPLES :: stpncpy(3) --------------------------------------/ .TP .BR stpncpy (3) .EX @@ -765,8 +783,29 @@ .SS Implementations .in +4n .EX /* This code is in the public domain. */ \& +.\" ----- EXAMPLES :: Implementations :: strtcpy(3) -------------------/ +ssize_t +.IR strtcpy "(char *restrict dst, const char *restrict src, size_t sz)" +{ + bool trunc; + char *p; + size_t dlen, slen; +\& + if (dsize == 0) + return \-1; +\& + slen = strnlen(src, dsize); + trunc = (slen == dsize); + dlen = slen \- trunc; +\& + p = mempcpy(dst, src, dlen); + *p = \[aq]\e0\[aq]; + + return trunc ? \-1 : slen; +} +\& .\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ char * .IR stpecpy "(char *dst, char end[0], const char *restrict src)" { -- 2.42.0
Attachment:
signature.asc
Description: PGP signature