_splitpath_s、_wsplitpath_s_splitpath_s, _wsplitpath_s

将路径名称分解成组件。Breaks a path name into components. 这些版本的 _splitpath、_wsplitpath 具有安全增强功能,如 CRT 中的安全功能所述。These are versions of _splitpath, _wsplitpath with security enhancements as described in Security Features in the 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  


[in] path[in] path
完整路径。Full path.

[out] drive[out] drive
后跟一个冒号 (:) 的驱动器号。Drive letter, followed by a colon (:). 如果不需要驱动器号,则可为此参数传递 NULLYou can pass NULL for this parameter if you do not need the drive letter.

[in] driveNumberOfElements[in] driveNumberOfElements
drive 缓冲区大小(以单字节字符或宽字符为单位)。The size of the drive buffer in single-byte or wide characters. 如果 driveNULL,则该值必须为 0。If drive is NULL, this value must be 0.

[out] dir[out] dir
目录路径,包括尾部反斜杠。Directory path, including trailing slash. 正斜杠 ( / )、反斜杠 ( \ ),或两者均使用。Forward slashes ( / ), backslashes ( \ ), or both may be used. 如果不需要目录路径,则可为此参数传递 NULLYou can pass NULL for this parameter if you do not need the directory path.

[in] dirNumberOfElements[in] dirNumberOfElements
dir 缓冲区大小(以单字节字符或宽字符为单位)。The size of the dir buffer in single-byte or wide characters. 如果 dirNULL,则该值必须为 0。If dir is NULL, this value must be 0.

[out] fname[out] fname
基文件名(不带扩展名)。Base filename (without extension). 如果不需要文件名,则可为此参数传递 NULLYou can pass NULL for this parameter if you do not need the filename.

[in] nameNumberOfElements[in] nameNumberOfElements
fname 缓冲区大小(以单字节字符或宽字符为单位)。The size of the fname buffer in single-byte or wide characters. 如果 fnameNULL,则该值必须为 0。If fname is NULL, this value must be 0.

[out] ext[out] ext
文件扩展名,包括前导句点 (.)。如果不需要文件扩展名,则可为此参数传递 NULLFilename extension, including leading period (.).You can pass NULL for this parameter if you do not need the filename extension.

[in] extNumberOfElements[in] extNumberOfElements
ext 缓冲区大小(以单字节字符或宽字符为单位)。The size of ext buffer in single-byte or wide characters. 如果 extNULL,则该值必须为 0。If ext is NULL, this value must be 0.

返回值Return Value

如果成功,则为零;如果失败,则为错误代码。Zero if successful; an error code on failure.

错误条件Error Conditions

条件Condition 返回值Return Value
driveNULL,则 driveNumberOfElements 为非零drive is NULL, driveNumberOfElements is non-zero EINVAL
drive 是非 NULL,则 driveNumberOfElements 为零drive is non-NULL, driveNumberOfElements is zero EINVAL
dirNULL,则 dirNumberOfElements 为非零dir is NULL, dirNumberOfElements is non-zero EINVAL
dir 是非 NULL,则 dirNumberOfElements 为零dir is non-NULL, dirNumberOfElements is zero EINVAL
fnameNULL,则 nameNumberOfElements 为非零fname is NULL, nameNumberOfElements is non-zero EINVAL
fname 是非 NULL,则 nameNumberOfElements 为零fname is non-NULL, nameNumberOfElements is zero EINVAL
extNULL,则 extNumberOfElements 为非零ext is NULL, extNumberOfElements is non-zero EINVAL
ext 是非 NULL,则 extNumberOfElements 为零ext is non-NULL, extNumberOfElements is zero EINVAL

如果发生上述情况之一,都会调用无效参数处理程序,如参数验证中所述。If any of the above conditions occurs, the invalid parameter handler is invoked, as described in Parameter Validation . 如果允许执行继续,则这些功能将 errno 设置为 EINVAL 并返回 EINVALIf execution is allowed to continue, these functions set errno to EINVAL and return EINVAL.

如果所有缓冲区均过短而无法保存结果,这些函数会将所有缓冲区清除为空字符串,并将 errno 设置为 ERANGE,返回 ERANGEIf any of the buffers is too short to hold the result, these functions clear all the buffers to empty strings, set errno to ERANGE, and return ERANGE.


_splitpath_s 函数将路径分解成其的四个组件。The _splitpath_s function breaks a path into its four components. _splitpath_s 将根据情况自动处理多字节字符串参数,根据当前正在使用的多字节代码页识别多字节字符序列。_splitpath_s automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. _wsplitpath_s_splitpath_s 的宽字符版本;_wsplitpath_s 的参数是宽字符串。_wsplitpath_s is a wide-character version of _splitpath_s; the arguments to _wsplitpath_s are wide-character strings. 否则这些函数具有相同行为These functions behave identically otherwise

一般文本例程映射Generic-Text Routine Mappings

TCHAR.H 例程TCHAR.H routine 未定义 _UNICODE 和 _MBCS_UNICODE & _MBCS not defined 已定义 _MBCS_MBCS defined 已定义 _UNICODE_UNICODE defined
_tsplitpath_s _splitpath_s _splitpath_s _wsplitpath_s

完整路径的每个组件均存储在单独的缓冲区中;清单常量 _MAX_DRIVE_MAX_DIR_MAX_FNAME_MAX_EXT(在 STDLIB.H 中定义)指定每个文件组件的最大可允许大小。Each component of the full path is stored in a separate buffer; the manifest constants _MAX_DRIVE, _MAX_DIR, _MAX_FNAME, and _MAX_EXT (defined in STDLIB.H) specify the maximum allowable size for each file component. 文件组件大于相应清单常量会导致堆损坏。File components larger than the corresponding manifest constants cause heap corruption.

下表列出了清单常量的值。The following table lists the values of the manifest constants.

名称Name Value

如果完整路径不包含组件(例如,文件名),则 _splitpath_s 会将空字符串分配给相应的缓冲区。If the full path does not contain a component (for example, a filename), _splitpath_s assigns an empty string to the corresponding buffer.

在 C++ 中,通过模板重载简化这些函数的使用;重载可以自动推导出缓冲区长度,不再需要指定大小参数。In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. 有关详细信息,请参阅 Secure Template OverloadsFor more information, see Secure Template Overloads.

这些函数的调试版本首先用 0xFD 填充缓冲区。The debug versions of these functions first fill the buffer with 0xFD. 若要禁用此行为,请使用 _CrtSetDebugFillThresholdTo disable this behavior, use _CrtSetDebugFillThreshold.


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

有关其他兼容性信息,请参见“简介”中的 兼容性For additional compatibility information, see Compatibility in the Introduction.


请参阅 _makepath_s、_wmakepath_s 的示例。See the example for _makepath_s, _wmakepath_s.

请参阅See Also

文件处理 File Handling
_splitpath、_wsplitpath _splitpath, _wsplitpath
_fullpath、_wfullpath _fullpath, _wfullpath
_getmbcp _getmbcp
_makepath、_wmakepath _makepath, _wmakepath