strncat, strncat_s

 

C

Compiler-Unterstützung

Sprache

Header

Typunterstützung

Programm-Dienstprogramme

Unterstützung für variable Funktionsargumente

Fehlerbehandlung

Dynamische Speicherverwaltung

Bibliothek für Zeichenketten

Algorithmen

Numerik

Datums- und Zeitdienstprogramme

Ein-/Ausgabeunterstützung

Lokalisierungsunterstützung

Unterstützung für Nebenläufigkeit (C11)

Technische Spezifikationen

Symbolindex

 

Bibliothek für Zeichenketten

Null-terminierte Byte-Strings

Null-terminierte Multibyte-Strings

Null-terminierte breite Zeichenketten

 

Null-terminierte Byte-Strings

Funktionen
Zeichenmanipulation
isalnum isalpha islower isupper isdigit isxdigit isblank (C99)	iscntrl isgraph isspace isprint ispunct tolower toupper
Konvertierungen zu und von numerischen Formaten
atoiatolatoll (C99) atof strtolstrtoll (C99) strtoulstrtoull (C99)	strtoimaxstrtouimax (C99)(C99) strtofstrtodstrtold (C99)(C99) strfromfstrfromdstrfroml (C23)(C23)(C23)
Stringmanipulation
strcpystrcpy_s (C11) strncpystrncpy_s (C11) strcatstrcat_s (C11)	strncatstrncat_s (C11) strxfrm strdup (C23) strndup (C23)
Stringuntersuchung
strlenstrnlen_s (C11) strcmp strncmp strcoll strchr strrchr	strspn strcspn strpbrk strstr strtokstrtok_s (C11)
Speichermanipulation
memchr memcmp memsetmemset_explicitmemset_s (C23)(C11)	memcpymemcpy_s (C11) memmovememmove_s (C11) memccpy (C23)
Sonstiges
strerrorstrerror_sstrerrorlen_s (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) Hängt höchstens count Zeichen vom Zeichen-Array, auf das src zeigt, an das Ende der nullterminierten Byte-Zeichenkette, auf die dest zeigt, an. Dabei wird die Suche gestoppt, 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 (somit ist die maximale Anzahl von Bytes, die die Funktion schreiben kann, count+1).

Das Verhalten ist undefiniert, wenn das Ziel-Array nicht genügend Platz für den Inhalt von sowohl dest als auch die ersten count Zeichen von src zuzüglich des abschließenden Nullzeichens hat. Das Verhalten ist undefiniert, wenn sich die Quell- und Zielobjekte überschneiden. Das Verhalten ist undefiniert, wenn entweder dest kein Zeiger auf eine nullterminierte Byte-Zeichenkette ist oder src kein Zeiger auf ein Zeichen-Array ist,

2) Identisch mit (1), außer dass diese Funktion den Rest des Ziel-Arrays (vom letzten geschriebenen Byte bis destsz) überschreiben kann und dass die folgenden Fehler zur Laufzeit erkannt werden und die derzeit installierte Constraint Handler-Funktion 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
• Abschneiden würde auftreten: count oder die Länge von src, je nachdem, welcher Wert kleiner ist, überschreitet den verfügbaren Platz zwischen dem Nullterminator von dest und destsz.
• Es würde eine Überschneidung zwischen der Quell- und der Zielzeichenkette auftreten

Das Verhalten ist undefiniert, wenn die Größe des Zeichen-Arrays, auf das dest zeigt, < strnlen(dest,destsz)+strnlen(src,count)+1 < destsz; mit anderen Worten, ein fehlerhafter Wert von destsz deckt den drohenden Pufferüberlauf nicht auf. Das Verhalten ist undefiniert, wenn die Größe des Zeichen-Arrays, auf das src zeigt, < strnlen(src,count) < destsz; mit anderen Worten, ein fehlerhafter Wert von count deckt den drohenden Pufferüberlauf nicht auf.

Wie bei allen bounds-checked Funktionen ist strncat_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ mit der ganzzahligen Konstante 1 definiert, bevor <string.h> eingebunden wird.

Parameter

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

Rückgabewert

1) Gibt eine Kopie von dest zurück

2) Gibt Null bei Erfolg zurück, gibt einen Nicht-Null-Wert bei einem Fehler zurück. Bei einem Fehler schreibt die Funktion auch Null in dest[0] (es sei denn, dest ist ein Nullzeiger oder destsz ist Null oder größer als RSIZE_MAX).

Hinweise

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

Obwohl das Abschneiden zur Anpassung an den Zielpuffer ein Sicherheitsrisiko und daher eine Laufzeitverletzung für strncat_s darstellt, ist es möglich, das Abschneidungsverhalten zu erreichen, indem count gleich der Größe des Ziel-Arrays minus eins gesetzt 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

Führen Sie diesen Code aus

#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 Funktion strncat (S. 379)

• K.3.7.2.2 Die Funktion strncat_s (S. TBD)

• C17-Standard (ISO/IEC 9899:2018)

• 7.24.3.2 Die Funktion strncat (S. 265-266)

• K.3.7.2.2 Die Funktion strncat_s (S. 449-450)

• C11-Standard (ISO/IEC 9899:2011)

• 7.24.3.2 Die Funktion strncat (S. 364-365)

• K.3.7.2.2 Die Funktion strncat_s (S. 618-620)

• C99-Standard (ISO/IEC 9899:1999)

• 7.21.3.2 Die Funktion strncat (S. 327-328)

• C89/C90-Standard (ISO/IEC 9899:1990)

• 4.11.3.2 Die Funktion strncat

Siehe auch

strcatstrcat_s (C11)	verbindet zwei Strings (Funktion)
strcpystrcpy_s (C11)	kopiert einen String in einen anderen (Funktion)
memccpy (C23)	kopiert einen Puffer in einen anderen und stoppt nach dem angegebenen Trennzeichen (Funktion)
C++ Dokumentation für strncat