lstrcpynW-Funktion (winbase.h)

Artikel
08/27/2023

Kopiert eine angegebene Anzahl von Zeichen aus einer Quellzeichenfolge in einen Puffer.

Warnung Verwenden Sie nicht. Erwägen Sie stattdessen die Verwendung von StringCchCopy . Siehe Hinweise.

Syntax

LPWSTR lstrcpynW(
  [out] LPWSTR  lpString1,
  [in]  LPCWSTR lpString2,
  [in]  int     iMaxLength
);

Parameter

[out] lpString1

Typ: LPTSTR

Der Zielpuffer, der die kopierten Zeichen empfängt. Der Puffer muss groß genug sein, um die anzahl der von iMaxLength angegebenen TCHAR-Werte zu enthalten, einschließlich des Platzes für ein abschließendes NULL-Zeichen.

[in] lpString2

Typ: LPCTSTR

Die Quellzeichenfolge, aus der die Funktion Zeichen kopieren soll.

[in] iMaxLength

Typ: int

Die Anzahl der TCHAR-Werte , die aus der Zeichenfolge kopiert werden sollen, auf die lpString2 in den Puffer zeigt, auf den lpString1 verweist, einschließlich eines abschließenden NULL-Zeichens.

Rückgabewert

Typ: LPTSTR

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Zeiger auf den Puffer. Die Funktion kann auch dann erfolgreich sein, wenn die Quellzeichenfolge größer als iMaxLength-Zeichen ist.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL , und lpString1 ist möglicherweise nicht null-beendet.

Hinweise

Der Puffer, auf den lpString1 verweist, muss groß genug sein, um ein abschließendes NULL-Zeichen einzuschließen, und der von iMaxLength angegebene Zeichenfolgenlängenwert enthält Platz für ein abschließendes NULL-Zeichen.

Die lstrcpyn-Funktion weist ein undefiniertes Verhalten auf, wenn sich Quell- und Zielpuffer überlappen.

Sicherheitswarnung

Die falsche Verwendung dieser Funktion kann die Sicherheit Ihrer Anwendung beeinträchtigen. Diese Funktion verwendet die strukturierte Ausnahmebehandlung (Structured Exception Handling, SEH), um Zugriffsverletzungen und andere Fehler abzufangen. Wenn diese Funktion SEH-Fehler abfängt, gibt sie NULL zurück, ohne die Zeichenfolge zu beenden und den Aufrufer über den Fehler zu benachrichtigen. Der Aufrufer kann nicht davon ausgehen, dass nicht genügend Speicherplatz die Fehlerbedingung ist.

Wenn der Puffer, auf den lpString1 verweist, nicht groß genug ist, um die kopierte Zeichenfolge zu enthalten, kann es zu einem Pufferüberlauf kommen. Beachten Sie beim Kopieren einer gesamten Zeichenfolge, dass sizeof die Anzahl von Bytes zurückgibt. Wenn beispielsweise lpString1 auf einen Puffer szString1 zeigt, der als TCHAR szString[100]deklariert ist, gibt sizeof(szString1) die Größe des Puffers in Bytes anstelle von WCHAR an, was zu einem Pufferüberlauf für die Unicode-Version der Funktion führen könnte.

Pufferüberlaufsituationen sind die Ursache für viele Sicherheitsprobleme in Anwendungen und können einen Denial-of-Service-Angriff auf die Anwendung verursachen, wenn eine Zugriffsverletzung auftritt. Im schlimmsten Fall kann ein Pufferüberlauf es einem Angreifer ermöglichen, ausführbaren Code in Ihren Prozess einzufügen, insbesondere wenn lpString1 ein stapelbasierter Puffer ist.

Die Verwendung von sizeof(szString1)/sizeof(szString1[0]) gibt die richtige Größe des Puffers an.

Erwägen Sie stattdessen die Verwendung von StringCchCopy . verwenden Sie entweder StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src);, da sie sich bewusst sind, dass buffer kein Zeiger sein darf, oder verwenden Sie StringCchCopy(buffer, ARRAYSIZE(buffer), src);, wenn Sie wissen, dass der Aufrufer beim Kopieren in einen Zeiger für die Übergabe der Größe des zeigerfähigen Speichers in Zeichen verantwortlich ist.

Überprüfen Sie Sicherheitsüberlegungen: Windows-Benutzeroberfläche , bevor Sie fortfahren.

Hinweis

Der winbase.h-Header definiert lstrcpyn als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll