man3/strncat.3

   1 '\" t
   2 .\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH strncat 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 strncat \- concatenate a null-padded character sequence into a string
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <string.h>
  15 .P
  16 .BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ],
  17 .BI "               size_t " sz );
  18 .fi
  19 .SH DESCRIPTION
  20 This function catenates the input character sequence
  21 contained in a null-padded fixed-width buffer,
  22 into a string at the buffer pointed to by
  23 .IR dst .
  24 The programmer is responsible for allocating a destination buffer large enough,
  25 that is,
  26 .IR "strlen(dst) + strnlen(src, sz) + 1" .
  27 .P
  28 An implementation of this function might be:
  29 .P
  30 .in +4n
  31 .EX
  32 char *
  33 strncat(char *restrict dst, const char *restrict src, size_t sz)
  34 {
  35     int   len;
  36     char  *p;
  37 \&
  38     len = strnlen(src, sz);
  39     p = dst + strlen(dst);
  40     p = mempcpy(p, src, len);
  41     *p = \[aq]\e0\[aq];
  42 \&
  43     return dst;
  44 }
  45 .EE
  46 .in
  47 .SH RETURN VALUE
  48 .BR strncat ()
  49 returns
  50 .IR dst .
  51 .SH ATTRIBUTES
  52 For an explanation of the terms used in this section, see
  53 .BR attributes (7).
  54 .TS
  55 allbox;
  56 lbx lb lb
  57 l l l.
  58 Interface       Attribute       Value
  59 T{
  60 .na
  61 .nh
  62 .BR strncat ()
  63 T}      Thread safety   MT-Safe
  64 .TE
  65 .SH STANDARDS
  66 C11, POSIX.1-2008.
  67 .SH HISTORY
  68 POSIX.1-2001, C89, SVr4, 4.3BSD.
  69 .SH CAVEATS
  70 The name of this function is confusing.
  71 This function has no relation to
  72 .BR strncpy (3).
  73 .P
  74 If the destination buffer is not large enough,
  75 the behavior is undefined.
  76 See
  77 .B _FORTIFY_SOURCE
  78 in
  79 .BR feature_test_macros (7).
  80 .SH BUGS
  81 This function can be very inefficient.
  82 Read about
  83 .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
  84 Shlemiel the painter
  85 .UE .
  86 .SH EXAMPLES
  87 .\" SRC BEGIN (strncat.c)
  88 .EX
  89 #include <err.h>
  90 #include <stdio.h>
  91 #include <stdlib.h>
  92 #include <string.h>
  93 \&
  94 #define nitems(arr)  (sizeof((arr)) / sizeof((arr)[0]))
  95 \&
  96 int
  97 main(void)
  98 {
  99     size_t  maxsize;
 100 \&
 101     // Null-padded fixed-width character sequences
 102     char    pre[4] = "pre.";
 103     char    new_post[50] = ".foo.bar";
 104 \&
 105     // Strings
 106     char    post[] = ".post";
 107     char    src[] = "some_long_body.post";
 108     char    *dest;
 109 \&
 110     maxsize = nitems(pre) + strlen(src) \- strlen(post) +
 111               nitems(new_post) + 1;
 112     dest = malloc(sizeof(*dest) * maxsize);
 113     if (dest == NULL)
 114         err(EXIT_FAILURE, "malloc()");
 115 \&
 116     dest[0] = \[aq]\e0\[aq];  // There's no 'cpy' function to this 'cat'.
 117     strncat(dest, pre, nitems(pre));
 118     strncat(dest, src, strlen(src) \- strlen(post));
 119     strncat(dest, new_post, nitems(new_post));
 120 \&
 121     puts(dest);  // "pre.some_long_body.foo.bar"
 122     free(dest);
 123     exit(EXIT_SUCCESS);
 124 }
 125 .EE
 126 .\" SRC END
 127 .in
 128 .SH SEE ALSO
 129 .BR string (3),
 130 .BR string_copying (3)