Namespaces
Variants

strncat, strncat_s

From cppreference.net
< c ‎ | string ‎ | byte
C
Strings library
Null-terminated byte strings
Functions
Character manipulation
Conversions to and from numeric formats
String manipulation
strncat strncat_s
(C11)
(C23)
(C23)

String examination
Memory manipulation
Miscellaneous
(C11) (C11)
Definiert in Header <string.h>
(1)
char * strncat ( char * dest, const char * src, size_t count ) ;
(bis C99)
char * strncat ( char * restrict dest, const char * restrict src, size_t count ) ;
(seit C99)
errno_t strncat_s ( char * restrict dest, rsize_t destsz,
const char * restrict src, rsize_t count ) ;
(2) (seit C11)
1) Fügt maximal count Zeichen aus dem Zeichenarray, auf das src zeigt, an das Ende der nullterminierten Byte-Zeichenkette, auf die dest zeigt, an und stoppt, wenn das Nullzeichen gefunden wird. Das Zeichen src [ 0 ] ersetzt den Nullterminator am Ende von dest . Das abschließende Nullzeichen wird immer am Ende angehängt (daher beträgt die maximale Anzahl der Bytes, die die Funktion schreiben kann, count + 1 ).
Das Verhalten ist undefiniert, wenn das Zielarray nicht genügend Platz für die Inhalte von sowohl dest als auch den ersten count Zeichen von src plus dem abschließenden Nullzeichen hat. Das Verhalten ist undefiniert, wenn sich die Quell- und Zielobjekte überlappen. Das Verhalten ist undefiniert, wenn entweder dest kein Zeiger auf eine nullterminierte Byte-Zeichenkette ist oder src kein Zeiger auf ein Zeichenarray ist.
2) Gleich wie (1) , mit der Ausnahme, dass diese Funktion den restlichen Teil des Zielarrays (vom letzten geschriebenen Byte bis zu destsz ) überschreiben kann und dass die folgenden Fehler zur Laufzeit erkannt werden und den aktuell installierten constraint handler aufrufen:
  • src oder dest ist ein Nullzeiger
  • destsz oder count ist null oder größer als RSIZE_MAX
  • es gibt kein Nullzeichen in den ersten destsz Bytes von dest
  • Trunkierung würde auftreten: count oder die Länge von src , je nachdem welcher kleiner ist, überschreitet den verfügbaren Platz zwischen dem Nullterminator von dest und destsz .
  • Überlappung würde zwischen den Quell- und Zielzeichenfolgen auftreten
Das Verhalten ist undefiniert, wenn die Größe des Zeichenarrays, auf das dest zeigt, < strnlen ( dest,destsz ) + strnlen ( src,count ) + 1 < destsz ; mit anderen Worten, ein fehlerhafter Wert von destsz macht den drohenden Pufferüberlauf nicht sichtbar. Das Verhalten ist undefiniert, wenn die Größe des Zeichenarrays, auf das src zeigt, < strnlen ( src,count ) < destsz ; mit anderen Worten, ein fehlerhafter Wert von count macht den drohenden Pufferüberlauf nicht sichtbar.
Wie bei allen grenzprüfenden Funktionen ist strncat_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf den Integer-Konstantenwert 1 setzt, bevor <string.h> eingebunden wird.

Inhaltsverzeichnis

Parameter

dest - Zeiger auf die nullterminierte Byte-Zeichenkette, an die angehängt werden soll
src - Zeiger auf das Zeichenarray, aus dem kopiert werden soll
count - maximale Anzahl der zu kopierenden Zeichen
destsz - Größe des Zielpuffers

Rückgabewert

1) gibt eine Kopie von dest zurück
2) gibt bei Erfolg Null zurück, gibt bei Fehler einen Wert ungleich Null zurück. Außerdem wird bei einem Fehler Null in dest [ 0 ] geschrieben (sofern dest kein Nullzeiger ist und destsz nicht Null oder größer als RSIZE_MAX ist).

Hinweise

Da strncat bei jedem Aufruf bis zum Ende von dest suchen muss, ist es ineffizient, viele Zeichenketten mit strncat zu einer zu verketten.

Obwohl das Abschneiden zur Anpassung an den Zielpuffer ein Sicherheitsrisiko darstellt und daher einen Verstoß gegen die Laufzeitbedingungen für strncat_s bedeutet, ist es möglich, das abschneidende Verhalten zu erreichen, indem count gleich der Größe des Zielarrays minus eins angegeben wird: Es werden die ersten count Bytes kopiert und wie immer der Nullterminator angehängt: strncat_s ( dst, sizeof dst, src, ( sizeof dst ) - strnlen_s ( dst, sizeof dst ) - 1 ) ;

Beispiel

Diesen Code ausführen 
#define __STDC_WANT_LIB_EXT1__ 1
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
int main(void)
{
    char str[50] = "Hello ";
    char str2[50] = "World!";
    strcat(str, str2);
    strncat(str, " Goodbye World!", 3);
    puts(str);
#ifdef __STDC_LIB_EXT1__
    set_constraint_handler_s(ignore_handler_s);
    char s1[100] = "good";
    char s5[1000] = "bye";
    int r1 = strncat_s(s1, 100, s5, 1000); // r1 is 0, s1 holds "goodbye\0"
    printf("s1 = %s, r1 = %d\n", s1, r1);
    char s2[6] = "hello";
    int r2 = strncat_s(s2, 6, "", 1); // r2 is 0, s2 holds "hello\0"
    printf("s2 = %s, r2 = %d\n", s2, r2);
    char s3[6] = "hello";
    int r3 = strncat_s(s3, 6, "X", 2); // r3 is non-zero, s3 holds "\0"
    printf("s3 = %s, r3 = %d\n", s3, r3);
    // the strncat_s truncation idiom:
    char s4[7] = "abc";
    int r4 = strncat_s(s4, 7, "defghijklmn", 3); // r4 is 0, s4 holds "abcdef\0"
    printf("s4 = %s, r4 = %d\n", s4, r4);
#endif
}

Mögliche Ausgabe: 

Hello World! Go
s1 = goodbye, r1 = 0
s2 = hello, r2 = 0
s3 = , r3 = 22
s4 = abcdef, r4 = 0

Referenzen

  • C23-Standard (ISO/IEC 9899:2024):
  • 7.26.3.2 Die strncat-Funktion (S: 379)
  • K.3.7.2.2 Die strncat_s-Funktion (S: TBD)
  • C17-Standard (ISO/IEC 9899:2018):
  • 7.24.3.2 Die strncat-Funktion (S: 265-266)
  • K.3.7.2.2 Die strncat_s-Funktion (S: 449-450)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.24.3.2 Die strncat-Funktion (S: 364-365)
  • K.3.7.2.2 Die strncat_s-Funktion (S: 618-620)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.21.3.2 Die strncat-Funktion (S: 327-328)
  • C89/C90 Standard (ISO/IEC 9899:1990):
  • 4.11.3.2 Die strncat-Funktion

Siehe auch

(C11)
verkettet zwei Zeichenketten
(Funktion)
(C11)
kopiert eine Zeichenkette in eine andere
(Funktion)
(C23)
kopiert einen Puffer in einen anderen, stoppt nach dem angegebenen Trennzeichen
(Funktion)
C++-Dokumentation für strncat