_splitpath_s，_wsplitpath_s

将路径名称分解成组件。 这些函数的版本是 _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 缓冲区大小（以单字节字符或宽字符为单位）。 如果 drive 是 NULL，则该值必须为 0。

dir
目录路径，包括尾部反斜杠。 正斜杠 ( / )、反斜杠 ( \\ )，或两者均使用。 如果不需要目录路径，则可为此参数传递 NULL。

dirNumberOfElements
dir 缓冲区大小（以单字节字符或宽字符为单位）。 如果 dir 是 NULL，则该值必须为 0。

fname
基文件名（不带扩展名）。 如果不需要文件名，则可为此参数传递 NULL。

nameNumberOfElements
fname 缓冲区大小（以单字节字符或宽字符为单位）。 如果 fname 是 NULL，则该值必须为 0。

ext
文件扩展名，包括前导句点 (.)。 如果不需要文件扩展名，则可为此参数传递 NULL。

extNumberOfElements
ext 缓冲区大小（以单字节字符或宽字符为单位）。 如果 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 函数将路径分解成其的四个组件。 _splitpath_s 将根据情况自动处理多字节字符串参数，根据当前正在使用的多字节代码页识别多字节字符序列。 _wsplitpath_s 是 _splitpath_s的宽字符版本； _wsplitpath_s 的参数是宽字符串。 否则这些函数具有相同行为

默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。

一般文本例程映射

TCHAR.H 例程	_UNICODE 和 _MBCS 未定义	_MBCS 已定义	_UNICODE 已定义
_tsplitpath_s	_splitpath_s	_splitpath_s	_wsplitpath_s

完整路径的每个组件均存储在单独的缓冲区中；清单常量 _MAX_DRIVE、_MAX_DIR、_MAX_FNAME 和 _MAX_EXT（在 STDLIB.H 中定义）指定每个文件组件的最大可允许大小。 文件组件大于相应清单常量会导致堆损坏。

下表列出了清单常量的值。

名称	值
_MAX_DRIVE	3
_MAX_DIR	256
_MAX_FNAME	256
_MAX_EXT	256

如果完整路径不包含组件（例如，文件名），则 _splitpath_s 会将空字符串分配给相应的缓冲区。

在 C++ 中，通过模板重载简化这些函数的使用；重载可以自动推导出缓冲区长度，不再需要指定大小参数。 有关详细信息，请参阅安全模板重载。

这些函数的调试库版本首先用 0xFE 填充缓冲区。 若要禁用此行为，请使用 _CrtSetDebugFillThreshold。

要求

例程	必需的标头
_splitpath_s	<stdlib.h>
_wsplitpath_s	<stdlib.h> 或 <wchar.h>

有关兼容性的详细信息，请参阅 兼容性。

示例

请参阅 _makepath_s、_wmakepath_s 的示例。

另请参阅

文件处理
_splitpath、_wsplitpath
_fullpath、_wfullpath
_getmbcp
_makepath、_wmakepath
_setmbcp