SetFileShortNameW function (winbase.h)

Sets the short name for the specified file. The file must be on an NTFS file system volume.

Syntax

BOOL SetFileShortNameW(
  [in] HANDLE  hFile,
  [in] LPCWSTR lpShortName
);

Parameters

[in] hFile

A handle to the file. The file must be opened with either the GENERIC_ALL access right or GENERIC_WRITE|DELETE, and with the FILE_FLAG_BACKUP_SEMANTICS file attribute.

[in] lpShortName

A pointer to a string that specifies the short name for the file.

Specifying an empty (zero-length) string will remove the short file name, if it exists for the file specified by the hFile parameter. If a short file name does not exist, the function will do nothing and return success.

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:  This behavior is not supported. The parameter must contain a valid string of one or more characters.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. GetLastError may return one of the following error codes that are specific to this function.

Return code Description
ERROR_ALREADY_EXISTS
The specified short name is not unique.
ERROR_INVALID_PARAMETER
Either the specified file has been opened in case-sensitive mode or the specified short name is invalid.

Remarks

The caller of this function must have the SE_RESTORE_NAME privilege. For more information, see Running with Special Privileges.

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) Yes
Resilient File System (ReFS) No
 

SMB 3.0 does not support short names on shares with continuous availability capability . Short names are not recommended on CsvFs.

Note

The winbase.h header defines SetFileShortName as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

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

See also

File Management Functions

GetShortPathName