_splitpath_s, _wsplitpath_s

Artikel
06/09/2015

Unterteilt einen Pfadnamen in Komponenten. Diese Versionen sind von _splitpath, _wsplitpath mit werden, wie in Sicherheitsfunktionen in der CRT beschrieben.

errno_t _splitpath_s(
   const char * path,
   char * drive,
   size_t driveNumberOfElements,
   char * dir,
   size_t dirNumberOfElements,
   char * fname,
   size_t nameNumberOfElements,
   char * ext, 
   size_t extNumberOfElements
);
errno_t _wsplitpath_s(
   const wchar_t * path,
   wchar_t * drive,
   size_t driveNumberOfElements,
   wchar_t *dir,
   size_t dirNumberOfElements,
   wchar_t * fname,
   size_t nameNumberOfElements,
   wchar_t * ext,
   size_t extNumberOfElements
);
template <size_t drivesize, size_t dirsize, size_t fnamesize, size_t extsize>
errno_t _splitpath_s(
   const char *path,
   char (&drive)[drivesize],
   char (&dir)[dirsize],
   char (&fname)[fnamesize],
   char (&ext)[extsize]
); // C++ only
template <size_t drivesize, size_t dirsize, size_t fnamesize, size_t extsize>
errno_t _wsplitpath_s(
   const wchar_t *path,
   wchar_t (&drive)[drivesize],
   wchar_t (&dir)[dirsize],
   wchar_t (&fname)[fnamesize],
   wchar_t (&ext)[extsize]
); // C++ only

Parameter

[in] path
Vollständiger Pfad.
[out] drive
Laufwerkbuchstabe, gefolgt von einem Doppelpunkt (:). Sie können NULL für diesen Parameter übergeben, wenn der Laufwerkbuchstaben benötigen.
[in] driveNumberOfElements
Die Größe des Puffers drive im Einzelbyte- oder den Breitzeichen. Wenn driveNULL ist, muss dieser Wert 0.
[out] dir
Verzeichnispfad, z nachgestellten Schrägstrich. Schrägstrich ( / ), umgekehrte Schrägstriche ( \ ) oder beide verwendet werden. Sie können NULL für diesen Parameter übergeben, wenn Sie den Verzeichnispfad benötigen.
[in] dirNumberOfElements
Die Größe des Puffers dir im Einzelbyte- oder den Breitzeichen. Wenn dirNULL ist, muss dieser Wert 0.
[out] fname
Geringer Dateiname (ohne Dateinamenerweiterung). Sie können NULL für diesen Parameter übergeben, wenn der Dateiname benötigen.
[in] nameNumberOfElements
Die Größe des Puffers fname im Einzelbyte- oder den Breitzeichen. Wenn fnameNULL ist, muss dieser Wert 0.
[out] ext
Dateinamenerweiterung, einschließlich führenden Punkt (.). Sie können NULL für diesen Parameter übergeben, wenn Sie nicht die Dateinamenerweiterung benötigen.
[in] extNumberOfElements
Die Größe von ext Puffer im Einzelbyte- oder den Breitzeichen. Wenn extNULL ist, muss dieser Wert 0.

Rückgabewert

Null, wenn erfolgreich, ein Fehlercode, wenn ein Fehler auftritt.

Fehlerbedingungen

Bedingung	Rückgabewert
path ist NULL.	EINVAL
drive ist NULL, driveNumberOfElements ist ungleich 0 (null)	EINVAL
drive ist als NULL, driveNumberOfElements ist ungewöhnlich	EINVAL
dir ist NULL, dirNumberOfElements ist ungleich 0 (null)	EINVAL
dir ist als NULL, dirNumberOfElements ist ungewöhnlich	EINVAL
fname ist NULL, nameNumberOfElements ist ungleich 0 (null)	EINVAL
fname ist als NULL, nameNumberOfElements ist ungewöhnlich	EINVAL
ext ist NULL, extNumberOfElements ist ungleich 0 (null)	EINVAL
ext ist als NULL, extNumberOfElements ist ungewöhnlich	EINVAL

Wenn eine der oben genannten Bedingungen, tritt der ungültige Parameterhandler wird aufgerufen, wie in Parametervalidierung beschrieben. Wenn die weitere Ausführung zugelassen wird, stellen diese Funktionen errno auf EINVAL ein und geben EINVAL zurück.

Wenn eine in Puffern zu kurz, das Ergebnis, freien Raum dieser Funktionen aufzunehmen ist sämtliche Puffer auf leere Zeichenfolgen, legen Sie errno auf ERANGE und geben ERANGE fest.

Hinweise

Die _splitpath_s - Funktion wird ein Pfad in seine vier Komponenten. _splitpath_s behandelt automatisch Mehrbyte-Zeichenfolgen-Argumente entsprechend und derzeit erkennt Mehrbytezeichensequenzen entsprechend der Mehrbyte-Codepage. _wsplitpath_s ist eine Breitzeichen-Version von _splitpath_s; die Argumente für _wsplitpath_s sind Zeichenfolgen mit Breitzeichen. Diese Funktionen identisch verhalten sich andernfalls

Zuordnung generischer Textroutinen

TCHAR.H-Routine	_UNICODE & _MBCS nicht definiert	_MBCS definiert	_UNICODE definiert
_tsplitpath_s	_splitpath_s	_splitpath_s	_wsplitpath_s

Jede Komponente des vollständigen Pfads wird in einem separaten Puffer gespeichert; die Manifestkonstanten _MAX_DRIVE, _MAX_DIR, _MAX_FNAME und _MAX_EXT (definiert in STDLIB.H) Geben Sie die maximal zulässige Größe für jede Dateikomponente an. Erfassen Sie die Komponenten, die als entsprechende Manifest Konstantenursachen-Heapbeschädigung größer sind.

In der folgenden Tabelle sind die Werte der Manifestkonstanten auf.

Name	Wert
_MAX_DRIVE	3
_MAX_DIR	256
_MAX_FNAME	256
_MAX_EXT	256

Wenn der vollständige Pfad keine Komponente, (beispielsweise ein Dateiname) enthält, wird _splitpath_s eine leere Zeichenfolge an den entsprechenden Puffer zu.

Die Verwendung dieser Funktionen in C++ wird durch Überladungen (als Vorlagen vorhanden) vereinfacht. Überladungen können automatisch die Pufferlänge ableiten, sodass kein Größenargument angegeben werden muss. Weitere Informationen finden Sie unter Sichere Vorlagenüberladungen.

Die Debugversionen dieser Funktionen füllen zunächst den Puffer mit "0xFD" auf. Mit _CrtSetDebugFillThreshold deaktivieren Sie dieses Verhalten.