November 3rd, 2025
like1 reaction

Why does SHFormat­Date­Time take an unaligned FILETIME?

I noted some time ago Windows requires that pointers be aligned unless explicitly permitted to be unaligned. I gave as an example of a function that explicitly permits unaligned pointers the SHFormat­Date­Time function:

LWSTDAPI_(int)
    SHFormatDateTimeA(
        _In_ const FILETIME UNALIGNED * pft,
        _Inout_opt_ DWORD * pdwFlags,
        _Out_writes_(cchBuf) LPSTR pszBuf,
        UINT cchBuf); 

Why does this function go out of its way to allow an unaligned FILETIME?

The SHFormat­Date­Time was originally written for Explorer to use when formatting dates and times in details view and in property sheets. And a common source of these FILETIME structures are embedded inside Shell item ID lists, commonly known as “pidls” (rhymes with “riddles”) because the Hungarian notation for them is pidl, a “pointer to an ID list”.

Shell item ID lists require only byte alignment, so any structures you embed in them will be unaligned. The SHFormat­Date­Time bent over backward to accommodate its primary audience and allowed unaligned FILETIME structures to be passed in. (It presumably just copies it to an aligned local variable.)

I suspect that the SHFormat­Date­Time function was originally written for the Windows 95 series, which ran on x86-class processors, and x86-class processors are forgiving of misalignment. When the Windows NT team ported the code to alignment-sensitive RISC processors, they got tired of fixing all the individual call sites to copy the misaligned FILETIME to an aligned local, and they instead just taught the SHFormat­Date­Time function to be forgiving of misalignment and transfer the work of copying the misaligned FILETIME to a local into the SHFormat­Date­Time function.

So really, the fact that SHFormat­Date­Time accepts a misaligned pointer is just a historical expediency and not something that was part of its original design. Nowadays, we’d just tell everybody to align the FILETIME on the caller side instead of doing it on the receiving end.

Topics
History

Author

Raymond has been involved in the evolution of Windows for more than 30 years. In 2003, he began a Web site known as The Old New Thing which has grown in popularity far beyond his wildest imagination, a development which still gives him the heebie-jeebies. The Web site spawned a book, coincidentally also titled The Old New Thing (Addison Wesley 2007). He occasionally appears on the Windows Dev Docs Twitter account to tell stories which convey no useful information.

1 comment

Sort by :
  • skSdnW 5 hours ago · Edited

    The most common PIDL format (normal filesystem files and folders) stores the times in DOS format (2 WORDs), not as a FILETIME (in all Windows versions before 10 at least).

    SHFormat­Date­Time is exported by shlwapi which of course did not exist in 95 nor NT4, it shipped as part of IE3+ and this specific function was added for IE5. (The shell team may have had an internal version before this but the PIDL comment still applies)

    WIN32_FIND_DATA on the other hand does have FILETIME members that are not 64-bit aligned and it has been covered on this blog in the past (why...

    Read more