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@xxxxxxxxxx> Cc: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx> Cc: Douglas McIlroy <douglas.mcilroy@xxxxxxxxxxxxx> Cc: Jakub Wilk <jwilk@xxxxxxxxx> Cc: Serge Hallyn <serge@xxxxxxxxxx> Cc: Iker Pedrosa <ipedrosa@xxxxxxxxxx> Cc: Andrew Pinski <pinskia@xxxxxxxxx> Cc: Stefan Puiu <stefan.puiu@xxxxxxxxx> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx> --- man7/string_copy.7 | 855 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 855 insertions(+) create mode 100644 man7/string_copy.7 diff --git a/man7/string_copy.7 b/man7/string_copy.7 new file mode 100644 index 000000000..a32b93c01 --- /dev/null +++ b/man7/string_copy.7 @@ -0,0 +1,855 @@ +.\" Copyright 2022 Alejandro Colomar <alx@xxxxxxxxxx> +.\" +.\" SPDX-License-Identifier: BSD-3-Clause +.\" +.TH string_copy 7 (date) "Linux man-pages (unreleased)" +.\" ----- NAME :: -----------------------------------------------------/ +.SH NAME +stpcpy, +strcpy, strcat, +stpecpy, stpecpyx, +strlcpy, strlcat, +stpncpy, +strncpy, +zustr2ustp, zustr2stp, +strncat, +ustpcpy, ustr2stp +\- copy strings and character sequences +.\" ----- SYNOPSIS :: -------------------------------------------------/ +.SH SYNOPSIS +.\" ----- SYNOPSIS :: (Null-terminated) strings -----------------------/ +.SS Strings +.nf +// Chain-copy a string. +.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); +.PP +// Copy/catenate a string. +.BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); +.BI "char *strcat(char *restrict " dst ", const char *restrict " src ); +.PP +// Chain-copy a string with truncation. +.BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); +.PP +// Chain-copy a string with truncation and SIGSEGV on UB. +.BI "char *stpecpyx(char *" dst ", char " end "[0], const char *restrict " src ); +.PP +// Copy/catenate a string with truncation and SIGSEGV on UB. +.BI "size_t strlcpy(char " dst "[restrict ." sz "], \ +const char *restrict " src , +.BI " size_t " sz ); +.BI "size_t strlcat(char " dst "[restrict ." sz "], \ +const char *restrict " src , +.BI " size_t " sz ); +.fi +.\" ----- SYNOPSIS :: Null-padded character sequences --------/ +.SS Null-padded character sequences +.nf +// Zero a fixed-width buffer, and +// copy a string into a character sequence with truncation. +.BI "char *stpncpy(char " dst "[restrict ." sz "], \ +const char *restrict " src , +.BI " size_t " sz ); +.PP +// Zero a fixed-width buffer, and +// copy a string into a character sequence with truncation. +.BI "char *strncpy(char " dest "[restrict ." sz "], \ +const char *restrict " src , +.BI " size_t " sz ); +.PP +// Chain-copy a null-padded character sequence into a character sequence. +.BI "char *zustr2ustp(char *restrict " dst ", \ +const char " src "[restrict ." sz ], +.BI " size_t " sz ); +.PP +// Chain-copy a null-padded character sequence into a string. +.BI "char *zustr2stp(char *restrict " dst ", \ +const char " src "[restrict ." sz ], +.BI " size_t " sz ); +.PP +// Catenate a null-padded character sequence into a string. +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ], +.BI " size_t " sz ); +.fi +.\" ----- SYNOPSIS :: Measured character sequences --------------------/ +.SS Measured character sequences +.nf +// Chain-copy a measured character sequence. +.BI "char *ustpcpy(char *restrict " dst ", \ +const char " src "[restrict ." len ], +.BI " size_t " len ); +.PP +// Chain-copy a measured character sequence into a string. +.BI "char *ustr2stp(char *restrict " dst ", \ +const char " src "[restrict ." len ], +.BI " size_t " len ); +.fi +.SH DESCRIPTION +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/ +.SS Terms (and abbreviations) +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/ +.TP +.IR "string " ( str ) +is a sequence of zero or more non-null characters followed by a null byte. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq +.TP +.I character sequence +is a sequence of zero or more non-null characters. +A program should never usa a character sequence where a string is required. +However, with appropriate care, +a string can be used in the place of a character sequence. +.RS +.TP +.IR "null-padded character sequence " ( zustr ) +Character sequences can be contained in fixed-width buffers, +which contain padding null bytes after the character sequence, +to fill the rest of the buffer +without affecting the character sequence; +however, those padding null bytes are not part of the character sequence. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: measured character sequence +.TP +.IR "measured character sequence " ( ustr ) +Character sequence delimited by its length. +It may be a slice of a larger character sequence, +or even of a string. +.RE +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: length (len) ----/ +.TP +.IR "length " ( len ) +is the number of non-null characters in a string or character sequence. +It is the return value of +.I strlen(str) +and of +.IR "strnlen(ustr, sz)" . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size (sz) -------/ +.TP +.IR "size " ( sz ) +refers to the entire buffer +where the string or character sequence is contained. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/ +.TP +.I end +is the name of a pointer to one past the last element of a buffer. +It is equivalent to +.IR &str[sz] . +It is used as a sentinel value, +to be able to truncate strings or character sequences +instead of overrunning the containing buffer. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: copy ------------/ +.TP +.I copy +This term is used when +the writing starts at the first element pointed to by +.IR dst . +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: catenate --------/ +.TP +.I catenate +This term is used when +a function first finds the terminating null byte in +.IR dst , +and then starts writing at that position. +.\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ +.TP +.I chain +This term is used when +it's the programmer who provides +a pointer to the terminating null byte in the string +.I dst +(or one after the last character in a character sequence), +and the function starts writing at that location. +The function returns +a pointer to the new location of the terminating null byte +(or one after the last character in a character sequence) +after the call, +so that the programmer can use it to chain such calls. +.\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/ +.SS Copy, catenate, and chain-copy +Originally, +there was a distinction between functions that copy and those that catenate. +However, newer functions that copy while allowing chaining +cover both use cases with a single API. +They are also algorithmically faster, +since they don't need to search for +the terminating null byte of the existing string. +However, functions that catenate have a much simpler use, +so if performance is not important, +it can make sense to use them for improving readability. +.PP +The pointer returned by functions that allow chaining +is a byproduct of the copy operation, +so it has no performance costs. +Functions that return such a pointer, +and thus can be chained, +have names of the form +.RB * stp *(), +since it's common to name the pointer just +.IR p . +.PP +Chain-copying functions that truncate +should accept a pointer to the end of the destination buffer, +and have names of the form +.RB * stpe *(). +This allows not having to recalculate the remaining size after each call. +.\" ----- DESCRIPTION :: Truncate or not? -----------------------------/ +.SS Truncate or not? +The first thing to note is that programmers should be careful with buffers, +so they always have the correct size, +and truncation is not necessary. +.PP +In most cases, +truncation is not desired, +and it is simpler to just do the copy. +Simpler code is safer code. +Programming against programming mistakes by adding more code +just adds more points where mistakes can be made. +.PP +Nowadays, +compilers can detect most programmer errors with features like +compiler warnings, +static analyzers, and +.BR \%_FORTIFY_SOURCE +(see +.BR ftm (7)). +Keeping the code simple +helps these overflow-detection features be more precise. +.PP +When validating user input, +however, +it makes sense to truncate. +Remember to check the return value of such function calls. +.PP +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 stpecpyx (3) +is a variant of +.BR stpecpy (3) +that consumes the entire source string, +to catch bugs in the program +by forcing a segmentation fault (as +.BR strlcpy (3bsd) +and +.BR strlcat (3bsd) +do). +.IP \(bu +.BR strlcpy (3bsd) +and +.BR strlcat (3bsd) +are designed to crash if the input string is invalid +(doesn't contain a terminating null byte). +.IP \(bu +.BR stpncpy (3) +and +.BR strncpy (3) +also truncate, but they don't write strings, +but rather null-padded character sequences. +.\" ----- DESCRIPTION :: Null-padded character sequences --------------/ +.SS Null-padded character sequences +For historic reasons, +some standard APIs, +such as +.BR utmpx (5), +use null-padded character sequences in fixed-width buffers. +To interface with them, +specialized functions need to be used. +.PP +To copy strings into them, use +.BR stpncpy (3). +.PP +To copy from an unterminated string within a fixed-width buffer into a string, +ignoring any trailing null bytes in the source fixed-width buffer, +you should use +.BR zustr2stp (3) +or +.BR strncat (3). +.PP +To copy from an unterminated string within a fixed-width buffer +into a character sequence, +ingoring any trailing null bytes in the source fixed-width buffer, +you should use +.BR zustr2ustp (3). +.\" ----- DESCRIPTION :: Measured character sequences -----------------/ +.SS Measured character sequences +The simplest character sequence copying function is +.BR mempcpy (3). +It requires always knowing the length of your character sequences, +for which structures can be used. +It makes the code much faster, +since you always know the length of your character sequences, +and can do the minimal copies and length measurements. +.BR mempcpy (3) +copies character sequences, +so you need to explicitly set the terminating null byte if you need a string. +.PP +However, +for keeping type safety, +it's good to add a wrapper that uses +.I char\~* +instead of +.IR void\~* : +.BR ustpcpy (3). +.PP +In programs that make considerable use of strings or character sequences, +and need the best performance, +using overlapping character sequences can make a big difference. +It allows holding subsequences of a larger character sequence. +while not duplicating memory +nor using time to do a copy. +.PP +However, this is delicate, +since it requires using character sequences. +C library APIs use strings, +so programs that use character sequences +will have to take care of differentiating strings from character sequences. +.PP +To copy a measured character sequence, use +.BR ustpcpy (3). +.PP +To copy a measured character sequence into a string, use +.BR ustr2stp (3). +.PP +Because these functions ask for the length, +and a string is by nature composed of a character sequence of the same length +plus a terminating null byte, +a string is also accepted as input. +.\" ----- DESCRIPTION :: String vs character sequence -----------------/ +.SS String vs character sequence +Some functions only operate on strings. +Those require that the input +.I src +is a string, +and guarantee an output string +(even when truncation occurs). +Functions that catenate +also require that +.I dst +holds a string before the call. +List of functions: +.IP \(bu 3 +.PD 0 +.BR stpcpy (3) +.IP \(bu +.BR strcpy "(3), \c" +.BR strcat (3) +.IP \(bu +.BR stpecpy "(3), \c" +.BR stpecpyx (3) +.IP \(bu +.BR strlcpy "(3bsd), \c" +.BR strlcat (3bsd) +.PD +.PP +Other functions require an input string, +but create a character sequence as output. +These functions have confusing names, +and have a long history of misuse. +List of functions: +.IP \(bu 3 +.PD 0 +.BR stpncpy (3) +.IP \(bu +.BR strncpy (3) +.PD +.PP +Other functions operate on an input character sequence, +and create an output string. +Functions that catenate +also require that +.I dst +holds a string before the call. +.BR strncat (3) +has an even more misleading name than the functions above. +List of functions: +.IP \(bu 3 +.PD 0 +.BR zustr2stp (3) +.IP \(bu +.BR strncat (3) +.IP \(bu +.BR ustr2stp (3) +.PD +.PP +Other functions operate on an input character sequence +to create an output character sequence. +List of functions: +.IP \(bu 3 +.PD 0 +.BR ustpcpy (3) +.IP \(bu +.BR zustr2stp (3) +.PD +.\" ----- DESCRIPTION :: Functions :: ---------------------------------/ +.SS Functions +.\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ +.TP +.BR stpcpy (3) +This function copies the input string into a destination string. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ +.TP +.BR strcpy (3) +.TQ +.BR strcat (3) +These functions copy and catenate the input string into a destination string. +The programmer is responsible for allocating a buffer large enough. +The return value is useless. +.IP +.BR stpcpy (3) +is a faster alternative to these functions. +.\" ----- DESCRIPTION :: Functions :: stpecpy(3), stpecpyx(3) ---------/ +.TP +.BR stpecpy (3) +.TQ +.BR stpecpyx (3) +These functions 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 +(but it is guaranteed to be null-terminated). +They return a pointer suitable for chaining. +Truncation needs to be detected only once after the last chained call. +.BR stpecpyx (3) +has identical semantics to +.BR stpecpy (3), +except that it forces a SIGSEGV if the +.I src +pointer is not a string. +.IP +These functions are not provided by any library; +See EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ +.TP +.BR strlcpy (3bsd) +.TQ +.BR strlcat (3bsd) +These functions copy and catenate 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). +They return the length of the total string they tried to create. +These functions force a SIGSEGV if the +.I src +pointer is not a string. +.IP +.BR stpecpyx (3) +is a faster alternative to these functions. +.\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ +.TP +.BR stpncpy (3) +This function copies the input string into +a destination null-padded character sequence in a fixed-width buffer. +If the destination buffer, +limited by its size, +isn't large enough to hold the copy, +the resulting character sequence is truncated. +Since it creates a character sequence, +it doesn't need to write a terminating null byte. +It's impossible to distinguish truncation by the result of the call, +from a character sequence that just fits the destination buffer; +truncation should be detected by +comparing the length of the input string +with the size of the destination buffer. +.\" ----- DESCRIPTION :: Functions :: strncpy(3) ----------------------/ +.TP +.BR strncpy (3) +This function is identical to +.BR stpncpy (3) +except for the useless return value. +.IP +.BR stpncpy (3) +is a more useful alternative to this function. +.\" ----- DESCRIPTION :: Functions :: zustr2ustp(3) --------------------/ +.TP +.BR zustr2ustp (3) +This function copies the input character sequence +contained in a null-padded wixed-width buffer, +into a destination character sequence. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.IP +A truncating version of this function doesn't exist, +since the size of the original character sequence is always known, +so it wouldn't be very useful. +.IP +This function is not provided by any library; +See EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: zustr2stp(3) --------------------/ +.TP +.BR zustr2stp (3) +This function copies the input character sequence +contained in a null-padded wixed-width buffer, +into a destination string. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.IP +A truncating version of this function doesn't exist, +since the size of the original character sequence is always known, +so it wouldn't be very useful. +.IP +This function is not provided by any library; +See EXAMPLES for a reference implementation. +.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ +.TP +.BR strncat (3) +Do not confuse this function with +.BR strncpy (3); +they are not related at all. +.IP +This function catenates the input character sequence +contained in a null-padded wixed-width buffer, +into a destination string. +The programmer is responsible for allocating a buffer large enough. +The return value is useless. +.IP +.BR zustr2stp (3) +is a faster alternative to this function. +.\" ----- DESCRIPTION :: Functions :: ustpcpy(3) ----------------------/ +.TP +.BR ustpcpy (3) +This function copies the input character sequence, +limited by its length, +into a destination character sequence. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.\" ----- DESCRIPTION :: Functions :: ustr2stp(3) ---------------------/ +.TP +.BR ustr2stp (3) +This function copies the input character sequence, +limited by its length, +into a destination string. +The programmer is responsible for allocating a buffer large enough. +It returns a pointer suitable for chaining. +.\" ----- RETURN VALUE :: ---------------------------------------------/ +.SH RETURN VALUE +The following functions return +a pointer to the terminating null byte in the destination string. +.IP \(bu 3 +.PD 0 +.BR stpcpy (3) +.IP \(bu +.BR ustr2stp (3) +.IP \(bu +.BR zustr2stp (3) +.PD +.PP +The following functions return +a pointer to the terminating null byte in the destination string, +except when truncation occurs; +if truncation occurs, +they return a pointer to the end of the destination buffer. +.IP \(bu 3 +.BR stpecpy (3), +.BR stpecpyx (3) +.PP +The following function returns +a pointer to one after the last character +in the destination character sequence; +if truncation occurs, +that pointer is equivalent to +a pointer to the end of the destination buffer. +.IP \(bu 3 +.BR stpncpy (3) +.PP +The following functions return +a pointer to one after the last character +in the destination character sequence. +.IP \(bu 3 +.PD 0 +.BR zustr2ustp (3) +.IP \(bu +.BR ustpcpy (3) +.PD +.PP +The following functions return +the length of the total string that they tried to create +(as if truncation didn't occur). +.IP \(bu 3 +.BR strlcpy (3bsd), +.BR strlcat (3bsd) +.PP +The following functions return the +.I dst +pointer, +which is useless. +.IP \(bu 3 +.PD 0 +.BR strcpy (3), +.BR strcat (3) +.IP \(bu +.BR strncpy (3) +.IP \(bu +.BR strncat (3) +.PD +.\" ----- 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) +This function copies 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 +.B \-E2BIG +on truncation. +.IP +.BR stpecpy (3) +is a simpler and faster alternative to this function. +.RE +.\" ----- CAVEATS :: --------------------------------------------------/ +.SH CAVEATS +Don't mix chain calls to truncating and non-truncating functions. +It is conceptually wrong +unless you know that the first part of a copy will always fit. +Anyway, the performance difference will probably be negligible, +so it will probably be more clear if you use consistent semantics: +either truncating or non-truncating. +Calling a non-truncating function after a truncating one is necessarily wrong. +.\" ----- BUGS :: -----------------------------------------------------/ +.SH BUGS +All catenation functions share the same performance problem: +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.\" ----- EXAMPLES :: -------------------------------------------------/ +.SH EXAMPLES +The following are examples of correct use of each of these functions. +.\" ----- EXAMPLES :: stpcpy(3) ---------------------------------------/ +.TP +.BR stpcpy (3) +.EX +p = buf; +p = stpcpy(p, "Hello "); +p = stpcpy(p, "world"); +p = stpcpy(p, "!"); +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: strcpy(3), strcat(3) ----------------------------/ +.TP +.BR strcpy (3) +.TQ +.BR strcat (3) +.EX +strcpy(buf, "Hello "); +strcat(buf, "world"); +strcat(buf, "!"); +len = strlen(buf); +puts(buf); +.EE +.\" ----- EXAMPLES :: stpecpy(3), stpecpyx(3) -------------------------/ +.TP +.BR stpecpy (3) +.TQ +.BR stpecpyx (3) +.EX +end = buf + sizeof(buf); +p = buf; +p = stpecpy(p, end, "Hello "); +p = stpecpy(p, end, "world"); +p = stpecpy(p, end, "!"); +if (p == end) { + p\-\-; + goto toolong; +} +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ +.TP +.BR strlcpy (3bsd) +.TQ +.BR strlcat (3bsd) +.EX +if (strlcpy(buf, "Hello ", sizeof(buf)) >= sizeof(buf)) + goto toolong; +if (strlcat(buf, "world", sizeof(buf)) >= sizeof(buf)) + goto toolong; +len = strlcat(buf, "!", sizeof(buf)); +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 +p = stpncpy(buf, "Hello world!", sizeof(buf)); +if (sizeof(buf) < strlen("Hello world!")) + goto toolong; +len = p \- buf; +for (size_t i = 0; i < sizeof(buf); i++) + putchar(buf[i]); +.EE +.\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ +.TP +.BR strncpy (3) +.EX +strncpy(buf, "Hello world!", sizeof(buf)); +if (sizeof(buf) < strlen("Hello world!")) + goto toolong; +len = strnlen(buf, sizeof(buf)); +for (size_t i = 0; i < sizeof(buf); i++) + putchar(buf[i]); +.EE +.\" ----- EXAMPLES :: zustr2ustp(3) -----------------------------------/ +.TP +.BR zustr2ustp (3) +.EX +p = buf; +p = zustr2ustp(p, "Hello ", 6); +p = zustr2ustp(p, "world", 42); // Padding null bytes ignored. +p = zustr2ustp(p, "!", 1); +len = p \- buf; +printf("%.*s\en", (int) len, buf); +.EE +.\" ----- EXAMPLES :: zustr2stp(3) ------------------------------------/ +.TP +.BR zustr2stp (3) +.EX +p = buf; +p = zustr2stp(p, "Hello ", 6); +p = zustr2stp(p, "world", 42); // Padding null bytes ignored. +p = zustr2stp(p, "!", 1); +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: strncat(3) --------------------------------------/ +.TP +.BR strncat (3) +.EX +buf[0] = \(aq\e0\(aq; // There's no 'cpy' function to this 'cat'. +strncat(buf, "Hello ", 6); +strncat(buf, "world", 42); // Padding null bytes ignored. +strncat(buf, "!", 1); +len = strlen(buf); +puts(buf); +.EE +.\" ----- EXAMPLES :: ustpcpy(3) --------------------------------------/ +.TP +.BR ustpcpy (3) +.EX +p = buf; +p = ustpcpy(p, "Hello ", 6); +p = ustpcpy(p, "world", 5); +p = ustpcpy(p, "!", 1); +len = p \- buf; +printf("%.*s\en", (int) len, buf); +.EE +.\" ----- EXAMPLES :: ustr2stp(3) -------------------------------------/ +.TP +.BR ustr2stp (3) +.EX +p = buf; +p = ustr2stp(p, "Hello ", 6); +p = ustr2stp(p, "world", 5); +p = ustr2stp(p, "!", 1); +len = p \- buf; +puts(buf); +.EE +.\" ----- EXAMPLES :: Implementations :: ------------------------------/ +.SS Implementations +Here are reference implementations for functions not provided by libc. +.PP +.in +4n +.EX +/* This code is in the public domain. */ + +.\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ +char * +.IR stpecpy "(char *dst, char end[0], const char *restrict src)" +{ + char *p; + + if (dst == end) + return end; + + p = memccpy(dst, src, \(aq\e0\(aq, end \- dst); + if (p != NULL) + return p \- 1; + + /* truncation detected */ + end[\-1] = \(aq\e0\(aq; + return end; +} + +.\" ----- EXAMPLES :: Implementations :: stpecpy(3) -------------------/ +char * +.IR stpecpyx "(char *dst, char end[0], const char *restrict src)" +{ + if (src[strlen(src)] != \(aq\e0\(aq) + raise(SIGSEGV); + + return stpecpy(dst, end, src); +} + +.\" ----- EXAMPLES :: Implementations :: zustr2ustp(3) ----------------/ +char * +.IR zustr2ustp "(char *restrict dst, const char *restrict src, size_t sz)" +{ + return ustpcpy(dst, src, strnlen(src, sz)); +} + +.\" ----- EXAMPLES :: Implementations :: zustr2stp(3) -----------------/ +char * +.IR zustr2stp "(char *restrict dst, const char *restrict src, size_t sz)" +{ + char *p; + + p = zustr2ustp(dst, src, sz); + *p = \(aq\e0\(aq; + + return p; +} + +.\" ----- EXAMPLES :: Implementations :: ustpcpy(3) -------------------/ +char * +.IR ustpcpy "(char *restrict dst, const char *restrict src, size_t len)" +{ + return mempcpy(dst, src, len); +} + +.\" ----- EXAMPLES :: Implementations :: ustr2stp(3) ------------------/ +char * +.IR ustr2stp "(char *restrict dst, const char *restrict src, size_t len)" +{ + char *p; + + p = ustpcpy(dst, src, len); + *p = \(aq\e0\(aq; + + return p; +} +.EE +.in +.\" ----- SEE ALSO :: -------------------------------------------------/ +.SH SEE ALSO +.BR bzero (3), +.BR memcpy (3), +.BR memccpy (3), +.BR mempcpy (3), +.BR stpcpy (3), +.BR strlcpy (3bsd), +.BR strncat (3), +.BR stpncpy (3), +.BR string (3) -- 2.39.0
