summaryrefslogtreecommitdiffstats
path: root/man3/strncat.3
blob: f53c9309ac76b6fc339112b258d1b07e8b320cc1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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)