[This structure is valid only for version 3 of NTFS volumes; it may be altered in future versions.]
Represents an attribute record.
Syntax
typedef struct _ATTRIBUTE_RECORD_HEADER {
ATTRIBUTE_TYPE_CODE TypeCode;
ULONG RecordLength;
UCHAR FormCode;
UCHAR NameLength;
USHORT NameOffset;
USHORT Flags;
USHORT Instance;
union {
struct {
ULONG ValueLength;
USHORT ValueOffset;
UCHAR Reserved[2];
} Resident;
struct {
VCN LowestVcn;
VCN HighestVcn;
USHORT MappingPairsOffset;
UCHAR Reserved[6];
LONGLONG AllocatedLength;
LONGLONG FileSize;
LONGLONG ValidDataLength;
LONGLONG TotalAllocated;
} Nonresident;
} Form;
} ATTRIBUTE_RECORD_HEADER, *PATTRIBUTE_RECORD_HEADER;
Members
TypeCode
The attribute type code.
| Value | Meaning |
|---|---|
| $STANDARD_INFORMATION 0x10 | File attributes (such as read-only and archive), time stamps (such as file creation and last modified), and the hard link count. |
| $ATTRIBUTE_LIST 0x20 | A list of attributes that make up the file and the file reference of the MFT file record in which each attribute is located. |
| $FILE_NAME 0x30 | The name of the file, in Unicode characters. |
| $OBJECT_ID 0x40 | A 64-byte object identifier assigned by the link-tracking service. |
| $VOLUME_NAME 0x60 | The volume label. Present in the $Volume file. |
| $VOLUME_INFORMATION 0x70 | The volume information. Present in the $Volume file. |
| $DATA 0x80 | The contents of the file. |
| $INDEX_ROOT 0x90 | Used to implement filename allocation for large directories. |
| $INDEX_ALLOCATION 0xA0 | Used to implement filename allocation for large directories. |
| $BITMAP 0xB0 | A bitmap index for a large directory. |
| $REPARSE_POINT 0xC0 | The reparse point data. |
RecordLength
The size of the attribute record, in bytes. This value reflects the required size for the record variant and is always rounded to the nearest quadword boundary.
FormCode
The attribute form code.
| Value | Meaning |
|---|---|
| RESIDENT_FORM 0x00 | The value is contained in the file record and immediately follows the attribute record header. |
| NONRESIDENT_FORM 0x01 | The value is contained in other sectors on the disk. |
NameLength
The size of the optional attribute name, in characters, or 0 if there is no attribute name. The maximum attribute name length is 255 characters.
NameOffset
The offset of the attribute name from the start of the attribute record, in bytes. If the NameLength member is 0, this member is undefined.
Flags
The attribute flags.
ATTRIBUTE_FLAG_COMPRESSION_MASK (0x00FF)
ATTRIBUTE_FLAG_SPARSE (0x8000)
ATTRIBUTE_FLAG_ENCRYPTED (0x4000)
Instance
The unique instance for this attribute in the file record.
Form
If the FormCode member is RESIDENT_FORM, the union is a Resident structure. If FormCode is NONRESIDENT_FORM, the union is a Nonresident structure.
Resident
ValueLength
The size of the attribute value, in bytes.
ValueOffset
The offset to the value from the start of the attribute record, in bytes.
Reserved
Reserved.
Nonresident
LowestVcn
The lowest virtual cluster number (VCN) covered by this attribute record.
HighestVcn
The highest VCN covered by this attribute record.
MappingPairsOffset
The offset to the mapping pairs array from the start of the attribute record, in bytes. For more information, see Remarks.
Reserved
Reserved.
AllocatedLength
The allocated size of the file, in bytes. This value is an even multiple of the cluster size. This member is not valid if the LowestVcn member is nonzero.
FileSize
The file size (highest byte that can be read plus 1), in bytes. This member is not valid if LowestVcn is nonzero.
ValidDataLength
The valid data length (highest initialized byte plus 1), in bytes. This value is rounded to the nearest cluster boundary. This member is not valid if LowestVcn is nonzero.
TotalAllocated
The total allocated for the file (the sum of the allocated clusters).
Remarks
Note that there is no associated header file for this structure.
This structure definition is valid only for major version 3 and minor version 0 or 1, as reported by FSCTL_GET_NTFS_VOLUME_DATA.
Attribute records are always aligned on a quadword boundary.
If the attribute is nonresident, the attribute record header contains a list of retrieval information that provides a mapping between VCN and logical cluster number (LCN) for the attribute. If the retrieval information does not fit in the base file segment, it can be stored in an external file record segment by itself. If it still does not fit into one external file record segment, there is a provision in the attribute list to contain multiple entries for an attribute that requires additional retrieval information.
The mapping pairs array is stored in a compressed form and assumes that the information is decompressed and cached by the system. It consists of a series of NextVcn/CurrentLcn pairs. For example, if a file has a single run of 8 clusters starting at LCN 128 and the file starts at LowestVcn 0, then the mapping pairs array has just one entry, which is NextVcn=8 and CurrentLcn=128. The array is a byte stream that stores the changes to the working variables when processed sequentially. The byte stream is to be interpreted as a zero-terminated stream of triples, as follows:
count byte = v + (l * 16)
where v is the number of changed low-order VCN bytes and l is the number of changed low-order LCN bytes.
The decompression algorithm is as follows:
- Initialize NextVcn to
Attribute->LowestVcnand CurrentLcn to 0. - Initialize the byte stream pointer to
(PCHAR)Attribute + Attribute->AttributeForm->Nonresident->MappingPairsOffset. - Set CurrentVcn to NextVcn.
- Read the next byte from the stream. If it is 0, then break; else extract v and l as previously described.
- Interpret the next v bytes as a signed quantity, with the low-order byte first. Unpack it sign-extended into 64 bits and add it to NextVcn.
- Interpret the next l bytes as a signed quantity, with the low-order byte first. Unpack it sign-extended into 64 bits and add it to CurrentLcn. If this produces a CurrentLcn of 0, then the VCNs from CurrentVcn to NextVcn–1 are unallocated.
- Update the cached mapping information from CurrentVcn, NextVcn, and CurrentLcn.
- Go to step 3.
See also
Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.
