Annotating Structs and Classes

You can annotate struct and class members by using annotations that act like invariants—they are presumed to be true at any function call or function entry/exit that involves the enclosing structure as a parameter or a result value.

Struct and Class Annotations

• _Field_range_(low, high)

  The field is in the range (inclusive) from low to high. Equivalent to _Satisfies_(_Curr_ >= low && _Curr_ <= high) applied to the annotated object by using the appropriate pre or post conditions.

• _Field_size_(size), _Field_size_opt_(size), _Field_size_bytes_(size), _Field_size_bytes_opt_(size)

  A field that has a writable size in elements (or bytes) as specified by size.

• _Field_size_part_(size, count), _Field_size_part_opt_(size, count), _Field_size_bytes_part_(size, count), _Field_size_bytes_part_opt_(size, count)

  A field that has a writable size in elements (or bytes) as specified by size, and the count of those elements (bytes) that are readable.

• _Field_size_full_(size), _Field_size_full_opt_(size), _Field_size_bytes_full_(size), _Field_size_bytes_full_opt_(size)

  A field that has both readable and writable size in elements (or bytes) as specified by size.

• _Struct_size_bytes_(size)

  A field that has both readable and writable size in elements (or bytes) as specified by size.

  Applies to struct or class declaration. Indicates that a valid object of that type may be larger than the declared type, with the number of bytes being specified by size. For example:

  
  typedef _Struct_size_bytes_(nSize)  
  struct MyStruct {  
      size_t nSize;  
      …  
  };  
  
  

  The buffer size in bytes of a parameter pM of type MyStruct * is then taken to be:

  min(pM->nSize, sizeof(MyStruct))  
  

See Also

Using SAL Annotations to Reduce C/C++ Code Defects
Understanding SAL
Annotating Function Parameters and Return Values
Annotating Function Behavior
Annotating Locking Behavior
Specifying When and Where an Annotation Applies
Intrinsic Functions
Best Practices and Examples