| 1 |
.\" Copyright, the authors of the Linux man-pages project |
| 2 |
.\" |
| 3 |
.\" SPDX-License-Identifier: BSD-3-Clause |
| 4 |
.\" |
| 5 |
.TH string_copying 7 2026-02-10 "Linux man-pages 6.18" |
| 6 |
.\" ----- NAME :: -----------------------------------------------------/ |
| 7 |
.SH NAME |
| 8 |
stpcpy, |
| 9 |
strcpy, strcat, |
| 10 |
stpecpy, |
| 11 |
strtcpy, |
| 12 |
strlcpy, strlcat, |
| 13 |
stpncpy, |
| 14 |
strncpy, |
| 15 |
strncat |
| 16 |
\- copying strings and character sequences |
| 17 |
.\" ----- SYNOPSIS :: -------------------------------------------------/ |
| 18 |
.SH SYNOPSIS |
| 19 |
.\" ----- SYNOPSIS :: (Null-terminated) strings -----------------------/ |
| 20 |
.SS Strings |
| 21 |
.nf |
| 22 |
// Chain-copy a string. |
| 23 |
.BI "char *stpcpy(char *restrict " dst ", const char *restrict " src ); |
| 24 |
.P |
| 25 |
// Copy/catenate a string. |
| 26 |
.BI "char *strcpy(char *restrict " dst ", const char *restrict " src ); |
| 27 |
.BI "char *strcat(char *restrict " dst ", const char *restrict " src ); |
| 28 |
.P |
| 29 |
// Chain-copy a string with truncation. |
| 30 |
.BI "char *stpecpy(char *" dst ", char " end "[0], const char *restrict " src ); |
| 31 |
.P |
| 32 |
// Copy/catenate a string with truncation. |
| 33 |
.BR "ssize_t strtcpy(" "size_t dsize;" |
| 34 |
.BI " char " dst "[restrict " dsize "], const char *restrict " src , |
| 35 |
.BI " size_t " dsize ); |
| 36 |
.BR "size_t strlcpy(" "size_t dsize;" |
| 37 |
.BI " char " dst "[restrict " dsize "], const char *restrict " src , |
| 38 |
.BI " size_t " dsize ); |
| 39 |
.BR "size_t strlcat(" "size_t dsize;" |
| 40 |
.BI " char " dst "[restrict " dsize "], const char *restrict " src , |
| 41 |
.BI " size_t " dsize ); |
| 42 |
.fi |
| 43 |
.\" ----- SYNOPSIS :: Null-padded character sequences --------/ |
| 44 |
.SS Null-padded character sequences |
| 45 |
.nf |
| 46 |
// Fill a fixed-size buffer with characters from a string |
| 47 |
// and pad with null bytes. |
| 48 |
.BR "char *strncpy(" "size_t dsize;" |
| 49 |
.BI " char " dst "[restrict " dsize "], const char *restrict " src , |
| 50 |
.BI " size_t " dsize ); |
| 51 |
.BR "char *stpncpy(" "size_t dsize;" |
| 52 |
.BI " char " dst "[restrict " dsize "], const char *restrict " src , |
| 53 |
.BI " size_t " dsize ); |
| 54 |
.P |
| 55 |
// Chain-copy a null-padded character sequence into a character sequence. |
| 56 |
.I mempcpy(dst, src, strnlen(src, countof(src))); |
| 57 |
.P |
| 58 |
// Chain-copy a null-padded character sequence into a string. |
| 59 |
.I stpcpy(mempcpy(dst, src, strnlen(src, countof(src))), \[dq]\[dq]); |
| 60 |
.P |
| 61 |
// Catenate a null-padded character sequence into a string. |
| 62 |
.BR "char *strncat(" "size_t ssize;" |
| 63 |
.BI " char *restrict " dst ", const char " src "[restrict " ssize ], |
| 64 |
.BI " size_t " ssize ); |
| 65 |
.P |
| 66 |
// Duplicate a null-padded character sequence into a string. |
| 67 |
.BR "char *strndup(" "size_t ssize;" |
| 68 |
.BI " const char " src [ ssize "], size_t " ssize ); |
| 69 |
.fi |
| 70 |
.\" ----- SYNOPSIS :: Length-bounded character sequences --------------/ |
| 71 |
.SS Length-bounded character sequences |
| 72 |
.nf |
| 73 |
// Chain-copy a length-bounded character sequence. |
| 74 |
.BR "void *mempcpy(" "size_t len;" |
| 75 |
.BI " void " dst "[restrict " len "], const void " src "[restrict " len ], |
| 76 |
.BI " size_t " len ); |
| 77 |
.P |
| 78 |
// Chain-copy a length-bounded character sequence into a string. |
| 79 |
.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]); |
| 80 |
.fi |
| 81 |
.SH DESCRIPTION |
| 82 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: -----------------/ |
| 83 |
.SS Terms (and abbreviations) |
| 84 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: string (str) ----/ |
| 85 |
.TP |
| 86 |
.IR "string " ( str ) |
| 87 |
is a sequence of zero or more non-null characters followed by a null character. |
| 88 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: null-padded character seq |
| 89 |
.TP |
| 90 |
.I character sequence |
| 91 |
is a sequence of zero or more non-null characters. |
| 92 |
A program should never use a character sequence where a string is required. |
| 93 |
However, with appropriate care, |
| 94 |
a string can be used in the place of a character sequence. |
| 95 |
.RS |
| 96 |
.TP |
| 97 |
.I null-padded character sequence |
| 98 |
Character sequences can be contained in fixed-size buffers, |
| 99 |
which contain padding null bytes after the character sequence, |
| 100 |
to fill the rest of the buffer |
| 101 |
without affecting the character sequence; |
| 102 |
however, those padding null bytes are not part of the character sequence. |
| 103 |
Don't confuse null-padded with null-terminated: |
| 104 |
null-padded means 0 or more padding null bytes, |
| 105 |
while null-terminated means exactly 1 terminating null character. |
| 106 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: length-bounded character sequence |
| 107 |
.TP |
| 108 |
.I length-bounded character sequence |
| 109 |
Character sequence delimited by its length. |
| 110 |
It may be a slice of a larger character sequence, |
| 111 |
or even of a string. |
| 112 |
.RE |
| 113 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: length (len) ----/ |
| 114 |
.TP |
| 115 |
.IR "length " ( len ) |
| 116 |
is the number of non-null characters in a string or character sequence. |
| 117 |
It is the return value of |
| 118 |
.I strlen(str) |
| 119 |
and of |
| 120 |
.IR "strnlen(buf, size)" . |
| 121 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: size ------------/ |
| 122 |
.TP |
| 123 |
.I size |
| 124 |
refers to the entire buffer |
| 125 |
where the string or character sequence is contained. |
| 126 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: end -------------/ |
| 127 |
.TP |
| 128 |
.I end |
| 129 |
is the name of a pointer to one past the last element of a buffer. |
| 130 |
It is equivalent to |
| 131 |
.IR &str[size] . |
| 132 |
It is used as a sentinel value, |
| 133 |
to be able to truncate strings or character sequences |
| 134 |
instead of overrunning the containing buffer. |
| 135 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: copy ------------/ |
| 136 |
.TP |
| 137 |
.I copy |
| 138 |
This term is used when |
| 139 |
the writing starts at the first element pointed to by |
| 140 |
.IR dst . |
| 141 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: catenate --------/ |
| 142 |
.TP |
| 143 |
.I catenate |
| 144 |
This term is used when |
| 145 |
a function first finds the terminating null character in |
| 146 |
.IR dst , |
| 147 |
and then starts writing at that position. |
| 148 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: chain -----------/ |
| 149 |
.TP |
| 150 |
.I chain |
| 151 |
This term is used when |
| 152 |
it's the programmer who provides |
| 153 |
a pointer to the terminating null character in the string |
| 154 |
.I dst |
| 155 |
(or one after the last character in a character sequence), |
| 156 |
and the function starts writing at that location. |
| 157 |
The function returns |
| 158 |
a pointer to the new location of the terminating null character |
| 159 |
(or one after the last character in a character sequence) |
| 160 |
after the call, |
| 161 |
so that the programmer can use it to chain such calls. |
| 162 |
.\" ----- DESCRIPTION :: Terms (and abbreviations) :: duplicate -------/ |
| 163 |
.TP |
| 164 |
.I duplicate |
| 165 |
Allocate a new buffer |
| 166 |
where a copy is placed. |
| 167 |
.\" ----- DESCRIPTION :: Copy, catenate, and chain-copy ---------------/ |
| 168 |
.SS Copy, catenate, and chain-copy |
| 169 |
Originally, |
| 170 |
there was a distinction between functions that copy and those that catenate. |
| 171 |
However, newer functions that copy while allowing chaining |
| 172 |
cover both use cases with a single API. |
| 173 |
They are also algorithmically faster, |
| 174 |
since they don't need to search for |
| 175 |
the terminating null character of the existing string. |
| 176 |
However, functions that catenate have a much simpler use, |
| 177 |
so if performance is not important, |
| 178 |
it can make sense to use them for improving readability. |
| 179 |
.P |
| 180 |
The pointer returned by functions that allow chaining |
| 181 |
is a byproduct of the copy operation, |
| 182 |
so it has no performance costs. |
| 183 |
Functions that return such a pointer, |
| 184 |
and thus can be chained, |
| 185 |
have names of the form |
| 186 |
.RB * stp *(), |
| 187 |
since it's common to name the pointer just |
| 188 |
.IR p . |
| 189 |
.P |
| 190 |
Chain-copying functions that truncate |
| 191 |
should accept a pointer to the end of the destination buffer, |
| 192 |
and have names of the form |
| 193 |
.RB * stpe *(). |
| 194 |
This allows not having to recalculate the remaining size after each call. |
| 195 |
.\" ----- DESCRIPTION :: Truncate or not? -----------------------------/ |
| 196 |
.SS Truncate or not? |
| 197 |
The first thing to note is that programmers should be careful with buffers, |
| 198 |
so they always have the correct size, |
| 199 |
and truncation is not necessary. |
| 200 |
.P |
| 201 |
In most cases, |
| 202 |
truncation is not desired, |
| 203 |
and it is simpler to just do the copy. |
| 204 |
Simpler code is safer code. |
| 205 |
Programming against programming mistakes by adding more code |
| 206 |
just adds more points where mistakes can be made. |
| 207 |
.P |
| 208 |
Nowadays, |
| 209 |
compilers can detect most programmer errors with features like |
| 210 |
compiler warnings, |
| 211 |
static analyzers, and |
| 212 |
.B \%_FORTIFY_SOURCE |
| 213 |
(see |
| 214 |
.BR ftm (7)). |
| 215 |
Keeping the code simple |
| 216 |
helps these overflow-detection features be more precise. |
| 217 |
.P |
| 218 |
When validating user input, |
| 219 |
code should normally not truncate, |
| 220 |
but instead fail and prevent the copy at all. |
| 221 |
.P |
| 222 |
In some cases, |
| 223 |
however, |
| 224 |
it makes sense to truncate. |
| 225 |
.P |
| 226 |
Functions that truncate: |
| 227 |
.IP \[bu] 3 |
| 228 |
.BR stpecpy () |
| 229 |
.IP \[bu] |
| 230 |
.BR strtcpy () |
| 231 |
.IP \[bu] |
| 232 |
.BR strlcpy (3bsd) |
| 233 |
and |
| 234 |
.BR strlcat (3bsd) |
| 235 |
are similar, but have important performance problems; |
| 236 |
see BUGS. |
| 237 |
.IP \[bu] |
| 238 |
.BR stpncpy (3) |
| 239 |
and |
| 240 |
.BR strncpy (3) |
| 241 |
also truncate, but they don't write strings, |
| 242 |
but rather null-padded character sequences. |
| 243 |
.\" ----- DESCRIPTION :: Null-padded character sequences --------------/ |
| 244 |
.SS Null-padded character sequences |
| 245 |
For historic reasons, |
| 246 |
some standard APIs and file formats, |
| 247 |
such as |
| 248 |
.BR utmpx (5) |
| 249 |
and |
| 250 |
.BR tar (1), |
| 251 |
use null-padded character sequences in fixed-size buffers. |
| 252 |
To interface with them, |
| 253 |
specialized functions need to be used. |
| 254 |
.P |
| 255 |
To copy bytes from strings into these buffers, use |
| 256 |
.BR strncpy (3) |
| 257 |
or |
| 258 |
.BR stpncpy (3). |
| 259 |
.P |
| 260 |
To read a null-padded character sequence, |
| 261 |
use |
| 262 |
.IR "strnlen(src,\ countof(src))" , |
| 263 |
and then you can treat it as a length-bounded character sequence; |
| 264 |
or use |
| 265 |
.BR strncat (3) |
| 266 |
or |
| 267 |
.BR strndup (3) |
| 268 |
directly. |
| 269 |
.\" ----- DESCRIPTION :: Length-bounded character sequences -----------/ |
| 270 |
.SS Length-bounded character sequences |
| 271 |
The simplest character sequence copying function is |
| 272 |
.BR mempcpy (3). |
| 273 |
It requires always knowing the length of your character sequences, |
| 274 |
for which structures can be used. |
| 275 |
It makes the code much faster, |
| 276 |
since you always know the length of your character sequences, |
| 277 |
and can do the minimal copies and length measurements. |
| 278 |
.BR mempcpy (3) |
| 279 |
copies character sequences, |
| 280 |
so you need to explicitly set the terminating null character |
| 281 |
if you need a string. |
| 282 |
.P |
| 283 |
In programs that make considerable use of strings or character sequences, |
| 284 |
and need the best performance, |
| 285 |
using overlapping character sequences can make a big difference. |
| 286 |
It allows holding subsequences of a larger character sequence, |
| 287 |
while not duplicating memory |
| 288 |
nor using time to do a copy. |
| 289 |
.P |
| 290 |
However, this is delicate, |
| 291 |
since it requires using character sequences. |
| 292 |
C library APIs use strings, |
| 293 |
so programs that use character sequences |
| 294 |
will have to take care of differentiating strings from character sequences. |
| 295 |
.P |
| 296 |
To copy a length-bounded character sequence, use |
| 297 |
.BR mempcpy (3). |
| 298 |
.P |
| 299 |
To copy a length-bounded character sequence into a string, use |
| 300 |
.IR "\%stpcpy(mempcpy(dst,\ src,\ len),\ \[dq]\[dq])" . |
| 301 |
.P |
| 302 |
A string is also accepted as input, |
| 303 |
because |
| 304 |
.BR mempcpy (3) |
| 305 |
asks for the length, |
| 306 |
and a string is composed of a character sequence of the same length |
| 307 |
plus a terminating null character. |
| 308 |
.\" ----- DESCRIPTION :: String vs character sequence -----------------/ |
| 309 |
.SS String vs character sequence |
| 310 |
Some functions only operate on strings. |
| 311 |
Those require that the input |
| 312 |
.I src |
| 313 |
is a string, |
| 314 |
and guarantee an output string |
| 315 |
(even when truncation occurs). |
| 316 |
Functions that catenate |
| 317 |
also require that |
| 318 |
.I dst |
| 319 |
holds a string before the call. |
| 320 |
List of functions: |
| 321 |
.IP \[bu] 3 |
| 322 |
.PD 0 |
| 323 |
.BR stpcpy (3) |
| 324 |
.IP \[bu] |
| 325 |
.BR strcpy (3), |
| 326 |
.BR strcat (3) |
| 327 |
.IP \[bu] |
| 328 |
.BR stpecpy () |
| 329 |
.IP \[bu] |
| 330 |
.BR strtcpy () |
| 331 |
.IP \[bu] |
| 332 |
.BR strlcpy (3bsd), |
| 333 |
.BR strlcat (3bsd) |
| 334 |
.PD |
| 335 |
.P |
| 336 |
Other functions require an input string, |
| 337 |
but create a character sequence as output. |
| 338 |
These functions have confusing names, |
| 339 |
and have a long history of misuse. |
| 340 |
List of functions: |
| 341 |
.IP \[bu] 3 |
| 342 |
.PD 0 |
| 343 |
.BR stpncpy (3) |
| 344 |
.IP \[bu] |
| 345 |
.BR strncpy (3) |
| 346 |
.PD |
| 347 |
.P |
| 348 |
Other functions operate on an input character sequence, |
| 349 |
and create an output string. |
| 350 |
Functions that catenate |
| 351 |
also require that |
| 352 |
.I dst |
| 353 |
holds a string before the call. |
| 354 |
.BR strncat (3) |
| 355 |
has an even more misleading name than the functions above. |
| 356 |
List of functions: |
| 357 |
.IP \[bu] 3 |
| 358 |
.PD 0 |
| 359 |
.BR strncat (3) |
| 360 |
.IP \[bu] |
| 361 |
.BR strndup (3) |
| 362 |
.PD |
| 363 |
.P |
| 364 |
Other functions operate on an input character sequence |
| 365 |
to create an output character sequence. |
| 366 |
List of functions: |
| 367 |
.IP \[bu] 3 |
| 368 |
.BR mempcpy (3) |
| 369 |
.\" ----- DESCRIPTION :: Functions :: ---------------------------------/ |
| 370 |
.SS Functions |
| 371 |
.\" ----- DESCRIPTION :: Functions :: stpcpy(3) -----------------------/ |
| 372 |
.TP |
| 373 |
.BR stpcpy (3) |
| 374 |
Copy the input string into a destination string. |
| 375 |
The programmer is responsible for allocating a buffer large enough. |
| 376 |
It returns a pointer suitable for chaining. |
| 377 |
.\" ----- DESCRIPTION :: Functions :: strcpy(3), strcat(3) ------------/ |
| 378 |
.TP |
| 379 |
.BR strcpy (3) |
| 380 |
.TQ |
| 381 |
.BR strcat (3) |
| 382 |
Copy and catenate the input string into a destination string. |
| 383 |
The programmer is responsible for allocating a buffer large enough. |
| 384 |
The return value is useless. |
| 385 |
.IP |
| 386 |
.BR stpcpy (3) |
| 387 |
is a faster alternative to these functions. |
| 388 |
.\" ----- DESCRIPTION :: Functions :: stpecpy() -----------------------/ |
| 389 |
.TP |
| 390 |
.BR stpecpy () |
| 391 |
Chain-copy the input string into a destination string. |
| 392 |
If the destination buffer, |
| 393 |
limited by a pointer to its end, |
| 394 |
isn't large enough to hold the copy, |
| 395 |
the resulting string is truncated |
| 396 |
(but it is guaranteed to be null-terminated). |
| 397 |
It returns a pointer suitable for chaining. |
| 398 |
Truncation needs to be detected only once after the last chained call. |
| 399 |
.IP |
| 400 |
This function is not provided by any library; |
| 401 |
see EXAMPLES for a reference implementation. |
| 402 |
.\" ----- DESCRIPTION :: Functions :: strtcpy() -----------------------/ |
| 403 |
.TP |
| 404 |
.BR strtcpy () |
| 405 |
Copy the input string into a destination string. |
| 406 |
If the destination buffer isn't large enough to hold the copy, |
| 407 |
the resulting string is truncated |
| 408 |
(but it is guaranteed to be null-terminated). |
| 409 |
It returns the length of the string, |
| 410 |
or \-1 if it truncated. |
| 411 |
.IP |
| 412 |
This function is not provided by any library; |
| 413 |
see EXAMPLES for a reference implementation. |
| 414 |
.\" ----- DESCRIPTION :: Functions :: strlcpy(3bsd), strlcat(3bsd) ----/ |
| 415 |
.TP |
| 416 |
.BR strlcpy (3bsd) |
| 417 |
.TQ |
| 418 |
.BR strlcat (3bsd) |
| 419 |
Copy and catenate the input string into a destination string. |
| 420 |
If the destination buffer, |
| 421 |
limited by its size, |
| 422 |
isn't large enough to hold the copy, |
| 423 |
the resulting string is truncated |
| 424 |
(but it is guaranteed to be null-terminated). |
| 425 |
They return the length of the total string they tried to create. |
| 426 |
.IP |
| 427 |
Check BUGS before using these functions. |
| 428 |
.IP |
| 429 |
.BR strtcpy () |
| 430 |
and |
| 431 |
.BR stpecpy () |
| 432 |
are better alternatives to these functions. |
| 433 |
.\" ----- DESCRIPTION :: Functions :: stpncpy(3) ----------------------/ |
| 434 |
.TP |
| 435 |
.BR stpncpy (3) |
| 436 |
Copy the input string into |
| 437 |
a destination null-padded character sequence in a fixed-size buffer. |
| 438 |
If the destination buffer, |
| 439 |
limited by its size, |
| 440 |
isn't large enough to hold the copy, |
| 441 |
the resulting character sequence is truncated. |
| 442 |
Since it creates a character sequence, |
| 443 |
it doesn't need to write a terminating null character. |
| 444 |
It's impossible to distinguish truncation by the result of the call, |
| 445 |
from a character sequence that just fits the destination buffer; |
| 446 |
truncation should be detected by |
| 447 |
comparing the length of the input string |
| 448 |
with the size of the destination buffer. |
| 449 |
.\" ----- DESCRIPTION :: Functions :: strncpy(3) ----------------------/ |
| 450 |
.TP |
| 451 |
.BR strncpy (3) |
| 452 |
This function is identical to |
| 453 |
.BR stpncpy (3) |
| 454 |
except for the useless return value. |
| 455 |
.IP |
| 456 |
.BR stpncpy (3) |
| 457 |
is a more useful alternative to this function. |
| 458 |
.\" ----- DESCRIPTION :: Functions :: strncat(3) ----------------------/ |
| 459 |
.TP |
| 460 |
.BR strncat (3) |
| 461 |
Catenate the input character sequence, |
| 462 |
contained in a null-padded fixed-size buffer, |
| 463 |
into a destination string. |
| 464 |
The programmer is responsible for allocating a buffer large enough. |
| 465 |
The return value is useless. |
| 466 |
.IP |
| 467 |
Do not confuse this function with |
| 468 |
.BR strncpy (3); |
| 469 |
they are not related at all. |
| 470 |
.IP |
| 471 |
.I \%stpcpy(mempcpy(dst,\ src,\ strnlen(src,\ countof(src))),\ \[dq]\[dq]) |
| 472 |
is a faster alternative to this function. |
| 473 |
.\" ----- DESCRIPTION :: Functions :: strndup(3) ----------------------/ |
| 474 |
.TP |
| 475 |
.BR strndup (3) |
| 476 |
Duplicate the input character sequence, |
| 477 |
contained in a null-padded fixed-size buffer, |
| 478 |
into a newly allocated destination string. |
| 479 |
.IP |
| 480 |
The string must be freed with |
| 481 |
.BR free (3). |
| 482 |
.\" ----- DESCRIPTION :: Functions :: mempcpy(3) ----------------------/ |
| 483 |
.TP |
| 484 |
.BR mempcpy (3) |
| 485 |
Copy the input character sequence, |
| 486 |
limited by its length, |
| 487 |
into a destination character sequence. |
| 488 |
The programmer is responsible for allocating a buffer large enough. |
| 489 |
It returns a pointer suitable for chaining. |
| 490 |
.\" ----- RETURN VALUE :: ---------------------------------------------/ |
| 491 |
.SH RETURN VALUE |
| 492 |
.TP |
| 493 |
.BR stpcpy (3) |
| 494 |
A pointer to the terminating null character in the destination string. |
| 495 |
.TP |
| 496 |
.BR stpecpy () |
| 497 |
A pointer to the terminating null character in the destination string, |
| 498 |
on success. |
| 499 |
On error, |
| 500 |
NULL is returned, |
| 501 |
and |
| 502 |
.I errno |
| 503 |
is set to indicate the error. |
| 504 |
.TP |
| 505 |
.BR mempcpy (3) |
| 506 |
.TQ |
| 507 |
.BR stpncpy (3) |
| 508 |
A pointer to one after the last character |
| 509 |
in the destination character sequence. |
| 510 |
.TP |
| 511 |
.BR strtcpy () |
| 512 |
The length of the string, |
| 513 |
on success. |
| 514 |
On error, |
| 515 |
\-1 is returned, |
| 516 |
and |
| 517 |
.I errno |
| 518 |
is set to indicate the error. |
| 519 |
.TP |
| 520 |
.BR strlcpy (3bsd) |
| 521 |
.TQ |
| 522 |
.BR strlcat (3bsd) |
| 523 |
The length of the total string that they tried to create |
| 524 |
(as if truncation didn't occur). |
| 525 |
.TP |
| 526 |
.BR strcpy (3) |
| 527 |
.TQ |
| 528 |
.BR strcat (3) |
| 529 |
.TQ |
| 530 |
.BR strncpy (3) |
| 531 |
.TQ |
| 532 |
.BR strncat (3) |
| 533 |
The |
| 534 |
.I dst |
| 535 |
pointer, |
| 536 |
which is useless. |
| 537 |
.TP |
| 538 |
.BR strndup (3) |
| 539 |
The newly allocated string. |
| 540 |
.\" ----- ERRORS ------------------------------------------------------/ |
| 541 |
.SH ERRORS |
| 542 |
Most of these functions don't set |
| 543 |
.IR errno . |
| 544 |
.TP |
| 545 |
.BR stpecpy () |
| 546 |
.TQ |
| 547 |
.BR strtcpy () |
| 548 |
.RS |
| 549 |
.TP |
| 550 |
.B ENOBUFS |
| 551 |
.I dsize |
| 552 |
was |
| 553 |
.BR 0 . |
| 554 |
.TP |
| 555 |
.B E2BIG |
| 556 |
The string has been truncated. |
| 557 |
.RE |
| 558 |
.TP |
| 559 |
.BR strndup (3) |
| 560 |
.RS |
| 561 |
.TP |
| 562 |
.B ENOMEM |
| 563 |
Insufficient memory available to allocate duplicate string. |
| 564 |
.RE |
| 565 |
.\" ----- NOTES :: strscpy(9) -----------------------------------------/ |
| 566 |
.SH NOTES |
| 567 |
The Linux kernel has an internal function for copying strings, |
| 568 |
.BR strscpy (9), |
| 569 |
which is identical to |
| 570 |
.BR strtcpy (), |
| 571 |
except that it returns |
| 572 |
.B \-E2BIG |
| 573 |
instead of \-1 |
| 574 |
and it doesn't set |
| 575 |
.IR errno . |
| 576 |
.\" ----- CAVEATS :: --------------------------------------------------/ |
| 577 |
.SH CAVEATS |
| 578 |
Don't mix chain calls to truncating and non-truncating functions. |
| 579 |
It is conceptually wrong |
| 580 |
unless you know that the first part of a copy will always fit. |
| 581 |
Anyway, the performance difference will probably be negligible, |
| 582 |
so it will probably be more clear if you use consistent semantics: |
| 583 |
either truncating or non-truncating. |
| 584 |
Calling a non-truncating function after a truncating one is necessarily wrong. |
| 585 |
.\" ----- BUGS :: -----------------------------------------------------/ |
| 586 |
.SH BUGS |
| 587 |
All catenation functions share the same performance problem: |
| 588 |
.UR https:\://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ |
| 589 |
Shlemiel the painter |
| 590 |
.UE . |
| 591 |
As a mitigation, |
| 592 |
compilers are able to transform some calls to catenation functions |
| 593 |
into normal copy functions, |
| 594 |
since |
| 595 |
.I strlen(dst) |
| 596 |
is usually a byproduct of the previous copy. |
| 597 |
.P |
| 598 |
.BR strlcpy (3) |
| 599 |
and |
| 600 |
.BR strlcat (3) |
| 601 |
need to read the entire |
| 602 |
.I src |
| 603 |
string, |
| 604 |
even if the destination buffer is small. |
| 605 |
This makes them vulnerable to Denial of Service (DoS) attacks |
| 606 |
if an attacker can control the length of the |
| 607 |
.I src |
| 608 |
string. |
| 609 |
And if not, |
| 610 |
they're still unnecessarily slow. |
| 611 |
.\" ----- EXAMPLES :: -------------------------------------------------/ |
| 612 |
.SH EXAMPLES |
| 613 |
The following are examples of correct use of each of these functions. |
| 614 |
.\" ----- EXAMPLES :: stpcpy(3) ---------------------------------------/ |
| 615 |
.TP |
| 616 |
.BR stpcpy (3) |
| 617 |
.EX |
| 618 |
p = buf; |
| 619 |
p = stpcpy(p, "Hello "); |
| 620 |
p = stpcpy(p, "world"); |
| 621 |
p = stpcpy(p, "!"); |
| 622 |
len = p \- buf; |
| 623 |
puts(buf); |
| 624 |
.EE |
| 625 |
.\" ----- EXAMPLES :: strcpy(3), strcat(3) ----------------------------/ |
| 626 |
.TP |
| 627 |
.BR strcpy (3) |
| 628 |
.TQ |
| 629 |
.BR strcat (3) |
| 630 |
.EX |
| 631 |
strcpy(buf, "Hello "); |
| 632 |
strcat(buf, "world"); |
| 633 |
strcat(buf, "!"); |
| 634 |
len = strlen(buf); |
| 635 |
puts(buf); |
| 636 |
.EE |
| 637 |
.\" ----- EXAMPLES :: stpecpy() ---------------------------------------/ |
| 638 |
.TP |
| 639 |
.BR stpecpy () |
| 640 |
.EX |
| 641 |
end = buf + countof(buf); |
| 642 |
p = buf; |
| 643 |
p = stpecpy(p, end, "Hello "); |
| 644 |
p = stpecpy(p, end, "world"); |
| 645 |
p = stpecpy(p, end, "!"); |
| 646 |
if (p == NULL) { |
| 647 |
len = countof(buf) \- 1; |
| 648 |
goto toolong; |
| 649 |
} |
| 650 |
len = p \- buf; |
| 651 |
puts(buf); |
| 652 |
.EE |
| 653 |
.\" ----- EXAMPLES :: strtcpy() ---------------------------------------/ |
| 654 |
.TP |
| 655 |
.BR strtcpy () |
| 656 |
.EX |
| 657 |
len = strtcpy(buf, "Hello world!", countof(buf)); |
| 658 |
if (len == \-1) |
| 659 |
goto toolong; |
| 660 |
puts(buf); |
| 661 |
.EE |
| 662 |
.\" ----- EXAMPLES :: strlcpy(3bsd), strlcat(3bsd) --------------------/ |
| 663 |
.TP |
| 664 |
.BR strlcpy (3bsd) |
| 665 |
.TQ |
| 666 |
.BR strlcat (3bsd) |
| 667 |
.EX |
| 668 |
if (strlcpy(buf, "Hello ", countof(buf)) >= countof(buf)) |
| 669 |
goto toolong; |
| 670 |
if (strlcat(buf, "world", countof(buf)) >= countof(buf)) |
| 671 |
goto toolong; |
| 672 |
len = strlcat(buf, "!", countof(buf)); |
| 673 |
if (len >= countof(buf)) |
| 674 |
goto toolong; |
| 675 |
puts(buf); |
| 676 |
.EE |
| 677 |
.\" ----- EXAMPLES :: stpncpy(3) --------------------------------------/ |
| 678 |
.TP |
| 679 |
.BR stpncpy (3) |
| 680 |
.EX |
| 681 |
p = stpncpy(u->ut_user, "alx", countof(u->ut_user)); |
| 682 |
if (countof(u->ut_user) < strlen("alx")) |
| 683 |
goto toolong; |
| 684 |
len = p \- u->ut_user; |
| 685 |
fwrite(u->ut_user, 1, len, stdout); |
| 686 |
.EE |
| 687 |
.\" ----- EXAMPLES :: strncpy(3) --------------------------------------/ |
| 688 |
.TP |
| 689 |
.BR strncpy (3) |
| 690 |
.EX |
| 691 |
strncpy(u->ut_user, "alx", countof(u->ut_user)); |
| 692 |
if (countof(u->ut_user) < strlen("alx")) |
| 693 |
goto toolong; |
| 694 |
len = strnlen(u->ut_user, countof(u->ut_user)); |
| 695 |
fwrite(u->ut_user, 1, len, stdout); |
| 696 |
.EE |
| 697 |
.\" ----- EXAMPLES :: mempcpy(dst, src, strnlen(src, countof(src))) ----/ |
| 698 |
.TP |
| 699 |
.I mempcpy(dst, src, strnlen(src, countof(src))) |
| 700 |
.EX |
| 701 |
char buf[countof(u->ut_user)]; |
| 702 |
p = buf; |
| 703 |
p = mempcpy(p, u->ut_user, strnlen(u->ut_user, countof(u->ut_user))); |
| 704 |
len = p \- buf; |
| 705 |
fwrite(buf, 1, len, stdout); |
| 706 |
.EE |
| 707 |
.\" ----- EXAMPLES :: stpcpy(mempcpy(dst, src, strnlen(src, countof(src))), "") |
| 708 |
.TP |
| 709 |
.I stpcpy(mempcpy(dst, src, strnlen(src, countof(src))), \[dq]\[dq]) |
| 710 |
.EX |
| 711 |
char buf[countof(u->ut_user) + 1]; |
| 712 |
p = buf; |
| 713 |
p = mempcpy(p, u->ut_user, strnlen(u->ut_user, countof(u->ut_user))); |
| 714 |
p = stpcpy(p, ""); |
| 715 |
len = p \- buf; |
| 716 |
puts(buf); |
| 717 |
.EE |
| 718 |
.\" ----- EXAMPLES :: strncat(3) --------------------------------------/ |
| 719 |
.TP |
| 720 |
.BR strncat (3) |
| 721 |
.EX |
| 722 |
char buf[countof(u->ut_user) + 1]; |
| 723 |
strcpy(buf, ""); |
| 724 |
strncat(buf, u->ut_user, countof(u->ut_user)); |
| 725 |
len = strlen(buf); |
| 726 |
puts(buf); |
| 727 |
.EE |
| 728 |
.\" ----- EXAMPLES :: strndup(3) --------------------------------------/ |
| 729 |
.TP |
| 730 |
.BR strndup (3) |
| 731 |
.EX |
| 732 |
buf = strndup(u->ut_user, countof(u->ut_user)); |
| 733 |
len = strlen(buf); |
| 734 |
puts(buf); |
| 735 |
free(buf); |
| 736 |
.EE |
| 737 |
.\" ----- EXAMPLES :: mempcpy(3) --------------------------------------/ |
| 738 |
.TP |
| 739 |
.BR mempcpy (3) |
| 740 |
.EX |
| 741 |
p = buf; |
| 742 |
p = mempcpy(p, "Hello ", 6); |
| 743 |
p = mempcpy(p, "world", 5); |
| 744 |
p = mempcpy(p, "!", 1); |
| 745 |
len = p \- buf; |
| 746 |
fwrite(buf, 1, len, stdout); |
| 747 |
.EE |
| 748 |
.\" ----- EXAMPLES :: stpcpy(mempcpy(), "") ---------------------------/ |
| 749 |
.TP |
| 750 |
.I stpcpy(mempcpy(dst, src, len), \[dq]\[dq]) |
| 751 |
.EX |
| 752 |
p = buf; |
| 753 |
p = mempcpy(p, "Hello ", 6); |
| 754 |
p = mempcpy(p, "world", 5); |
| 755 |
p = mempcpy(p, "!", 1); |
| 756 |
p = stpcpy(p, ""); |
| 757 |
len = p \- buf; |
| 758 |
puts(buf); |
| 759 |
.EE |
| 760 |
.\" ----- EXAMPLES :: Implementations :: ------------------------------/ |
| 761 |
.SS Implementations |
| 762 |
Here are reference implementations for functions not provided by libc. |
| 763 |
.P |
| 764 |
.in +4n |
| 765 |
.EX |
| 766 |
/* This code is in the public domain. */ |
| 767 |
\& |
| 768 |
.\" ----- EXAMPLES :: Implementations :: stpecpy() --------------------/ |
| 769 |
char * |
| 770 |
.IR stpecpy "(char *dst, char end[0], const char *restrict src)" |
| 771 |
{ |
| 772 |
size_t dlen; |
| 773 |
\& |
| 774 |
if (dst == NULL) |
| 775 |
return NULL; |
| 776 |
\& |
| 777 |
dlen = strtcpy(dst, src, end \- dst); |
| 778 |
return (dlen == \-1) ? NULL : dst + dlen; |
| 779 |
} |
| 780 |
\& |
| 781 |
.\" ----- EXAMPLES :: Implementations :: strtcpy() --------------------/ |
| 782 |
ssize_t |
| 783 |
.IR strtcpy "(char *restrict dst, const char *restrict src, size_t dsize)" |
| 784 |
{ |
| 785 |
bool trunc; |
| 786 |
size_t dlen, slen; |
| 787 |
\& |
| 788 |
if (dsize == 0) { |
| 789 |
errno = ENOBUFS; |
| 790 |
return \-1; |
| 791 |
} |
| 792 |
\& |
| 793 |
slen = strnlen(src, dsize); |
| 794 |
trunc = (slen == dsize); |
| 795 |
dlen = slen \- trunc; |
| 796 |
\& |
| 797 |
stpcpy(mempcpy(dst, src, dlen), ""); |
| 798 |
if (trunc) |
| 799 |
errno = E2BIG; |
| 800 |
return trunc ? \-1 : slen; |
| 801 |
} |
| 802 |
.\" ----- SEE ALSO :: -------------------------------------------------/ |
| 803 |
.SH SEE ALSO |
| 804 |
.BR bzero (3), |
| 805 |
.BR memcpy (3), |
| 806 |
.BR memccpy (3), |
| 807 |
.BR mempcpy (3), |
| 808 |
.BR stpcpy (3), |
| 809 |
.BR strlcpy (3bsd), |
| 810 |
.BR strncat (3), |
| 811 |
.BR stpncpy (3), |
| 812 |
.BR string (3) |