_splitpath_s, _wsplitpath_s
Break a path name into components. These are versions of _splitpath, _wsplitpath with security enhancements as described in Security Enhancements 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
Parameters
[in] path
Full path.[out] drive
Optional drive letter, followed by a colon (:).[in] driveNumberOfElements
The size of the drive buffer in single-byte or wide characters. If drive is NULL, this value must be set to zero.[out] dir
Optional directory path, including trailing slash. Forward slashes ( / ), backslashes ( \ ), or both may be used.[in] dirNumberOfElements
The size of the dir buffer in single-byte or wide characters. If dir is NULL, this value must be set to zero.[out] fname
Optional base filename (no extension).[in] nameNumberOfElements
The size of the fname buffer in single-byte or wide characters. If fname is NULL, this value must be zero.[out] ext
Optional filename extension, including leading period (.).[in] extNumberOfElements
The size of ext buffer in single-byte or wide characters. If ext is NULL, this value must be set to zero.
Return Value
Zero if successful; an error code on failure.
Error Conditions
Condition |
Return Value |
|---|---|
path is NULL |
EINVAL |
drive is NULL, driveNumberOfElements is non-zero |
EINVAL |
drive is non-NULL, driveNumberOfElements is zero |
EINVAL |
dir is NULL, dirNumberOfElements is non-zero |
EINVAL |
dir is non-NULL, dirNumberOfElements is zero |
EINVAL |
fname is NULL, nameNumberOfElements is non-zero |
EINVAL |
fname is non-NULL, nameNumberOfElements is zero |
EINVAL |
ext is NULL, extNumberOfElements is non-zero |
EINVAL |
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 . If execution is allowed to continue, these functions set errno to EINVAL and return EINVAL.
If 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
The _splitpath_s function breaks a path into its four components. _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 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 routine |
_UNICODE & _MBCS not defined |
_MBCS defined |
_UNICODE defined |
|---|---|---|---|
_tsplitpath |
_splitpath |
_splitpath |
_wsplitpath |
Each argument is stored in a buffer; the manifest constants _MAX_DRIVE, _MAX_DIR, _MAX_FNAME, and _MAX_EXT (defined in STDLIB.H) specify the maximum size necessary for each buffer. The other arguments point to buffers used to store the path elements. After a call to _splitpath_s is executed, these arguments contain empty strings for components not found in path. You can pass a NULL pointer to _splitpath_s for any component you don't need.
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. For more information, see Secure Template Overloads.
The debug versions of these functions first fill the buffer with 0xFD. To disable this behavior, use _CrtSetDebugFillThreshold.
Requirements
Routine |
Required header |
|---|---|
_splitpath_s |
<stdlib.h> |
_wsplitpath_s |
<stdlib.h> or <wchar.h> |
For additional compatibility information, see Compatibility in the Introduction.
Example
See the example for _makepath_s, _wmakepath_s.
.NET Framework Equivalent
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.