Namespaces
Variants

wcsncpy, wcsncpy_s

From cppreference.net
< c ‎ | string ‎ | wide
C
Strings library
Null-terminated wide strings
Definiert in Header <wchar.h>
(1)
wchar_t * wcsncpy ( wchar_t * dest, const wchar_t * src, size_t count ) ;
(seit C95)
(bis C99)
wchar_t * wcsncpy ( wchar_t * restrict dest, const wchar_t * restrict src, size_t count ) ;
(seit C99)
errno_t wcsncpy_s ( wchar_t * restrict dest, rsize_t destsz,
const wchar_t * restrict src, rsize_t count ) ;
(2) (seit C11)
1) Kopiert höchstens count Zeichen der breiten Zeichenkette, auf die src zeigt (einschließlich des abschließenden Nullbreitzeichens), in das breite Zeichenarray, auf das dest zeigt.
Wenn count erreicht wird, bevor der gesamte String src kopiert wurde, ist das resultierende Breitzeichen-Array nicht nullterminiert.
Falls nach dem Kopieren des abschließenden Null-Breitzeichens aus src , count nicht erreicht ist, werden zusätzliche Null-Breitzeichen in dest geschrieben, bis insgesamt count Zeichen geschrieben wurden.
Wenn sich die Zeichenketten überlappen, ist das Verhalten undefiniert.
2) Gleich wie (1) , außer dass die Funktion nicht mit dem Schreiben von Nullen in das Zielarray fortsetzt, um bis count aufzufüllen, sondern nach dem Schreiben des abschließenden Nullzeichens stoppt (wenn keine Null in der Quelle vorhanden war, schreibt sie eine an dest [ count ] und stoppt dann). Zudem werden die folgenden Fehler zur Laufzeit erkannt und rufen die aktuell installierte constraint handler -Funktion auf:
  • src oder dest ist ein null pointer
  • destsz oder count ist null oder größer als RSIZE_MAX / sizeof ( wchar_t )
  • count ist größer oder gleich destsz , aber destsz ist kleiner oder gleich wcsnlen_s ( src, count ) , mit anderen Worten, es würde ein Truncation auftreten
  • Überlappung würde zwischen den Quell- und Zielzeichenketten auftreten
Wie bei allen bounds-checked-Funktionen ist wcsncpy_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 setzt, bevor <wchar.h> inkludiert wird.

Inhaltsverzeichnis

Parameter

dest - Zeiger auf das Breitzeichen-Array, in das kopiert werden soll
src - Zeiger auf die zu kopierende Breitzeichen-Zeichenkette
count - maximale Anzahl der zu kopierenden Breitzeichen
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 Nicht-Null-Wert zurück. Außerdem wird bei Fehler L ' \0 ' in dest [ 0 ] geschrieben (sofern dest kein Nullzeiger ist und destsz weder Null noch größer als RSIZE_MAX / sizeof ( wchar_t ) ist) und der Rest des Zielarrays kann mit unspezifizierten Werten überschrieben werden.

Hinweise

Im typischen Gebrauch ist count die Anzahl der Elemente im Zielarray.

Obwohl das Abschneiden zur Anpassung an den Zielpuffer ein Sicherheitsrisiko darstellt und daher einen Verstoß gegen die Laufzeitbedingungen für wcsncpy_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 Breitzeichen kopiert und wie immer der Null-Breitzeichen-Abschluss angehängt: wcsncpy_s ( dst, sizeof dst / sizeof * dst, src, ( sizeof dst / sizeof * dst ) - 1 ) ;

Beispiel

Diesen Code ausführen 
#include <stdio.h>
#include <wchar.h>
#include <locale.h>
int main(void)
{
    const wchar_t src[] = L"わゐ";
    wchar_t dest[6] = {L'あ', L'い', L'う', L'え', L'お'};
    wcsncpy(dest, src, 4); // this will copy わゐ and repeat L'\0' two times
    puts("The contents of dest are: ");
    setlocale(LC_ALL, "en_US.utf8");
    const long dest_size = sizeof dest / sizeof *dest;
    for(wchar_t* p = dest; p-dest != dest_size; ++p) {
        *p ? printf("%lc ", *p)
           : printf("\\0 ");
    }
}

Mögliche Ausgabe: 

The contents of dest are: 
わ ゐ \0 \0 お \0

Referenzen

  • C17-Standard (ISO/IEC 9899:2018):
  • 7.29.4.2.2 Die wcsncpy-Funktion (S. 314)
  • K.3.9.2.1.2 Die wcsncpy_s-Funktion (S. 464)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.29.4.2.2 Die wcsncpy-Funktion (S: 431)
  • K.3.9.2.1.2 Die wcsncpy_s-Funktion (S: 640-641)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.24.4.2.2 Die wcsncpy-Funktion (S: 377)

Siehe auch

(C95) (C11)
kopiert eine Breitzeichen-Zeichenkette in eine andere
(Funktion)
(C95) (C11)
kopiert eine bestimmte Anzahl von Breitzeichen zwischen zwei nicht überlappenden Arrays
(Funktion)
(C11)
kopiert eine bestimmte Anzahl von Zeichen von einer Zeichenkette in eine andere
(Funktion)
C++-Dokumentation für wcsncpy