From The Linux Foundation

Definitions

1. type here means an entry in the Type table, not the usual type declared in program
2. We say that type A is derived from type B, if any of the following conditions is satisfied:
   • A is a pointer to B (i.e. A is 'B *')
   • A is an address of B (i.e. A is 'B &')
   • A is B with const qualifier (i.e. A is 'const B')
   • A is an array of B (i.e. A is 'B[<size>]')
   • A is derived from type C which is derived from type B

Naming Conventions

From compiler point of view, the same derived type can be represented in many ways by varying spaces in its Tname, e.g. one can write 'void **', 'void * *' or 'void**', and these strings are treated by compiler in the same way. Unfortunately, it's not simple to explain this fact to the DBMS. Thus we use a naming convention for such cases, just to avoid separate entries in the Type table which actually designate the same type.

The naming rules are like the following:

• For pointers, first asterisk should be separated by single space from the base type name.
  Correct:

  void *

  Incorrect:

  void*

• In case of pointers to pointers, there should be no spaces between asterisks.
  Correct:

  void **; void ***

  Incorrect:

  void * *; void ** *

• const qualifier should be separated by a single space from its base.
  Correct:

  const int *; const const void *

  Incorrect:

  const  int; const  const void *

• If const qualifiers and pointer's asterisks should be mixed together, then the const qualifier should be separated from asterisks by a single space.
  Correct:

  sockaddr_in * const *

  Incorrect:

  int *const

  .
• For arrays, the name should be formed like the following:

  base_type_name[array_size]

  Note that there is no spaces between base type and the first bracket, as well as inside brackets. This rule should be followed for arrays of any levels.
  Correct:

  int[10]; void *[5]; char[12][25]

  Incorrect:

  int [10]; void *[ 5]; char[12] [25]

Note: In some cases, there is a need to create entry for an array that has different sizes on different architectures. For such cases we suggest to place dots ('...') as an array size.

• For function pointers, we suggest to use function synopsis (without parameter names) with optional fptr- prefix:

  [fptr-]<ret_type> (*)(<param1>, <param2>, ...)

  Please pay attention to space separators.
  Correct:

  int (*)(void *); fptr-void (*)(double, double)

  Incorrect:

  fptr-header_name-1

  .

'Incorrect' in all examples above doesn'n mean that you break anything by adding type with such name; but you can add an extra record for type that is already present in the database and can confuse other people who will use this type in future.

Assigning Types to HeaderGroups

All entries in the Type table should be assigned to some header group, except the following:

• Intrinsic types and all type derived from them
• Function pointers (Ttype='FuncPtr') and all types derived from them
• 'BinVariable' types which are used as return types of data symbols visible on binary level only (e.g. 'vtable for ...' or 'typeinfo for ...').

It is useful to set Theadgroup not only for 'usual' types (e.g. typedefs or structures), but for all types derived from them. I.e. if we have typedef named 'A' and pointer to it, 'A *', the pointer should be assigned to the same header group as the typedef itself. The thing is that there can be a type with the same name in another header, and we should have separate records for pointers on these different types, pointers to these pointers, etc.

A tricky case is function pointer. Our experience shows that it is better not to assign function pointers to header groups, but set correct Tlibrary field for them. I.e. we don't distinguish function pointers that are pointers to the same function inside one library, but we do distinguish such types if they belong to different libraries. The reason is the same as for types - different libraries may declare types with the same names, and we should distinguish pointers to functions that use types with the same names but from different libraries. One can notice that some headers inside one library may also contain types with the same names; well, the cases such types are used in function pointers are VERY rare; in case if you met such situation, you can resolve it manually (i.e. manually create several different records in the Type table for function pointers), but in general we recommend not to assign FuncPtrs to header groups.

Setting 'appearedin' Values for Types

Entries with the following Ttype SHOULD NOT be ever marked as included:

• Array
• Const
• FuncPtr
• Intrinsic
• Pointer
• Ref
• Unknown
• Volatile

If one of such entries is marked as included and assigned to header, then this can break the generated header.