summaryrefslogtreecommitdiffstats
path: root/man3/strncat.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/strncat.3')
-rw-r--r--man3/strncat.367
1 files changed, 34 insertions, 33 deletions
diff --git a/man3/strncat.3 b/man3/strncat.3
index f53c930..74848c9 100644
--- a/man3/strncat.3
+++ b/man3/strncat.3
@@ -3,43 +3,45 @@
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
-.TH strncat 3 2023-07-20 "Linux man-pages 6.05.01"
+.TH strncat 3 2023-12-05 "Linux man-pages 6.7"
.SH NAME
-strncat \- concatenate a null-padded character sequence into a string
+strncat
+\-
+append non-null bytes from a source array to a string,
+and null-terminate the result
.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 );
+.P
+.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." ssize ],
+.BI " size_t " ssize );
.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
+This function appends at most
+.I ssize
+non-null bytes from the array pointed to by
+.IR src ,
+followed by a null character,
+to the end of the string 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
+.I dst
+must point to a string contained in a buffer that is large enough,
+that is, the buffer size must be at least
+.IR "strlen(dst) + strnlen(src, ssize) + 1" .
+.P
An implementation of this function might be:
-.PP
+.P
.in +4n
.EX
char *
-strncat(char *restrict dst, const char *restrict src, size_t sz)
+strncat(char *restrict dst, const char *restrict src, size_t ssize)
{
- int len;
- char *p;
-\&
- len = strnlen(src, sz);
- p = dst + strlen(dst);
- p = mempcpy(p, src, len);
- *p = \[aq]\e0\[aq];
+ #define strnul(s) (s + strlen(s))
\&
+ stpcpy(mempcpy(strnul(dst), src, strnlen(src, ssize)), "");
return dst;
}
.EE
@@ -62,17 +64,17 @@ T{
.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
+The name of this function is confusing;
+it has no relation to
.BR strncpy (3).
-.PP
-If the destination buffer is not large enough,
+.P
+If the destination buffer does not already contain a string,
+or is not large enough,
the behavior is undefined.
See
.B _FORTIFY_SOURCE
@@ -82,7 +84,7 @@ in
This function can be very inefficient.
Read about
.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
-Shlemiel the painter
+Shlemiel the painter
.UE .
.SH EXAMPLES
.\" SRC BEGIN (strncat.c)
@@ -97,9 +99,9 @@ Shlemiel the painter
int
main(void)
{
- size_t maxsize;
+ size_t n;
\&
- // Null-padded fixed-width character sequences
+ // Null-padded fixed-size character sequences
char pre[4] = "pre.";
char new_post[50] = ".foo.bar";
\&
@@ -108,9 +110,8 @@ main(void)
char src[] = "some_long_body.post";
char *dest;
\&
- maxsize = nitems(pre) + strlen(src) \- strlen(post) +
- nitems(new_post) + 1;
- dest = malloc(sizeof(*dest) * maxsize);
+ n = nitems(pre) + strlen(src) \- strlen(post) + nitems(new_post) + 1;
+ dest = malloc(sizeof(*dest) * n);
if (dest == NULL)
err(EXIT_FAILURE, "malloc()");
\&
@@ -128,4 +129,4 @@ main(void)
.in
.SH SEE ALSO
.BR string (3),
-.BR string_copying (3)
+.BR string_copying (7)