wcsncpy, wcsncpy_s

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 des Wide-Strings, auf den src zeigt (einschließlich des abschließenden Null-Wide-Zeichens), in das Wide-Zeichen-Array, auf das dest zeigt.

Wenn count erreicht ist, bevor der gesamte String src kopiert wurde, wird das resultierende Wide-Zeichen-Array nicht null-terminiert.

Wenn nach dem Kopieren des abschließenden Null-Wide-Zeichens aus src count nicht erreicht ist, werden zusätzliche Null-Wide-Zeichen in dest geschrieben, bis insgesamt count Zeichen geschrieben wurden.

Wenn die Strings überlappen, ist das Verhalten undefiniert.

2) Ähnlich wie (1), außer dass die Funktion das Auffüllen des Zielarrays mit Nullen bis zu count nicht fortsetzt, sondern nach dem Schreiben des abschließenden Null-Zeichens stoppt (wenn die Quelle kein Null-Zeichen enthielt, wird eines bei dest[count] geschrieben und dann gestoppt). Außerdem werden die folgenden Fehler zur Laufzeit erkannt und rufen die aktuell installierte Constraint Handler-Funktion auf.

src oder dest ist ein Nullzeiger
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, eine Abschneidung würde auftreten
Es würde eine Überschneidung zwischen der Quell- und der Zielzeichenkette auftreten

Wie bei allen grenzgeprüften Funktionen ist wcsncpy_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <wchar.h> auf die Ganzzahlkonstante 1 setzt.

[bearbeiten] Parameter

dest	-	Zeiger auf das Wide-Zeichen-Array, in das kopiert werden soll
src	-	Zeiger auf den zu kopierenden Wide-String
zählt	-	maximale Anzahl von zu kopierenden Zeichen
destsz	-	die Größe des Zielpuffers

[bearbeiten] Rückgabewert

1) Gibt eine Kopie von dest zurück

2) gibt Null bei Erfolg zurück, gibt einen Nicht-Null-Wert bei Fehler zurück. Bei einem Fehler wird außerdem L'\0' in dest[0] geschrieben (es sei denn, dest ist ein Null-Zeiger oder destsz ist Null oder größer als RSIZE_MAX/sizeof(wchar_t)) und der Rest des Zielarrays kann mit nicht spezifizierten Werten überschrieben werden.

[bearbeiten] Hinweise

Bei typischer Verwendung ist count die Anzahl der Elemente im Zielarray.

Obwohl eine Abschneidung zur Anpassung an den Zielpuffer ein Sicherheitsrisiko darstellt und daher eine Verletzung der Laufzeitbedingungen für wcsncpy_s ist, ist es möglich, das Abschneidungsverhalten zu erzielen, indem count gleich der Größe des Zielarrays minus eins gesetzt wird: Es werden die ersten count Wide-Zeichen kopiert und wie immer der Null-Wide-Terminator angehängt: wcsncpy_s(dst, sizeof dst / sizeof *dst, src, (sizeof dst / sizeof *dst)-1);

[bearbeiten] Beispiel

Führen Sie diesen Code aus

#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

[bearbeiten] Referenzen

C17-Standard (ISO/IEC 9899:2018)

7.29.4.2.2 Die Funktion wcsncpy (S. 314)

K.3.9.2.1.2 Die Funktion wcsncpy_s (S. 464)

C11-Standard (ISO/IEC 9899:2011)

7.29.4.2.2 Die Funktion wcsncpy (S. 431)

K.3.9.2.1.2 Die Funktion wcsncpy_s (S. 640-641)

C99-Standard (ISO/IEC 9899:1999)

7.24.4.2.2 Die Funktion wcsncpy (S. 377)

[bearbeiten] Siehe auch

wcscpywcscpy_s (C95)(C11)	kopiert eine breite Zeichenkette in eine andere (Funktion) [bearbeiten]
wmemcpywmemcpy_s (C95)(C11)	kopiert eine bestimmte Anzahl breiter Zeichen zwischen zwei nicht überlappenden Arrays (Funktion) [bearbeiten]
strncpystrncpy_s (C11)	kopiert eine bestimmte Anzahl von Zeichen von einem String in einen anderen (Funktion) [bearbeiten]
C++ Dokumentation für wcsncpy

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

cppreference.com

Namensräume

Varianten

Ansichten

Aktionen