GetShortPathNameA function (winbase.h)
Retrieves the short path form of the specified path.
For more information about file and path names, see Naming Files, Paths, and Namespaces.
DWORD GetShortPathNameA(
[in] LPCSTR lpszLongPath,
[out] LPSTR lpszShortPath,
[in] DWORD cchBuffer
);
[in] lpszLongPath
The path string.
By default, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.
Tip
Starting with Windows 10, Version 1607, you can opt-in to remove the MAX_PATH limitation without prepending "\\?\". See the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.
[out] lpszShortPath
A pointer to a buffer to receive the null-terminated short form of the path that lpszLongPath specifies.
Passing NULL for this parameter and zero for cchBuffer will always return the required buffer size for a specified lpszLongPath.
[in] cchBuffer
The size of the buffer that lpszShortPath points to, in TCHARs.
Set this parameter to zero if lpszShortPath is set to NULL.
If the function succeeds, the return value is the length, in TCHARs, of the string that is copied to lpszShortPath, not including the terminating null character.
If the lpszShortPath buffer is too small to contain the path, the return value is the size of the buffer, in TCHARs, that is required to hold the path and the terminating null character.
If the function fails for any other reason, the return value is zero. To get extended error information, call GetLastError.
The path that the lpszLongPath parameter specifies does not have to be a full or long path. The short form can be longer than the specified path.
If the return value is greater than the value specified in the cchBuffer parameter, you can call the function again with a buffer that is large enough to hold the path. For an example of this case in addition to using zero-length buffer for dynamic allocation, see the Example Code section.
You can set the lpszShortPath parameter to the same value as the lpszLongPath parameter; in other words, you can set the output buffer for the short path to the address of the input path string. Always ensure that the cchBuffer parameter accurately represents the total size, in TCHARs, of this buffer.
You can obtain the long name of a file from the short name by calling the GetLongPathName function. Alternatively, where GetLongPathName is not available, you can call FindFirstFile on each component of the path to get the corresponding long name.
It is possible to have access to a file or directory but not have access to some of the parent directories of that file or directory. As a result, GetShortPathName may fail when it is unable to query the parent directory of a path component to determine the short name for that component. This check can be skipped for directory components that already meet the requirements of a short name. For more information, see the Short vs. Long Names section of Naming Files, Paths, and Namespaces.
In Windows 8 and Windows Server 2012, this function is supported by the following technologies.
Technology | Supported |
---|---|
Server Message Block (SMB) 3.0 protocol | Yes |
SMB 3.0 Transparent Failover (TFO) | No |
SMB 3.0 with Scale-out File Shares (SO) | No |
Cluster Shared Volume File System (CsvFS) | No |
Resilient File System (ReFS) | Yes |
SMB 3.0 does not support short names on shares with continuous availability capability.
Resilient File System (ReFS) doesn't support short names. If you call GetShortPathName on a path that doesn't have any short names on-disk, the call will succeed, but will return the long-name path instead. This outcome is also possible with NTFS volumes because there's no guarantee that a short name will exist for a given long name.
For an example that uses GetShortPathName, see the Example Code section for GetFullPathName.
The following C++ example shows how to use a dynamically allocated output buffer.//...
long length = 0;
TCHAR* buffer = NULL;
// First obtain the size needed by passing NULL and 0.
length = GetShortPathName(lpszPath, NULL, 0);
if (length == 0) ErrorExit(TEXT("GetShortPathName"));
// Dynamically allocate the correct size
// (terminating null char was included in length)
buffer = new TCHAR[length];
// Now simply call again using same long path.
length = GetShortPathName(lpszPath, buffer, length);
if (length == 0) ErrorExit(TEXT("GetShortPathName"));
_tprintf(TEXT("long name = %s shortname = %s"), lpszPath, buffer);
delete [] buffer;
///...
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | winbase.h (include Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |