_splitpath_s、_wsplitpath_s

[アーティクル]
08/09/2011

パス名を構成要素に分解します。 _splitpath、_wsplitpath には、「CRT のセキュリティ機能」に説明されているように、セキュリティが強化されたバージョンがあります。

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

パラメーター

[入力] path
完全パス。
[出力] drive
ドライブ文字。後ろにコロン (:) が付きます。ドライブ文字が不要な場合は、このパラメーターに NULL を渡すことができます。
[入力] driveNumberOfElements
drive バッファーのサイズ (1 バイト文字またはワイド文字の数)。 drive が NULL の場合は、この値を 0 にする必要があります。
[出力] dir
ディレクトリパスと末尾のスラッシュ。区切り記号にはスラッシュ (/ ) および円記号 (\) を使用でき、両方を混在させることもできます。ディレクトリパスが不要な場合は、このパラメーターに NULL を渡すことができます。
[入力] dirNumberOfElements
dir バッファーのサイズ (1 バイト文字またはワイド文字の数)。 dir が NULL の場合は、この値を 0 にする必要があります。
[出力] fname
基本ファイル名 (拡張子なし)。ファイル名が不要な場合は、このパラメーターに NULL を渡すことができます。
[入力] nameNumberOfElements
fname バッファーのサイズ (1 バイト文字またはワイド文字の数)。 fname が NULL の場合は、この値を 0 にする必要があります。
[出力] ext
ファイル名の拡張子。先頭にピリオド (.) が付きます。ファイル名の拡張子が不要な場合は、このパラメーターに NULL を渡すことができます。
[入力] extNumberOfElements
ext バッファーのサイズ (1 バイト文字またはワイド文字の数)。 ext が NULL の場合は、この値を 0 にする必要があります。

戻り値

正常終了した場合は 0 を返します。失敗した場合はエラーコードを返します。

エラー条件

状態	戻り値
path が NULL	EINVAL
drive が NULL、driveNumberOfElements がゼロ以外	EINVAL
drive が NULL 以外、driveNumberOfElements がゼロ	EINVAL
dir が NULL、dirNumberOfElements がゼロ以外	EINVAL
dir が NULL 以外、dirNumberOfElements がゼロ	EINVAL
fname が NULL、nameNumberOfElements がゼロ以外	EINVAL
fname が NULL 以外、nameNumberOfElements がゼロ	EINVAL
ext が NULL、extNumberOfElements がゼロ以外	EINVAL
ext が NULL 以外、extNumberOfElements がゼロ	EINVAL

上記のいずれかの条件が発生すると、「パラメーターの検証」に説明されているように、無効なパラメーターハンドラーが呼び出されます。実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、EINVAL を返します。

バッファーが短すぎて結果を保存できない場合、この関数はすべてのバッファーを消去して空の文字列にし、errno を ERANGE に設定し、ERANGE を返します。

解説

_splitpath_s 関数は、パスを 4 つの構成要素に分解します。 _splitpath_s は現在使用中のマルチバイトコードページに従ってマルチバイト文字列を認識し、必要に応じてマルチバイト文字列引数を自動的に処理します。 _wsplitpath_s は _splitpath_s のワイド文字バージョンであり、_wsplitpath_s の引数はワイド文字列です。それ以外では、これらの関数の動作は同じです。

汎用テキストルーチンのマップ

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tsplitpath_s	_splitpath_s	_splitpath_s	_wsplitpath_s

完全なパスの各構成要素は、別々のバッファーに格納されます。各ファイル構成要素に許容される最大サイズは、STDLIB.H に定義されているマニフェスト定数の _MAX_DRIVE、_MAX_DIR、_MAX_FNAME、および _MAX_EXT で指定されます。ファイル構成要素のサイズが対応するマニフェスト定数を超えると、ヒープの破損が発生します。

マニフェスト定数の値を次の表に示します。