strncat(3)

1strncat(3)                 Library Functions Manual                 strncat(3)
2
3
4

NAME

6       strncat - concatenate a null-padded character sequence into a string
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <string.h>
13
14       char *strncat(char *restrict dst, const char src[restrict .sz],
15                      size_t sz);
16

DESCRIPTION

18       This  function  catenates  the  input character sequence contained in a
19       null-padded fixed-width buffer, into a string at the buffer pointed  to
20       by  dst.   The  programmer  is responsible for allocating a destination
21       buffer large enough, that is, strlen(dst) + strnlen(src, sz) + 1.
22
23       An implementation of this function might be:
24
25           char *
26           strncat(char *restrict dst, const char *restrict src, size_t sz)
27           {
28               int   len;
29               char  *p;
30
31               len = strnlen(src, sz);
32               p = dst + strlen(dst);
33               p = mempcpy(p, src, len);
34               *p = '\0';
35
36               return dst;
37           }
38

RETURN VALUE

40       strncat() returns dst.
41

ATTRIBUTES

43       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
44       tributes(7).
45
46       ┌────────────────────────────────────────────┬───────────────┬─────────┐
47       │Interface                                   │ Attribute     │ Value   │
48       ├────────────────────────────────────────────┼───────────────┼─────────┤
49       │strncat()                                   │ Thread safety │ MT-Safe │
50       └────────────────────────────────────────────┴───────────────┴─────────┘
51

STANDARDS

53       C11, POSIX.1-2008.
54

HISTORY

56       POSIX.1-2001, C89, SVr4, 4.3BSD.
57

CAVEATS

59       The  name of this function is confusing.  This function has no relation
60       to strncpy(3).
61
62       If the  destination  buffer  is  not  large  enough,  the  behavior  is
63       undefined.  See _FORTIFY_SOURCE in feature_test_macros(7).
64

BUGS

66       This function can be very inefficient.  Read about Shlemiel the painter
67       ⟨https://www.joelonsoftware.com/2001/12/11/back-to-basics/⟩.
68

EXAMPLES

70       #include <err.h>
71       #include <stdio.h>
72       #include <stdlib.h>
73       #include <string.h>
74
75       #define nitems(arr)  (sizeof((arr)) / sizeof((arr)[0]))
76
77       int
78       main(void)
79       {
80           size_t  maxsize;
81
82           // Null-padded fixed-width character sequences
83           char    pre[4] = "pre.";
84           char    new_post[50] = ".foo.bar";
85
86           // Strings
87           char    post[] = ".post";
88           char    src[] = "some_long_body.post";
89           char    *dest;
90
91           maxsize = nitems(pre) + strlen(src) - strlen(post) +
92                     nitems(new_post) + 1;
93           dest = malloc(sizeof(*dest) * maxsize);
94           if (dest == NULL)
95               err(EXIT_FAILURE, "malloc()");
96
97           dest[0] = '\0';  // There's no 'cpy' function to this 'cat'.
98           strncat(dest, pre, nitems(pre));
99           strncat(dest, src, strlen(src) - strlen(post));
100           strncat(dest, new_post, nitems(new_post));
101
102           puts(dest);  // "pre.some_long_body.foo.bar"
103           free(dest);
104           exit(EXIT_SUCCESS);
105       }
106