_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.

语法Syntax

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

参数Parameters

pathpath
完整路径。Full path.

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

driveNumberOfElementsdriveNumberOfElements
大小驱动器以单字节或宽字符为单位的缓冲区。The size of the drive buffer in single-byte or wide characters. 如果驱动器NULL,此值必须为 0。If drive is NULL, this value must be 0.

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

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

fnamefname
基文件名(不带扩展名)。Base filename (without extension). 你可以将传递NULL为此参数,如果你不需要文件名。You can pass NULL for this parameter if you do not need the filename.

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

extext
文件扩展名,包括前导段 ()。你可以将传递NULL为此参数,如果你不需要文件扩展名。Filename extension, including leading period (.).You can pass NULL for this parameter if you do not need the filename extension.

extNumberOfElementsextNumberOfElements
大小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
路径NULLpath is NULL EINVALEINVAL
驱动器NULLdriveNumberOfElements为非零drive is NULL, driveNumberOfElements is non-zero EINVALEINVAL
驱动器为非NULLdriveNumberOfElements为零drive is non-NULL, driveNumberOfElements is zero EINVALEINVAL
dirNULLdirNumberOfElements为非零dir is NULL, dirNumberOfElements is non-zero EINVALEINVAL
dir为非NULLdirNumberOfElements为零dir is non-NULL, dirNumberOfElements is zero EINVALEINVAL
fnameNULLnameNumberOfElements为非零fname is NULL, nameNumberOfElements is non-zero EINVALEINVAL
fname为非NULLnameNumberOfElements为零fname is non-NULL, nameNumberOfElements is zero EINVALEINVAL
extNULLextNumberOfElements为非零ext is NULL, extNumberOfElements is non-zero EINVALEINVAL
ext为非NULLextNumberOfElements为零ext is non-NULL, extNumberOfElements is zero EINVALEINVAL

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

任何缓冲区是否太短,无法保存结果,这些函数将清除所有缓冲区,空字符串,将设置errnoERANGE,并返回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.

备注Remarks

_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_tsplitpath_s _splitpath_s_splitpath_s _splitpath_s_splitpath_s _wsplitpath_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
_MAX_DRIVE_MAX_DRIVE 33
_MAX_DIR_MAX_DIR 256256
_MAX_FNAME_MAX_FNAME 256256
_MAX_EXT_MAX_EXT 256256

如果完整路径不包含组件 (例如,文件名), _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.

要求Requirements

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

有关其他兼容性信息,请参阅 兼容性For additional compatibility information, see Compatibility.

示例Example

请参阅 _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
_setmbcp_setmbcp