Home Library Learn Downloads Support Community
Sign in | United States - English | |
3 out of 14 rated this helpful - Rate this topic

GetShortPathName function

Applies to: desktop apps only

Retrieves the short path form of the specified path.

For more information about file and path names, see Naming Files, Paths, and Namespaces.

Syntax

Copy 
DWORD WINAPI GetShortPathName(
  __in   LPCTSTR lpszLongPath,
  __out  LPTSTR lpszShortPath,
  __in   DWORD cchBuffer
);

Parameters

lpszLongPath [in]

The path string.

In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming Files, Paths, and Namespaces.

lpszShortPath [out]

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.

cchBuffer [in]

The size of the buffer that lpszShortPath points to, in TCHARs.

Set this parameter to zero if lpszShortPath is set to NULL.

Return value

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.

Remarks

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.

Note  Although the return value in this case is a length that includes the terminating null character, the return value on success does not include the terminating null character in the count.

If the specified path is already in its short form and conversion is not needed, the function simply copies the specified path to the buffer specified by the lpszShortPath parameter.

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.

Examples

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.

C++
Copy 

//...
    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;
///...

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header
WinBase.h (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

Unicode and ANSI names

GetShortPathNameW (Unicode) and GetShortPathNameA (ANSI)

See also

File Management Functions
Naming Files, Paths, and Namespaces
FindFirstFile
GetFullPathName
GetLongPathName
SetFileShortName

 

 

Send comments about this topic to Microsoft

Build date: 4/17/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Try not to use this function
Short paths need a lot of assumptions, such as that the code page of your disk is the same as your current windows code page. If you really need to use 8.3 names, try to restrict them entirely to ASCII (characters < U+007F) for the greatest interoperability and least problems. Much better is to use decent long paths and Unicode path strings.
History
GetShortPathName fails if path doesn't exist!
This may seem obvious to some, but the path must actually exist to be able to get the short path name. I thought this function was more of a utility function, but remembering back to DOS days, the files present result in different file names being generated. Quite a gotcha if you are not paying attention ;)  Even if the parent directory exists but the filename within it does not and is less than 8.3, this method will fail.
History
C# syntax 
[DllImport("kernel32.dll", CharSet=CharSet.Auto)]
public static extern uint GetShortPathName(string lpszLongPath, StringBuilder lpszShortPath, uint cchBuffer);
History
vb.net syntax 
<DllImport("kernel32.dll", CharSet:=CharSet.Auto)> Public Shared Function GetShortPathName(ByVal lpszLongPath As String, ByVal lpszShortPath As StringBuilder, ByVal cchBuffer As UInt32) As UInt32
End Function
History
Short filename not always available

GetShortPathName fails to create a short filename if the file doesn't have a short file name. The default behavior in Windows NT, Windows 95, and Windows 98 is to automatically create short file names (8.3 format) for files with long names. You can turn this option off by using the "System Policy Editor" (Poledit.exe). Certain file systems also don't support creation of short names by default.

Is there a way to force the OS to create a short filename alias for a file of interest without having to change system policy?

History