{"id":111185,"date":"2025-05-16T07:00:00","date_gmt":"2025-05-16T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=111185"},"modified":"2025-05-21T15:24:12","modified_gmt":"2025-05-21T22:24:12","slug":"20250516-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20250516-00\/?p=111185","title":{"rendered":"What’s with the weird wReserved<\/CODE> value at the start of the DECIMAL<\/CODE> structure?"},"content":{"rendered":"

The DECIMAL<\/code> structure looks like this:<\/p>\n

typedef struct tagDEC {\r\n  USHORT wReserved;\r\n  union {\r\n    struct {\r\n      BYTE scale;\r\n      BYTE sign;\r\n    };\r\n    USHORT signscale;\r\n  };\r\n  ULONG  Hi32;\r\n  union {\r\n    struct {\r\n      ULONG Lo32;\r\n      ULONG Mid32;\r\n    };\r\n    ULONGLONG Lo64;\r\n  };\r\n} DECIMAL;\r\n<\/pre>\n
What is the deal with that wReserved<\/code> at the front?<\/p>\n
That reserved field comes into play when the DECIMAL<\/code> is placed inside a VARIANT<\/code>.<\/p>\n
Let’s start with this simple version of VARIANT<\/code>:<\/p>\n
typedef struct tagVARIANT {\r\n  uint16_t vt;\r\n  union {\r\n    uint64_t    llVal;\r\n    uint32_t    lVal;\r\n    uint8_t     bVal;\r\n    int16_t     iVal;\r\n    \u27e6 a whole bunch of other things \u27e7\r\n    \u27e6 the largest is 8 bytes        \u27e7\r\n    \u27e6 and requires 8-byte alignment \u27e7\r\n  };\r\n} VARIANT;\r\n<\/pre>\n
This simple version is a discriminated union with a large number of possible types. The largest such type is 8 bytes in size and has an alignment of 8 bytes. This means that there are 6 bytes of padding between the discriminant vt<\/code> and the union.<\/p>\n\n\n\n\n
0<\/td>\n1<\/td>\n2<\/td>\n3<\/td>\n4<\/td>\n5<\/td>\n6<\/td>\n7<\/td>\n8<\/td>\n9<\/td>\nA<\/td>\nB<\/td>\nC<\/td>\nD<\/td>\nE<\/td>\nF<\/td>\n<\/tr>\n
vt<\/td>\n(padding)<\/td>\npayload<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Let’s add the padding explicitly.<\/p>\n
typedef struct tagVARIANT {\r\n  uint16_t vt;\r\n  uint16_t pad1;<\/span>\r\n  uint16_t pad2;<\/span>\r\n  uint16_t pad3;<\/span>\r\n  union {\r\n    uint64_t    llVal;\r\n    uint32_t    lVal;\r\n    uint8_t     bVal;\r\n    int16_t     iVal;\r\n    \u27e6 a whole bunch of other things \u27e7\r\n    \u27e6 the largest is 8 bytes        \u27e7\r\n    \u27e6 and requires 8-byte alignment \u27e7\r\n  };\r\n} VARIANT;\r\n<\/pre>\n\n\n\n\n
0<\/td>\n1<\/td>\n2<\/td>\n3<\/td>\n4<\/td>\n5<\/td>\n6<\/td>\n7<\/td>\n8<\/td>\n9<\/td>\nA<\/td>\nB<\/td>\nC<\/td>\nD<\/td>\nE<\/td>\nF<\/td>\n<\/tr>\n
vt<\/td>\npad1<\/td>\npad2<\/td>\npad3<\/td>\npayload<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Now, the DECIMAL<\/code> type wants to hold a scaled decimal value, so we’ll need at least a byte for the scale, a bit for the sign, and a lot of bits for the mantissa. If we had to squeeze the DECIMAL<\/code> inside the payload field, there would be only 64 bits available. But wait, there are these extra 48 bits of padding. Maybe we can steal them to hold the scale, sign, and more mantissa bits.<\/p>\n\n\n\n\n
0<\/td>\n1<\/td>\n2<\/td>\n3<\/td>\n4<\/td>\n5<\/td>\n6<\/td>\n7<\/td>\n8<\/td>\n9<\/td>\nA<\/td>\nB<\/td>\nC<\/td>\nD<\/td>\nE<\/td>\nF<\/td>\n<\/tr>\n
vt<\/td>\n(I CAN HAZ<\/a> MOAR PAYLOAD?)<\/td>\npayload<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Great, we found an additional place to stash 48 bits of information.<\/p>\n
Our goal is to have the VARIANT<\/code> laid out like this:<\/p>\n\n\n\n\n\n
0<\/td>\n1<\/td>\n2<\/td>\n3<\/td>\n4<\/td>\n5<\/td>\n6<\/td>\n7<\/td>\n8<\/td>\n9<\/td>\nA<\/td>\nB<\/td>\nC<\/td>\nD<\/td>\nE<\/td>\nF<\/td>\n<\/tr>\n
vt<\/td>\npad1<\/td>\npad2<\/td>\npad3<\/td>\npayload<\/td>\nfor non-DECIMAL<\/code><\/td>\n<\/tr>\n
scale<\/span><\/td>\nsign<\/td>\nmantissa_high<\/td>\nmantissa_low<\/td>\nfor DECIMAL<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
So let’s declare our DECIMAL<\/code> structure so that it can nestle right in after the vt<\/code>:<\/p>\n
typedef struct tagDECIMAL\r\n{\r\n  uint8_t scale;\r\n  uint8_t sign;\r\n  uint32_t mantissa_high;\r\n  uint64_t mantissa_low;\r\n} DECIMAL;\r\n\r\ntypedef struct tagVARIANT\r\n{\r\n  uint16_t vt;\r\n  union {\r\n    DECIMAL decVal;\r\n    struct {\r\n      uint16_t pad1;\r\n      uint16_t pad2;\r\n      uint16_t pad3;\r\n      union {\r\n        uint64_t    llVal;\r\n        uint32_t    lVal;\r\n        uint8_t     bVal;\r\n        int16_t     iVal;\r\n        \u27e6 a whole bunch of other things \u27e7\r\n        \u27e6 the largest is 8 bytes        \u27e7\r\n        \u27e6 and requires 8-byte alignment \u27e7\r\n      };\r\n    };\r\n  };\r\n};\r\n<\/pre>\n
Oh noes! The result is<\/p>\n\n\n\n\n\n
0<\/td>\n1<\/td>\n2<\/td>\n3<\/td>\n4<\/td>\n5<\/td>\n6<\/td>\n7<\/td>\n8<\/td>\n9<\/td>\nA<\/td>\nB<\/td>\nC<\/td>\nD<\/td>\nE<\/td>\nF<\/td>\n10<\/td>\n11<\/td>\n12<\/td>\n13<\/td>\n14<\/td>\n15<\/td>\n16<\/td>\n17<\/td>\n<\/tr>\n
vt<\/td>\n(padding)<\/td>\npad1<\/td>\npad2<\/td>\npad3<\/td>\n(padding)<\/td>\npayload<\/td>\nfor non-DECIMAL<\/code><\/td>\n<\/tr>\n
(padding)<\/td>\nscale<\/span><\/td>\nsign<\/td>\n(padding)<\/td>\nmantissa_high<\/td>\nmantissa_low<\/td>\nfor DECIMAL<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Our attempt to squeeze out the padding just resulted in even more padding!<\/p>\n
The problem is that the DECIMAL<\/code> structure requires padding in order to align the two mantissa fields. There is no way to tell the compiler to  lay out a structure on the assumption that it always appears as part of a larger structure which misaligns its start address<\/a>. Mind you, even if there were a way to do it, you wouldn’t want to, because code is allowed to declare a standalone DECIMAL<\/code> structure that is not part of a VARIANT<\/code>, and now your promise is broken.<\/p>\n
The unnamed structure we introduced into our VARIANT<\/code> has the same problem as DECIMAL<\/code>, so it too gets alignment padding so that the unnamed structure starts at a multiple of 8.<\/p>\n
To get the layout we want, we must move the initial vt<\/code> inside the DECIMAL<\/code><\/i>.<\/p>\n
typedef struct tagDECIMAL\r\n{\r\n  uint16_t reserved;<\/span>\r\n  uint8_t scale;\r\n  uint8_t sign;\r\n  uint32_t mantissa_high;\r\n  uint64_t mantissa_low;\r\n} DECIMAL;\r\n\r\ntypedef struct tagVARIANT\r\n{\r\n  union {\r\n    struct {\r\n      uint16_t vt;\r\n      uint16_t pad1;\r\n      uint16_t pad2;\r\n      uint16_t pad3;\r\n      union {\r\n        uint64_t    llVal;\r\n        uint32_t    lVal;\r\n        uint8_t     bVal;\r\n        int16_t     iVal;\r\n        \u27e6 a whole bunch of other things \u27e7\r\n        \u27e6 the largest is 8 bytes        \u27e7\r\n        \u27e6 and requires 8-byte alignment \u27e7\r\n      };\r\n    };\r\n    DECIMAL decVal;\r\n  };\r\n};\r\n<\/pre>\n
The resulting layout is now<\/p>\n\n\n\n\n\n
0<\/td>\n1<\/td>\n2<\/td>\n3<\/td>\n4<\/td>\n5<\/td>\n6<\/td>\n7<\/td>\n8<\/td>\n9<\/td>\nA<\/td>\nB<\/td>\nC<\/td>\nD<\/td>\nE<\/td>\nF<\/td>\n<\/tr>\n
vt<\/td>\n(padding)<\/td>\npayload<\/td>\nfor non-DECIMAL<\/code><\/td>\n<\/tr>\n
reserved<\/td>\nscale<\/span><\/td>\nsign<\/td>\nmantissa_high<\/td>\nmantissa_low<\/td>\nfor DECIMAL<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
When the DECIMAL<\/code> is not part of a VARIANT<\/code> the reserved field is unused. But if it’s part of a VARIANT<\/code>, it’s living a double life as a vt<\/code>, and the value will always be VT_DECIMAL<\/code>.<\/p>\n
If a VARIANT<\/code> represents a DECIMAL<\/code>, you have the weird case that the vt<\/code> comes from the VARIANT<\/code>, but the other fields come from the DECIMAL<\/code>. Back in the days when the VARIANT<\/code> structure was defined, this sort of data punning was commonplace, and nobody would have batted an eye.<\/p>\n
Fortunately, even though compiler-writers might cast side-eye at this sort of thing, the trick is legal in this case because the vt<\/code> and wReserved<\/code> fields are both defined as unsigned short<\/code> and therefore satisfy the “common initial sequence” rule. This rule permits accessing the part of a non-active union member that shares a common initial sequence with the active union member. The basic idea is that you look for the longest stretch of initial elements of the two union members that agree in type, and those members can be read from one union member even if the other union member is the active member. (There is of course lots of fine print, but that’s the basic idea.)<\/p>\n
Bonus reading<\/b>:  Type Punning, Strict Aliasing, and Optimization<\/a> by John Regehr.<\/p>\n","protected":false},"excerpt":{"rendered":"
It’s where the discriminant goes when the DECIMAL<\/CODE> is put “inside” a VARIANT<\/CODE>.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-111185","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"
It’s where the discriminant goes when the DECIMAL<\/CODE> is put “inside” a VARIANT<\/CODE>.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/111185","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=111185"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/111185\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=111185"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=111185"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=111185"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}