strace's Named Constant Support (xlat) Documentation

strace has extensive support for decoding various named constants that appear in various places of Linux API surface, that is handled by similarly extensive API and infrastructure. This document is an attempt to capture the current state of it and provide information related to its usage.

File Format

xlat file is a file in a text-like format with ".in" extension, placed in the "xlat" directory. It is the basis of a C header file generation

It is interpreted line-by-line (by xlat/gen.sh script). Each line can be one of the following:

• One of the annotations, that start with # symbol and are listed below.

• Preprocessor definitions, that start with # and are not part of annotations listed below.

• Constants, that start either with one of A-Z characters, "1<<" character sequence, or a number.

• Any other content.

xlat/gen.sh processes the xlat file in two passes:

1. To generate constant check/definition rules.
2. To generate xlat struct definition.

The following rules are applied during processing:

• Annotations are processed as following:

  • #conditional

  • #unconditional

  • #val_type TYPE

  • #sorted [COMMAND]`

  • #value_indexed

  • #enum

  • #include INCLUDE

• Preprocessor definitions are emitted verbatim during the both passes.
• Constants ...
• The rest is added verbatim at the second pass.

API

The xlat-related API is split between two files:

• xlat.h contains main type definitions, xlat style flags, and xlat constant definition macros.

• defs.h contains functions and function-like macros for using xlats.

Types

The main type is struct xlat. It is defined as follows:

   1 enum xlat_type {
   2         XT_NORMAL,
   3         XT_SORTED,
   4         XT_INDEXED,
   5 };
   6 
   7 struct xlat_data {
   8         uint64_t val;
   9         const char *str;
  10 };
  11 
  12 struct xlat {
  13         const struct xlat_data *data;
  14         size_t flags_strsz;
  15         uint32_t size;
  16         enum xlat_type type;
  17         uint64_t flags_mask;
  18 };

xlat Styles

Functions and Macros

Things to Remember