PathCleanupSpec function (shlobj_core.h)

[PathCleanupSpec is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions.]

Removes illegal characters from a file or directory name. Enforces the 8.3 filename format on drives that do not support long file names.

Syntax

int PathCleanupSpec(
  [in, optional] PCWSTR pszDir,
  [in, out]      PWSTR  pszSpec
);

Parameters

[in, optional] pszDir

Type: PCWSTR

A pointer to a null-terminated buffer that contains the fully qualified path of the directory that will contain the file or directory named at pszSpec. The path must not exceed MAX_PATH characters in length, including the terminating null character. This path is not altered.

This value can be NULL.

[in, out] pszSpec

Type: PWSTR

A pointer to a null-terminated buffer that contains the file or directory name to be cleaned. In the case of a file, include the file's extension. Note that because '' is considered an invalid character and will be removed, this buffer cannot contain a path more than one directory deep.

On exit, the buffer contains a null-terminated string that includes the cleaned name.

This buffer should be at least MAX_PATH characters in length to avoid the possibility of a buffer overrun.

Return value

Type: int

Returns one or more of the following values.

Remarks

The following are considered invalid characters in all names.

\ / : * ? " < > |

Control characters are also considered invalid. If long file names are not supported, the semi-colon (;) and comma (,) characters are also invalid.

The drive named in pszDir is checked to determine whether its file system supports long file names. If it does not, the name at pszSpec is truncated to the 8.3 format and the PCS_TRUNCATED value returned. If pszDir is NULL, the drive on which Windows is installed is used to determine long file name support.

If the full path—the number of characters in the path at pszDir plus the number of characters in the cleaned name at pszSpec—exceeds MAX_PATH – 1 (to account for the terminating null character), the function returns PCS_PATHTOOLONG.

Requirements