%>

将路径名称分解成组件。 这些函数的版本是 _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 的示例。

另请参阅

文件处理
%>
%>
_getmbcp
%>
_setmbcp