_splitpath_s、_wsplitpath_s

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

パス名を構成要素に分解します。_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
ドライブを表す文字 (省略可能)。後ろにコロン (:) を付けます。
[入力] driveNumberOfElements
drive バッファのサイズ (1 バイト文字またはワイド文字の数)。drive が NULL の場合、この値はゼロに設定する必要があります。
[出力] dir
ディレクトリパスと末尾のスラッシュ (省略可能)。区切り記号にはスラッシュ (/ ) および円記号 (\) を使用でき、両方を混在させることもできます。
[入力] dirNumberOfElements
dir バッファのサイズ (1 バイト文字またはワイド文字の数)。dir が NULL の場合、この値はゼロに設定する必要があります。
[出力] fname
拡張子なしのベースファイル名 (省略可能)。
[入力] nameNumberOfElements
fname バッファのサイズ (1 バイト文字またはワイド文字の数)。fname が NULL の場合、この値はゼロにする必要があります。
[出力] ext
ファイル名の拡張子 (省略可能)。先頭にピリオド (.) が付きます。
[入力] extNumberOfElements
ext バッファのサイズ (1 バイト文字またはワイド文字の数)。ext が NULL の場合、この値はゼロに設定する必要があります。

戻り値

正常終了した場合は 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	_splitpath	_splitpath	_wsplitpath

各引数はバッファに格納されます。各バッファに必要な最大長は、STDLIB.H で定義されている記号定数 (manifest 定数) の _MAX_DRIVE、_MAX_DIR、_MAX_FNAME、および _MAX_EXT で指定します。その他の引数は、パスの要素を格納するバッファを指します。_splitpath_s の実行が完了すると、path に存在しない構成要素については、これらの引数に空の文字列が入ります。不要な構成要素については、_splitpath_s に NULL ポインタを渡すことができます。

C++ では、テンプレートのオーバーロードによってこれらの関数を簡単に使用できます。オーバーロードでは、バッファ長を自動的に推論できるため、サイズ引数を指定する必要がなくなります。詳細については、「セキュリティ保護されたテンプレートオーバーロード」を参照してください。

これらの関数のデバッグバージョンは、最初にバッファを 0xFD で埋めます。この動作を無効にするには、_CrtSetDebugFillThreshold を使用します。