Configuration files¶

Option name¶

• Description: This option allows to give a name to the analysis configuration. This name is used in the GUI field to select the analysis configuration if the configuration file contains several ones, which can be more convenient than its number.

  The name can also be used to select an analysis configuration from the command line with the -tis-config-select-by-name option.

  The given name is cosmetic and has no impact on the performed analysis.

• Type: string

Example:

[
  {
    "name": "configuration_name_1",
    "files": [
        "file_name_1.c",
        "file_name_2.c"
      ]
  },
  {
    "name": "configuration_name_2",
    "files": [
      {
        "name": "file_name_1.c",
        "cpp-extra-args": [
            "-I./include/"
        ]
      },
      {
        "name": "file_name_3.c"
      }
    ]
  }
]

Usage :

tis-analyzer -tis-config-load tis.config -tis-config-select-by-name \
  configuration_name_1

tis-analyzer -tis-config-load tis.config -tis-config-select-by-name \
  configuration_name_2

Note that you can switch from one configuration to another in the GUI, using the `Analysis configuration to run:` combo-box

Option files¶

• Description: The collection of files to analyze. Accepts either a list of file paths or the value "all". Listed file paths are relative to the location of the configuration file (or the prefix_path value if set) and may contain the wildcard * to match any string. The value "all" selects all source files contained in the directory of the configuration file, or, if prefix_path is set, all source files in prefix_path. If this field is set in a configuration file, all other source files given on the command line will be ignored.

  Examples:

  { "files": "all" }
  

  { "files": [ "src/aes.c", "main.c" ] }
  

  { "files": [ "src/*.c", "main.c" ] }
  

  { "files":
    [ { "name": "src/aes.c",
        "cpp-extra-args": "-I include -D ARG=2" },
      "main.c" ] }
  

  Note: Use the compilation_cmd field to add extra arguments to the pre-processor command for every file.

• Type:

  • string among the following values:

    • “all”

  • list of:

    • strings

    • objects with fields:

      • name (required): The name of the file.

        Type: string

      • cpp-command (optional): The command to use to pre-process the file. See also the -cpp-command-file command line option. Beware: relative paths in this field are kept unchanged (and are relative to the analyzer working directory and not the configuration file directory). The special option prefix_path does not affect paths of this field either. Use the cpp-extra-args field instead for options involving a path.

        Type: string

      • cpp-extra-args (optional): The extra arguments to add to the pre-processor command for the file. See also the -cpp-extra-args-file command line option. however only relevant options for pre-processing are kept. Relative paths are affected by the directory containing the configuration file and the prefix_path field.

        Type: string

Option filesystem¶

• Description: The virtual file system and its options to use for the analysis. See also tis-mkfs Manual. If the object of this field does not contain a "files" or "use", and if "enabled" is set to true, then a default empty filesystem is used.

• Type: object with fields:

  • enabled (optional): If enabled, the virtual file system is used during the analysis. If the feature is disabled, it can still be enabled later from the GUI. Default true

    Type: boolean

  • system_errors (optional): If set, system errors are simulated while accessing the file system. Default: value of the option -fs-error

    Type: boolean

  • files (optional): The list of files in the virtual file system. This list can be empty. This field is not compatible with the "use" one.

    Type: list of:

    • strings

    • objects with fields:

      • name (required): Name of the file (or directory) in the virtual file system. It should exactly match the string given to the filesystem functions in the C code.

        Type: string

      • type (optional): Type of the abstract file. This field is incompatible with "from", "size", "min_val" and "max_val". The supported files are regular files, directories, named pipes and character devices. If this field not given, as well as the "from" or "size" field, the default type of the file is a regular one.

        Type: string among the following values:

        • “chr”
        • “dir”
        • “fifo”
        • “file”

      • from (optional): If given, the content of the file (or directory) in the virtual file system will be the one of the real file located at the given path. If not given, the content of the file (or directory) will be abstracted. See more at File Generation. Note: if given, this filename is relative to the configuration file directory (unless the filename is absolute), and also depends on the special option prefix_path.

        Type: string

      • size (optional): First argument of the -generic option of tis-mkfs. It represents the number of bytes of the file. See more at File Generation. This field is not compatible with "from". Fields "min_val" and "max_val" are also required if this one is given.

        Type: integer

      • min_val (optional): Second argument of the -generic option of tis-mkfs. It represents the minimal value of the interval for each character of the file. See more at File Generation. This field is not compatible with "from". Fields "size" and "max_val" are also required if this one is given.

        Type: integer

      • max_val (optional): Third argument of the -generic option of tis-mkfs. It represents the maximal value of the interval for each character of the file. See more at File Generation. This field is not compatible with "from". Fields "size" and "min_val" are also required if this one is given.

        Type: integer

  • nb_max_files (optional): The maximum number of files that can be created by the program during the analysis. This field is relevant only if the "files" is given. Default: 20

    Type: integer

  • nb_max_dirs (optional): The maximum number of directories that can be created by the program during the analysis. This field is relevant only if the "files" is given. Default: 20

    Type: integer

  • generated_filename (optional): The name of the generated C file containing the virtual file system. This field is relevant only if the "files" is given. Note: if given, this filename is relative to the configuration file directory (unless the filename is absolute), and also depends on the special option prefix_path. Default: "tis-mkfs-filesystem.c"

    Type: string

  • use (optional): Name of a tis-mkfs generated C file to use instead of a list of files. This field is not compatible with the "files" one. Note: if given, this filename is relative to the configuration file directory (unless the filename is absolute), and also depends on the special option prefix_path.

    Type: string

Option language¶

• Description: The language to use for the analysis.

  Setting a language allows to automatically set a list of options to correctly analyzing the program according to the given language.

  The language is set after any other options of the configuration file, hence the list of options set by this language cannot be overwritten by a field of the configuration file.

  The auto value allows to decide which language to use according to the given list of source files.

  Note: If this field is not given, the behavior is the same as the auto value.

  Note: The automatic detection of the language is only performed if a configuration file is read. Using the analyzer with the command line without a configuration file will not perform the automatic detection of the language.

• Type: string among the following values:

  • “auto”
  • “c”
  • “c++”

Option prefix_path¶

• Description: This option allows to prefix all filenames with the given path.

  { "prefix_path": "path/to/another_directory" }
  

  • If the prefix_path option is not specified in the configuration file, by default, all relative filenames are relative to the directory containing the configuration file.
  • If the prefix_path option is given with an absolute path (which is not recommended), all relative filenames are prefixed by this path.
  • If the prefix_path option is given with a relative path, all relative filenames are prefixed by <directory containing the configuration file>/<prefix_path>

  Tip

  If the value of the option files is all, then only files located in the given prefix_path are selected.

  For instance, the following configuration file:

  {
    "files":
      [
        "src/dir/file1.c",
        "src/dir/file2.c"
      ],
    "cpp-extra-args": "-DFOO=4 -Isrc/dir/headers"
  }
  

  is equivalent to this one:

  {
    "prefix_path": "src/dir",
    "files":
      [
        "file1.c",
        "file2.c"
      ],
    "cpp-extra-args": "-DFOO=4 -Iheaders"
  }
  

• Type: string

Option include¶

• Description: An analysis configuration also allows the usage of the option include in order to load other configuration files, which must contain only a single analysis configuration each.

  { "include": "path/to/another_configuration_file.config" }
  

  For each option in the included configuration:

  • If the option has not been declared before the special option include, it will be added to the main configuration.
  • If the option has already been declared before the special option include:
    • If the option’s type is a list of values, the value of the option in the included configuration will be concatenated to the existing one in the main configuration.
    • Otherwise, the value of the option in the included configuration will replace the value in the main configuration.

  For any option declared after the include option in the main configuration, the value of the option will either be added, be concatenated or will replace the one declared in the included configuration by following the same rules as above.

  The following two analysis configurations:

  {
    "files": [ "test.c" ],
    "slevel": 150,
    "include": "dir/other.config",
    "val-stop-at-nth-alarm": 8
  }
  

  {
    "files": [ "other.c" ],
    "slevel": 10,
    "val-stop-at-nth-alarm": 4
  }
  

  are equivalent to this single analysis configuration:

  {
    "files": [ "test.c", "dir/other.c" ],
    "slevel": 10,
    "val-stop-at-nth-alarm": 8
  }
  

  Several configuration files can be included with a single include option.

  {
    "include":
      [
        "path/to/sub_config1.config",
        "path/to/sub_config2.config",
        "common/common.config"
      ]
  }
  

  In this case, the first configuration file to include is processed according to the above rules. Then the resulting configuration will be considered as the main one for the second configuration file to include, and so on…

• Type:

  • string
  • list of strings

Command line options¶

The command line options allowing to tune the analyzer can also be given in the configuration file. The command line option name needs to be written without the leading dash - (such as slevel-function instead of -slevel-function).

tis-analyzer -val -slevel 100 -main my_function

{
   "val": true,
   "slevel": 100,
   "main": "my_function"
}

{ "slevel": "0x100" }

tis-analyzer
  -cpp-extra-args=-Iinclude/
  -cpp-extra-args=-DFN(a\,b)=my_function(a\,b)
  -val-slevel-merge-after-loop "@all,-main"

{
   "cpp-extra-args":
     [
       "-Iinclude/",
       "-DFN(a,b)=my_function(a,b)"
     ],
   "val-slevel-merge-after-loop":
     [
       "@all",
       "-main"
     ]
}

{ "cpp-extra-args":
    [ "-Iinclude/",
      "-DFN(a,b)=my_function(a,b)" ] }

{ "cpp-extra-args": "-Iinclude/",
  "cpp-extra-args": "-DFN(a,b)=my_function(a,b)" }

tis-analyzer
  -slevel-function "f:100,g:50,h:56,main:42"
  -slevel-function "f:110,-g"

{
  "slevel-function":
    {
      "f": 100,
      "g": 50,
      "h": 56,
      "main": 42,
      "f": 110,
      "g": null
    }
}