SetFileShortNameA function (winbase.h)
Sets the short name for the specified file. The file must be on an NTFS file system volume.
Syntax
BOOL SetFileShortNameA(
[in] HANDLE hFile,
[in] LPCSTR 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 |
|---|---|
|
The specified short name is not unique. |
|
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 that 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 is 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 |