Retrieves the short path form of the specified path.

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

Syntax

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 lpszLongPath 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 cchBuffer, 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 lpszShortPath.

You can set lpszShortPath to the same value as lpszLongPath; in other words, you can set the output buffer for the short path to the address of the input path string. Always ensure cchBuffer 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.

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.

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

See Also

File Management Functions

Naming Files, Paths, and Namespaces

FindFirstFile

GetFullPathName

GetLongPathName

SetFileShortName

Send comments about this topic to Microsoft

Build date: 11/12/2009