Namespaces
Variants

strcpy, strcpy_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
strcpy strcpy_s
(C11)
(C11)
(C11)
String examination
Memory manipulation
Miscellaneous
(C11) (C11)
Definiert im 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 Zeichenarray, dessen erstes Element durch 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 Zeichenarray ist oder src kein Zeiger auf eine nullterminierte Byte-Zeichenkette ist.
2) Gleich wie (1) , außer dass es den Rest des Zielarrays mit nicht spezifizierten Werten überschreiben kann und dass die folgenden Fehler zur Laufzeit erkannt werden und die aktuell installierte constraint handler -Funktion aufrufen:
  • src oder dest ist ein Nullzeiger
  • destsz ist null oder größer als RSIZE_MAX
  • destsz ist kleiner oder gleich strnlen_s ( src, destsz ) ; mit anderen Worten, es würde ein Abschneiden auftreten
  • es würde eine Überlappung zwischen Quell- und Zielzeichenfolge auftreten
Das Verhalten ist undefiniert, wenn die Größe des Zeichenarrays, auf das dest <= strnlen_s ( src, destsz ) < destsz ; mit anderen Worten, ein fehlerhafter Wert von destsz kann einen Pufferüberlauf ermöglichen.
Wie bei allen grenzprüfenden Funktionen ist strcpy_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 das Zeichenarray, in das geschrieben werden soll
src - Zeiger auf die nullterminierte Byte-Zeichenkette, von der kopiert werden soll
destsz - maximale Anzahl der zu schreibenden Zeichen, typischerweise die 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 oder destsz nicht Null oder größer als RSIZE_MAX ist).

Hinweise

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

Die Funktion strcpy_s ähnelt der BSD-Funktion strlcpy , mit der Ausnahme, dass

  • strlcpy kürzt den Quellstring, um in das Ziel zu passen (was ein Sicherheitsrisiko darstellt)
  • strlcpy führt nicht alle Laufzeitprüfungen durch, die strcpy_s durchführt
  • strlcpy macht Fehler nicht offensichtlich, indem das Ziel auf einen Nullstring gesetzt oder ein Handler bei Aufrufversagen aufgerufen wird.

Obwohl strcpy_s das Abschneiden aufgrund möglicher Sicherheitsrisiken verbietet, ist es möglich, einen String mithilfe des grenzgeprüften strncpy_s abzuschneiden.

Beispiel

Diesen Code ausführen 
#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 strcpy-Funktion (S.: TBD)
  • K.3.7.1.3 Die strcpy_s-Funktion (S.: TBD)
  • C17-Standard (ISO/IEC 9899:2018):
  • 7.24.2.3 Die strcpy-Funktion (S. 264-265)
  • K.3.7.1.3 Die strcpy_s-Funktion (S. 447)
  • C11 Standard (ISO/IEC 9899:2011):
  • 7.24.2.3 Die strcpy-Funktion (S: 363)
  • K.3.7.1.3 Die strcpy_s-Funktion (S: 615-616)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.21.2.3 Die strcpy-Funktion (S: 326)
  • C89/C90 Standard (ISO/IEC 9899:1990):
  • 4.11.2.3 Die strcpy-Funktion

Siehe auch

(C11)
kopiert eine bestimmte Anzahl von Zeichen von einer Zeichenkette in eine andere
(Funktion)
(C11)
kopiert einen Puffer in einen anderen
(Funktion)
(C95) (C11)
kopiert eine Wide-String in eine andere
(Funktion)
(dynamic memory TR)
erstellt eine Kopie einer Zeichenkette durch Allokation
(Funktion)
C++-Dokumentation für strcpy