_splitpath_s, _wsplitpath_s

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _splitpath_s, _wsplitpath_s.

Breaks a path name into components. 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  

Parameters

[in] path
Full path.

[out] drive
Drive letter, followed by a colon (:). You can pass NULL for this parameter if you do not need the drive letter.

[in] driveNumberOfElements
The size of the drive buffer in single-byte or wide characters. If drive is NULL, this value must be 0.

[out] dir
Directory path, including trailing slash. Forward slashes ( / ), backslashes ( \ ), or both may be used. You can pass NULL for this parameter if you do not need the directory path.

[in] dirNumberOfElements
The size of the dir buffer in single-byte or wide characters. If dir is NULL, this value must be 0.

[out] fname
Base filename (without extension). You can pass NULL for this parameter if you do not need the filename.

[in] nameNumberOfElements
The size of the fname buffer in single-byte or wide characters. If fname is NULL, this value must be 0.

[out] ext
Filename extension, including leading period (.).You can pass NULL for this parameter if you do not need the filename extension.

[in] extNumberOfElements
The size of ext buffer in single-byte or wide characters. If ext is NULL, this value must be 0.

Zero if successful; an error code on failure.

Error Conditions

ConditionReturn Value
path is NULLEINVAL
drive is NULL, driveNumberOfElements is non-zeroEINVAL
drive is non-NULL, driveNumberOfElements is zeroEINVAL
dir is NULL, dirNumberOfElements is non-zeroEINVAL
dir is non-NULL, dirNumberOfElements is zeroEINVAL
fname is NULL, nameNumberOfElements is non-zeroEINVAL
fname is non-NULL, nameNumberOfElements is zeroEINVAL
ext is NULL, extNumberOfElements is non-zeroEINVAL
ext is non-NULL, extNumberOfElements is zeroEINVAL

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.

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_sare wide-character strings. These functions behave identically otherwise

Generic-Text Routine Mappings

TCHAR.H routine_UNICODE & _MBCS not defined_MBCS defined_UNICODE defined
_tsplitpath_s_splitpath_s_splitpath_s_wsplitpath_s

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.

NameValue
_MAX_DRIVE3
_MAX_DIR256
_MAX_FNAME256
_MAX_EXT256

If the full path does not contain a component (for example, a filename), _splitpath_s assigns an empty string to the corresponding buffer.

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.

RoutineRequired header
_splitpath_s<stdlib.h>
_wsplitpath_s<stdlib.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

See the example for _makepath_s, _wmakepath_s.

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

File Handling
_splitpath, _wsplitpath
_fullpath, _wfullpath
_getmbcp
_makepath, _wmakepath
_setmbcp

Show: