diff options
Diffstat (limited to '')
| -rw-r--r-- | man3/strncat.3 | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/man3/strncat.3 b/man3/strncat.3 new file mode 100644 index 0000000..f53c930 --- /dev/null +++ b/man3/strncat.3 @@ -0,0 +1,131 @@ +'\" t +.\" Copyright 2022 Alejandro Colomar <alx@kernel.org> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH strncat 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +strncat \- concatenate a null-padded character sequence into a string +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <string.h> +.PP +.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ], +.BI " size_t " sz ); +.fi +.SH DESCRIPTION +This function catenates the input character sequence +contained in a null-padded fixed-width buffer, +into a string at the buffer pointed to by +.IR dst . +The programmer is responsible for allocating a destination buffer large enough, +that is, +.IR "strlen(dst) + strnlen(src, sz) + 1" . +.PP +An implementation of this function might be: +.PP +.in +4n +.EX +char * +strncat(char *restrict dst, const char *restrict src, size_t sz) +{ + int len; + char *p; +\& + len = strnlen(src, sz); + p = dst + strlen(dst); + p = mempcpy(p, src, len); + *p = \[aq]\e0\[aq]; +\& + return dst; +} +.EE +.in +.SH RETURN VALUE +.BR strncat () +returns +.IR dst . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR strncat () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, C89, SVr4, 4.3BSD. +.SH CAVEATS +The name of this function is confusing. +This function has no relation to +.BR strncpy (3). +.PP +If the destination buffer is not large enough, +the behavior is undefined. +See +.B _FORTIFY_SOURCE +in +.BR feature_test_macros (7). +.SH BUGS +This function can be very inefficient. +Read about +.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/ +Shlemiel the painter +.UE . +.SH EXAMPLES +.\" SRC BEGIN (strncat.c) +.EX +#include <err.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define nitems(arr) (sizeof((arr)) / sizeof((arr)[0])) +\& +int +main(void) +{ + size_t maxsize; +\& + // Null-padded fixed-width character sequences + char pre[4] = "pre."; + char new_post[50] = ".foo.bar"; +\& + // Strings + char post[] = ".post"; + char src[] = "some_long_body.post"; + char *dest; +\& + maxsize = nitems(pre) + strlen(src) \- strlen(post) + + nitems(new_post) + 1; + dest = malloc(sizeof(*dest) * maxsize); + if (dest == NULL) + err(EXIT_FAILURE, "malloc()"); +\& + dest[0] = \[aq]\e0\[aq]; // There's no 'cpy' function to this 'cat'. + strncat(dest, pre, nitems(pre)); + strncat(dest, src, strlen(src) \- strlen(post)); + strncat(dest, new_post, nitems(new_post)); +\& + puts(dest); // "pre.some_long_body.foo.bar" + free(dest); + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR string (3), +.BR string_copying (3) |