Expand Minimize

RtlGenerate8dot3Name routine

The RtlGenerate8dot3Name routine generates a short (8.3) name for the specified long file name.

Syntax


NTSTATUS RtlGenerate8dot3Name(
  _In_     PCUNICODE_STRING Name,
  _In_     BOOLEAN AllowExtendedCharacters,
  _Inout_  PGENERATE_NAME_CONTEXT Context,
  _Inout_  PUNICODE_STRING Name8dot3
);

Parameters

Name [in]

Pointer to a Unicode string containing the long name for the file. Any leading periods in this file name are skipped during generation of a corresponding short name.

AllowExtendedCharacters [in]

Set to TRUE if the generated short file name can contain extended characters. Set to FALSE if the generated short file name must contain only characters within the current code page's ANSI or OEM range from 0x20 (space) through 0x7f (DEL).

Context [in, out]

Pointer to a caller-allocated buffer for use by RtlGenerate8dot3Name. Before calling RtlGenerate8dot3Name for the first time to translate the given long file name, the caller is responsible for filling the buffer with zeros.

Name8dot3 [in, out]

Pointer to a caller-allocated buffer to receive the generated short file name. The size of this buffer must be at least 24 bytes (12 Unicode characters).

Return value

None

Remarks

RtlGenerate8dot3Name returns a generated short name with at most eight characters, followed immediately by a period and up to three more characters.

RtlGenerate8dot3Name can be called repeatedly. For example, if the initially generated short name is a duplicate of an existing file name, the caller can pass the same parameters to RtlGenerate8dot3Name again. In this case, the buffer at Context should not be reinitialized with zeros. This buffer should be zeroed only for the initial call to translate a given long name. On repeated calls for the same long name, RtlGenerate8dot3Name stores private context information in this buffer to prevent name collisions.

Two calls to RtlGenerate8dot3Name with the same Name and Context are not guaranteed to return the same result. Callers should assume that the mapping of long name to short name is nondeterministic.

RtlGenerate8dot3Name translates the given long name using the current system code page, discarding any invalid or superfluous characters in the input long name. When AllowExtendedCharacters is set to TRUE, ANSI or double-byte character set (DBCS) characters that map to uppercase OEM characters can become part of a returned short name.

RtlGenerate8dot3Name returns a short file name with uppercase alphabetic characters. It returns underscores in the generated short name for any of the following characters that it encounters in the given long name:

  • Colons and semicolons

  • Commas

  • Plus and equal signs

  • Square brackets

For information about other string-handling routines, see Strings.

Requirements

Header

Ntifs.h (include Ntifs.h)

Library

Ntoskrnl.lib

IRQL

< DISPATCH_LEVEL

See also

RtlIsNameLegalDOS8Dot3
RtlIsValidOemCharacter
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft