strcpy, strcpy_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* strcpy( char* dest, const char* src );			(bis C99)
char* strcpy( char* restrict dest, const char* restrict src );			(seit C99)
errno_t strcpy_s( char* restrict dest, rsize_t destsz, const char* restrict src );		(2)	(seit C11)

1) Kopiert die nullterminierte Byte-Zeichenkette, auf die src zeigt, einschließlich des Nullterminators, in das Zeichen-Array, dessen erstes Element von dest gezeigt wird.

Das Verhalten ist undefiniert, wenn das dest-Array nicht groß genug ist. Das Verhalten ist undefiniert, wenn sich die Zeichenketten überlappen. Das Verhalten ist undefiniert, wenn entweder dest kein Zeiger auf ein Zeichen-Array ist oder src kein Zeiger auf eine nullterminierte Byte-Zeichenkette ist.

2) Dasselbe wie (1), außer dass der Rest des Ziel-Arrays mit nicht spezifizierten Werten überschrieben werden kann und die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte Constraint-Handler-Funktion aufrufen.

• src oder dest ist ein Null-Zeiger
• destsz ist Null oder größer als RSIZE_MAX
• destsz ist kleiner oder gleich strnlen_s(src, destsz); anders ausgedrückt, es würde zu einer Kürzung kommen.
• 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_s(src, destsz) < destsz ist; anders ausgedrückt, ein fehlerhafter Wert von destsz deckt den drohenden Pufferüberlauf nicht auf.

Wie bei allen grenzgeprüften Funktionen ist strcpy_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Ganzzahlkonstante 1 setzt, bevor <string.h> eingebunden wird.

Parameter

dest	-	Zeiger auf das Zeichen-Array, in das geschrieben werden soll
src	-	Zeiger auf den nullterminierten Byte-String, aus dem kopiert werden soll
destsz	-	maximale Anzahl von zu schreibenden Zeichen, typischerweise die Größe des Zielpuffers

Rückgabewert

1) gibt eine Kopie von dest zurück

2) gibt Null bei Erfolg zurück, gibt einen Wert ungleich Null bei Fehler zurück. Außerdem wird bei einem Fehler Null nach dest[0] geschrieben (es sei denn, dest ist ein Null-Zeiger oder destsz ist Null oder größer als RSIZE_MAX).

Hinweise

strcpy_s darf das Ziel-Array ab dem letzten geschriebenen Zeichen bis destsz überschreiben, um die Effizienz zu verbessern: Es kann in Multibyte-Blöcken kopieren und dann auf Null-Bytes prüfen.

Die Funktion strcpy_s ähnelt der BSD-Funktion strlcpy, außer dass

• strlcpy die Quellzeichenkette auf die Größe des Ziels kürzt (was ein Sicherheitsrisiko darstellt)
• strlcpy nicht alle Laufzeitprüfungen durchführt, die strcpy_s durchführt
• strlcpy Fehler nicht offensichtlich macht, indem es das Ziel auf eine leere Zeichenkette setzt oder einen Handler aufruft, wenn der Aufruf fehlschlägt.

Obwohl strcpy_s aufgrund potenzieller Sicherheitsrisiken keine Kürzungen zulässt, ist es möglich, eine Zeichenkette mit der grenzgeprüften Funktion strncpy_s zu kürzen.

Beispiel

Führen Sie diesen Code aus

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
int main(void)
{
    const char* src = "Take the test.";
//  src[0] = 'M' ; // this would be undefined behavior
    char dst[strlen(src) + 1]; // +1 to accommodate for the null terminator
    strcpy(dst, src);
    dst[0] = 'M'; // OK
    printf("src = %s\ndst = %s\n", src, dst);
 
#ifdef __STDC_LIB_EXT1__
    set_constraint_handler_s(ignore_handler_s);
    int r = strcpy_s(dst, sizeof dst, src);
    printf("dst = \"%s\", r = %d\n", dst, r);
    r = strcpy_s(dst, sizeof dst, "Take even more tests.");
    printf("dst = \"%s\", r = %d\n", dst, r);
#endif
}

Mögliche Ausgabe

src = Take the test.
dst = Make the test.
dst = "Take the test.", r = 0
dst = "", r = 22

Referenzen

• C23-Standard (ISO/IEC 9899:2024)

• 7.24.2.3 Die Funktion strcpy (S. TBD)

• K.3.7.1.3 Die Funktion strcpy_s (S. TBD)

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

• 7.24.2.3 Die Funktion strcpy (S. 264-265)

• K.3.7.1.3 Die Funktion strcpy_s (S. 447)

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

• 7.24.2.3 Die Funktion strcpy (S. 363)

• K.3.7.1.3 Die Funktion strcpy_s (S. 615-616)

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

• 7.21.2.3 Die Funktion strcpy (S. 326)

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

• 4.11.2.3 Die Funktion strcpy

Siehe auch

strncpystrncpy_s (C11)	kopiert eine bestimmte Anzahl von Zeichen von einem String in einen anderen (Funktion)
memcpymemcpy_s (C11)	kopiert einen Puffer in einen anderen (Funktion)
wcscpywcscpy_s (C95)(C11)	kopiert eine breite Zeichenkette in eine andere (Funktion)
strdup (Dynamischer Speicher-TR)	kopiert einen String, indem Speicher zugewiesen wird (Funktion)
C++ Dokumentation für strcpy