PathCchCombineEx function (pathcch.h)

Article
03/11/2023

Combines two path fragments into a single path. This function also canonicalizes any relative path elements, removing "." and ".." elements to simplify the final path.

This function differs from PathCchCombine in that it allows for a longer final path to be constructed.

This function differs from PathAllocCombine in that the caller must declare the size of the returned string, which is stored on the stack.

This function differs from PathCombine in that it accepts paths with "\", "\?" and "\?\UNC" prefixes.

Note This function, PathCchCombine, or PathAllocCombine should be used in place of PathCombine to prevent the possibility of a buffer overrun.

Syntax

WINPATHCCHAPI HRESULT PathCchCombineEx(
  [out]          PWSTR  pszPathOut,
  [in]           size_t cchPathOut,
  [in, optional] PCWSTR pszPathIn,
  [in, optional] PCWSTR pszMore,
  [in]           ULONG  dwFlags
);

Parameters

[out] pszPathOut

A pointer to a buffer that, when this function returns successfully, receives the combined path string. This parameter can point to the same buffer as pszPathIn or pszMore.

[in] cchPathOut

The size of the buffer pointed to by pszPathOut, in characters.

[in, optional] pszPathIn

A pointer to the first path string. This value can be NULL.

[in, optional] pszMore

A pointer to the second path string. If this path begins with a single backslash, it is combined with only the root of the path pointed to by pszPathIn. If this path is fully qualified, it is copied directly to the output buffer without being combined with the other path. This value can be NULL.

[in] dwFlags

One or more of the following flags:

Value	Meaning
PATHCCH_NONE 0x0000000	Do not allow for the construction of \\?\ paths (ie, long paths) longer than MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Allow the construction of \\?\ paths longer than MAX_PATH. Note that cchPathOut must be greater than MAX_PATH. If it is not, this flag is ignored.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Forces the API to treat the caller as long path enabled, independent of the process's long name enabled state. This option can be used only when PATHCCH_ALLOW_LONG_PATHS is specified, and cannot be used with PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS. Note This value is available starting in Windows 10, version 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 0x00000004	Forces the API to treat the caller as long path disabled, independent of the process's long name enabled state. This option can be used only when PATHCCH_ALLOW_LONG_PATHS is specified, and cannot be used with PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS. Note This value is available starting in Windows 10, version 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 0x00000008	Disables the normalization of path segments that includes removing trailing dots and spaces. This enables access to paths that win32 path normalization will block. Note This value is available starting in Windows 10, version 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH 0x00000010	Converts the input path into the extended length DOS device path form (with the \\?\ prefix) if not already in that form. This enables access to paths that are otherwise not addressable due to Win32 normalization rules (that can strip trailing dots and spaces) and path length limitations. This option implies the same behavior of PATHCCH_DO_NOT_NORMALIZE_SEGMENTS. Note This value is available starting in Windows 10, version 1703.

Return value

This function returns an HRESULT code, including the following.

Return code	Description
S_OK	The function succeeded. Note that this also includes the case of an empty extension, such as a period with no characters following it. In that case, the original string is returned unaltered.
E_INVALIDARG	This value can be caused by several things, such as the pszPathOut param being set to NULL, or the cchPathOut value being set to 0 or a value greater than PATHCCH_MAX_CCH .
E_OUTOFMEMORY	The function could not allocate enough memory to perform the operation.
PATHCCH_E_FILENAME_TOO_LONG	The size of one or both of the original paths exceeded PATHCCH_MAX_CCH .

Remarks

If both pszPathIn and pszMore are NULL or point to empty strings, a single backslash is copied to the buffer pointed to by pszPathOut.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	pathcch.h
Library	Pathcch.lib