@@ -213,6 +213,17 @@ If none of the above properties are provided, then the
The potential properties of this sections are listed below:
+* ``file_name_not_regexp``
+
+ Usage:
+
+ ``file_name_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+
+ Prevents the system from loading the file which name does not match
+ the regular expression specified as value of this property.
+
+
+
* ``file_name_regexp``
Usage:
@@ -222,14 +233,16 @@ The potential properties of this sections are listed below:
Prevents the system from loading the file which name matches the
regular expression specified as value of this property.
-* ``file_name_not_regexp``
- Usage:
+* ``label``
- ``file_name_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ Usage:
- Prevents the system from loading the file which name does not match
- the regular expression specified as value of this property.
+ ``label`` ``=`` <some-value>
+
+ Define a label for the section. A label is just an informative
+ string that might be used by the tool to refer to a type suppression
+ in error messages.
* ``soname_regexp``
@@ -254,16 +267,6 @@ The potential properties of this sections are listed below:
property. Note that this property also works on an abixml file if
it contains a SONAME property.
-* ``label``
-
- Usage:
-
- ``label`` ``=`` <some-value>
-
- Define a label for the section. A label is just an informative
- string that might be used by the tool to refer to a type suppression
- in error messages.
-
``[suppress_type]``
$$$$$$$$$$$$$$$$$$$
@@ -274,154 +277,124 @@ of the following properties must be provided:
``file_name_regexp``, ``file_name_not_regexp``, ``soname_regexp``,
``soname_not_regexp``, ``name``, ``name_regexp``,
- ``name_not_regexp``, ``type_kind``, ``source_location_not_in``,
- ``source_location_not_regexp``.
+ ``name_not_regexp``, ``source_location_not_in``,
+ ``source_location_not_regexp``, ``type_kind``.
If none of the above properties are provided, then the
``[suppress_type]`` directive is simply ignored.
The potential properties of this sections are listed below:
-* ``file_name_regexp``
-
- Usage:
-
- ``file_name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
-
- Suppresses change reports about ABI artifacts that are defined in a
- binary file which name matches the regular expression specified as
- value of this property.
-
-* ``file_name_not_regexp``
-
- Usage:
-
- ``file_name_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
- Suppresses change reports about ABI artifacts that are defined in a
- binary file which name does not match the regular expression
- specified as value of this property.
+ .. _suppr_accessed_through_property_label:
+* ``accessed_through``
-* ``soname_regexp``
+ Usage:
- Usage:
+ ``accessed_through`` ``=`` <some-predefined-values>
- ``soname_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ Suppress change reports involving a type which is referred to either
+ directly or through a pointer or a reference. The potential values
+ of this property are the predefined keywords below:
- Suppresses change reports about ABI artifacts that are defined in a
- shared library which SONAME property matches the regular expression
- specified as value of this property.
+ * ``direct``
-* ``soname_not_regexp``
+ So if the ``[suppress_type]`` contains the property
+ description: ::
- Usage:
+ accessed_through = direct
- ``soname_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ then changes about a type that is referred-to
+ directly (i.e, not through a pointer or a reference)
+ are going to be suppressed.
- Suppresses change reports about ABI artifacts that are defined in a
- shared library which SONAME property does not match the regular
- expression specified as value of this property.
+ * ``pointer``
-* ``name_regexp``
+ If the ``accessed_through`` property is set to the
+ value ``pointer`` then changes about a type that is
+ referred-to through a pointer are going to be
+ suppressed.
- Usage:
+ * ``reference``
- ``name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ If the ``accessed_through`` property is set to the
+ value ``reference`` then changes about a type that is
+ referred-to through a reference are going to be
+ suppressed.
- Suppresses change reports involving types whose name matches the
- regular expression specified as value of this property.
+ * ``reference-or-pointer``
+ If the ``accessed_through`` property is set to the
+ value ``reference-or-pointer`` then changes about a
+ type that is referred-to through either a reference
+ or a pointer are going to be suppressed.
-* ``name_not_regexp``
+ For an extensive example of how to use this property, please check
+ out the example below about :ref:`suppressing change reports about
+ types accessed either directly or through pointers
+ <example_accessed_through_label>`.
- Usage:
- ``name_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+.. _suppr_changed_enumerators_label:
- Suppresses change reports involving types whose name does *NOT* match
- the regular expression specified as value of this property. Said
- otherwise, this property specifies which types to keep, rather than
- types to suppress from reports.
+* ``changed_enumerators``
-* ``name``
+ Usage:
- Usage:
+ ``changed_enumerators`` ``=`` <list-of-enumerators>
+
+ Suppresses change reports involving changes in the value of
+ enumerators of a given enum type. This property is applied if the
+ ``type_kind`` property is set to the value ``enum``, at least. The
+ value of the ``changed_enumerators`` is a comma-separated list of
+ the enumerators that the user expects to change. For instance: ::
- ``name`` ``=`` <a-value>
+ changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1
- Suppresses change reports involving types whose name equals the value
- of this property.
-* ``type_kind``
+* ``drop``
Usage:
- ``type_kind`` ``=`` ``class`` | ``struct`` | ``union`` | ``enum`` |
- ``array`` | ``typedef`` | ``builtin``
-
- Suppresses change reports involving a certain kind of type. The kind
- of type to suppress change reports for is specified by the possible
- values listed above:
-
- - ``class``: suppress change reports for class types. Note that
- even if class types don't exist for C, this value still
- triggers the suppression of change reports for struct types,
- in C. In C++ however, it should do what it suggests.
-
- - ``struct``: suppress change reports for struct types in C or C++.
- Note that the value ``class`` above is a super-set of this
- one.
-
- - ``union``: suppress change reports for union types.
-
- - ``enum``: suppress change reports for enum types.
-
- - ``array``: suppress change reports for array types.
-
- - ``typedef``: suppress change reports for typedef types.
-
- - ``builtin``: suppress change reports for built-in (or native)
- types. Example of built-in types are char, int, unsigned int,
- etc.
+ ``drop`` ``=`` yes | no
- .. _suppr_source_location_not_in_label:
+ If a type is matched by a suppression specification which contains
+ the "drop" property set to "yes" (or to "true") then the type is not
+ even going to be represented in the internal representation of the
+ ABI being analyzed. This property makes its enclosing suppression
+ specification to be applied in the :ref:`early suppression
+ specification mode <early_suppression_mode_label>`. The net effect
+ is that it potentially reduces the memory used to represent the ABI
+ being analyzed.
-* ``source_location_not_in``
+ Please note that for this property to be effective, the enclosing
+ suppression specification must have at least one of the following
+ properties specified: ``name_regexp``, ``name``, ``name_regexp``,
+ ``source_location_not_in`` or ``source_location_not_regexp``.
- Usage:
- ``source_location_not_in`` ``=`` <``list-of-file-paths``>
+* ``file_name_not_regexp``
- Suppresses change reports involving a type which is defined in a file
- which path is *NOT* listed in the value ``list-of-file-paths``. Note
- that the value is a comma-separated list of file paths e.g, this
- property ::
-
- source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h
+ Usage:
- suppresses change reports about all the types that are *NOT* defined
- in header files whose path end up with the strings
- libabigail/abg-ir.h or libabigail/abg-dwarf-reader.h.
+ ``file_name_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
- .. _suppr_source_location_not_regexp_label:
+ Suppresses change reports about ABI artifacts that are defined in a
+ binary file which name does not match the regular expression
+ specified as value of this property.
-* ``source_location_not_regexp``
- Usage:
+* ``file_name_regexp``
- ``source_location_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ Usage:
- Suppresses change reports involving a type which is defined in a file
- which path does *NOT* match the :ref:`regular expression
- <suppr_regexp_label>` provided as value of the property. E.g, this
- property ::
+ ``file_name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
- source_location_not_regexp = libabigail/abg-.*\\.h
+ Suppresses change reports about ABI artifacts that are defined in a
+ binary file which name matches the regular expression specified as
+ value of this property.
- suppresses change reports involving all the types that are *NOT*
- defined in header files whose path match the regular expression
- provided a value of the property.
.. _suppr_has_data_member_label:
@@ -471,6 +444,7 @@ whose names match the regular expression ``^private_data_member``. In
other words, it would match any type which contains data members whose
names start with the string "private_data_member".
+
.. _suppr_has_data_member_inserted_at_label:
* ``has_data_member_inserted_at``
@@ -616,6 +590,7 @@ names start with the string "private_data_member".
}
+
.. _suppr_has_size_change_property_label:
* ``has_size_change``
@@ -632,103 +607,144 @@ and
Those properties will not match a type change if the size of the type
changes, unless the ``has_size_changes`` property is set to ``yes``.
+ .. _suppr_label_property_label:
- .. _suppr_accessed_through_property_label:
-
-* ``accessed_through``
+* ``label``
Usage:
- ``accessed_through`` ``=`` <some-predefined-values>
+ ``label`` ``=`` <some-value>
- Suppress change reports involving a type which is referred to either
- directly or through a pointer or a reference. The potential values
- of this property are the predefined keywords below:
+ Define a label for the section. A label is just an informative
+ string that might be used by a tool to refer to a type suppression in
+ error messages.
- * ``direct``
- So if the ``[suppress_type]`` contains the property
- description: ::
+* ``name``
- accessed_through = direct
+ Usage:
- then changes about a type that is referred-to
- directly (i.e, not through a pointer or a reference)
- are going to be suppressed.
+ ``name`` ``=`` <a-value>
- * ``pointer``
+ Suppresses change reports involving types whose name equals the value
+ of this property.
- If the ``accessed_through`` property is set to the
- value ``pointer`` then changes about a type that is
- referred-to through a pointer are going to be
- suppressed.
- * ``reference``
+* ``name_not_regexp``
- If the ``accessed_through`` property is set to the
- value ``reference`` then changes about a type that is
- referred-to through a reference are going to be
- suppressed.
+ Usage:
- * ``reference-or-pointer``
+ ``name_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
- If the ``accessed_through`` property is set to the
- value ``reference-or-pointer`` then changes about a
- type that is referred-to through either a reference
- or a pointer are going to be suppressed.
+ Suppresses change reports involving types whose name does *NOT* match
+ the regular expression specified as value of this property. Said
+ otherwise, this property specifies which types to keep, rather than
+ types to suppress from reports.
- For an extensive example of how to use this property, please check
- out the example below about :ref:`suppressing change reports about
- types accessed either directly or through pointers
- <example_accessed_through_label>`.
-* ``drop``
+* ``name_regexp``
Usage:
- ``drop`` ``=`` yes | no
+ ``name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
- If a type is matched by a suppression specification which contains
- the "drop" property set to "yes" (or to "true") then the type is not
- even going to be represented in the internal representation of the
- ABI being analyzed. This property makes its enclosing suppression
- specification to be applied in the :ref:`early suppression
- specification mode <early_suppression_mode_label>`. The net effect
- is that it potentially reduces the memory used to represent the ABI
- being analyzed.
+ Suppresses change reports involving types whose name matches the
+ regular expression specified as value of this property.
- Please note that for this property to be effective, the enclosing
- suppression specification must have at least one of the following
- properties specified: ``name_regexp``, ``name``, ``name_regexp``,
- ``source_location_not_in`` or ``source_location_not_regexp``.
- .. _suppr_label_property_label:
+* ``soname_not_regexp``
-* ``label``
+ Usage:
+
+ ``soname_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+
+ Suppresses change reports about ABI artifacts that are defined in a
+ shared library which SONAME property does not match the regular
+ expression specified as value of this property.
+
+
+* ``soname_regexp``
+
+ Usage:
+
+ ``soname_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+
+ Suppresses change reports about ABI artifacts that are defined in a
+ shared library which SONAME property matches the regular expression
+ specified as value of this property.
+
+ .. _suppr_source_location_not_in_label:
+
+* ``source_location_not_in``
Usage:
- ``label`` ``=`` <some-value>
+ ``source_location_not_in`` ``=`` <``list-of-file-paths``>
- Define a label for the section. A label is just an informative
- string that might be used by a tool to refer to a type suppression in
- error messages.
+ Suppresses change reports involving a type which is defined in a file
+ which path is *NOT* listed in the value ``list-of-file-paths``. Note
+ that the value is a comma-separated list of file paths e.g, this
+ property ::
+
+ source_location_not_in = libabigail/abg-ir.h, libabigail/abg-dwarf-reader.h
-.. _suppr_changed_enumerators_label:
+ suppresses change reports about all the types that are *NOT* defined
+ in header files whose path end up with the strings
+ libabigail/abg-ir.h or libabigail/abg-dwarf-reader.h.
-* ``changed_enumerators``
+ .. _suppr_source_location_not_regexp_label:
- Usage:
- ``changed_enumerators`` ``=`` <list-of-enumerators>
-
- Suppresses change reports involving changes in the value of
- enumerators of a given enum type. This property is applied if the
- ``type_kind`` property is set to the value ``enum``, at least. The
- value of the ``changed_enumerators`` is a comma-separated list of
- the enumerators that the user expects to change. For instance: ::
+* ``source_location_not_regexp``
+
+ Usage:
+
+ ``source_location_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+
+ Suppresses change reports involving a type which is defined in a file
+ which path does *NOT* match the :ref:`regular expression
+ <suppr_regexp_label>` provided as value of the property. E.g, this
+ property ::
+
+ source_location_not_regexp = libabigail/abg-.*\\.h
+
+ suppresses change reports involving all the types that are *NOT*
+ defined in header files whose path match the regular expression
+ provided a value of the property.
+
+
+* ``type_kind``
+
+ Usage:
+
+ ``type_kind`` ``=`` ``class`` | ``struct`` | ``union`` | ``enum`` |
+ ``array`` | ``typedef`` | ``builtin``
+
+ Suppresses change reports involving a certain kind of type. The kind
+ of type to suppress change reports for is specified by the possible
+ values listed above:
+
+ - ``class``: suppress change reports for class types. Note that
+ even if class types don't exist for C, this value still
+ triggers the suppression of change reports for struct types,
+ in C. In C++ however, it should do what it suggests.
+
+ - ``struct``: suppress change reports for struct types in C or C++.
+ Note that the value ``class`` above is a super-set of this
+ one.
+
+ - ``union``: suppress change reports for union types.
+
+ - ``enum``: suppress change reports for enum types.
+
+ - ``array``: suppress change reports for array types.
+
+ - ``typedef``: suppress change reports for typedef types.
+
+ - ``builtin``: suppress change reports for built-in (or native)
+ types. Example of built-in types are char, int, unsigned int,
+ etc.
- changed_enumerators = LAST_ENUMERATORS0, LAST_ENUMERATOR1
``[suppress_function]``
$$$$$$$$$$$$$$$$$$$$$$$$
@@ -751,25 +767,62 @@ If none of the above properties are provided, then the
The potential properties of this sections are:
-* ``label``
+
+ .. _suppr_change_kind_property_label:
+
+* ``change_kind``
Usage:
- ``label`` ``=`` <some-value>
+ ``change_kind`` ``=`` <predefined-possible-values>
- This property is the same as the :ref:`label property
- <suppr_label_property_label>` defined above.
+ Specifies the kind of changes this suppression specification should
+ apply to. The possible values of this property as well as their
+ meaning are listed below:
+ - ``function-subtype-change``
-* ``file_name_regexp``
+ This suppression specification applies to functions
+ that which have at least one sub-type that has
+ changed.
- Usage:
+ - ``added-function``
- ``file_name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ This suppression specification applies to functions
+ that have been added to the binary.
- Suppresses change reports about ABI artifacts that are defined in a
- binary file which name matches the regular expression specified as
- value of this property.
+ - ``deleted-function``
+
+ This suppression specification applies to functions
+ that have been removed from the binary.
+
+ - ``all``
+
+ This suppression specification applies to functions
+ that have all of the changes above. Note that not
+ providing the ``change_kind`` property at all is
+ equivalent to setting it to the value ``all``.
+
+
+* ``drop``
+
+ Usage:
+
+ ``drop`` ``=`` yes | no
+
+ If a function is matched by a suppression specification which
+ contains the "drop" property set to "yes" (or to "true") then the
+ function is not even going to be represented in the internal
+ representation of the ABI being analyzed. This property makes its
+ enclosing suppression specification to be applied in the :ref:`early
+ suppression specification mode <early_suppression_mode_label>`. The
+ net effect is that it potentially reduces the memory used to
+ represent the ABI being analyzed.
+
+ Please note that for this property to be effective, the enclosing
+ suppression specification must have at least one of the following
+ properties specified: ``name_regexp``, ``name``, ``name_regexp``,
+ ``source_location_not_in`` or ``source_location_not_regexp``.
* ``file_name_not_regexp``
@@ -782,25 +835,26 @@ The potential properties of this sections are:
binary file which name does not match the regular expression
specified as value of this property.
-* ``soname_regexp``
+
+* ``file_name_regexp``
Usage:
- ``soname_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ ``file_name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
Suppresses change reports about ABI artifacts that are defined in a
- shared library which SONAME property matches the regular expression
- specified as value of this property.
+ binary file which name matches the regular expression specified as
+ value of this property.
-* ``soname_not_regexp``
- Usage:
+* ``label``
- ``soname_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+ Usage:
- Suppresses change reports about ABI artifacts that are defined in a
- shared library which SONAME property does not match the regular
- expression specified as value of this property.
+ ``label`` ``=`` <some-value>
+
+ This property is the same as the :ref:`label property
+ <suppr_label_property_label>` defined above.
* ``name``
@@ -812,24 +866,6 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose name equals the
value of this property.
-* ``name_regexp``
-
- Usage:
-
- ``name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
-
- Suppresses change reports involving functions whose name matches the
- regular expression specified as value of this property.
-
- Let's consider the case of functions that have several symbol names.
- This happens when the underlying symbol for the function has
- aliases. Each symbol name is actually one alias name.
-
- In this case, if the regular expression matches the name of
- at least one of the aliases names, then it must match the names of
- all of the aliases of the function for the directive to actually
- suppress the diff reports for said function.
-
* ``name_not_regexp``
@@ -843,41 +879,24 @@ The potential properties of this sections are:
The rules for functions that have several symbol names are the same
rules as for the ``name_regexp`` property above.
- .. _suppr_change_kind_property_label:
-
-* ``change_kind``
+* ``name_regexp``
Usage:
- ``change_kind`` ``=`` <predefined-possible-values>
-
- Specifies the kind of changes this suppression specification should
- apply to. The possible values of this property as well as their
- meaning are listed below:
-
- - ``function-subtype-change``
-
- This suppression specification applies to functions
- that which have at least one sub-type that has
- changed.
-
- - ``added-function``
-
- This suppression specification applies to functions
- that have been added to the binary.
-
- - ``deleted-function``
+ ``name_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
- This suppression specification applies to functions
- that have been removed from the binary.
+ Suppresses change reports involving functions whose name matches the
+ regular expression specified as value of this property.
- - ``all``
+ Let's consider the case of functions that have several symbol names.
+ This happens when the underlying symbol for the function has
+ aliases. Each symbol name is actually one alias name.
- This suppression specification applies to functions
- that have all of the changes above. Note that not
- providing the ``change_kind`` property at all is
- equivalent to setting it to the value ``all``.
+ In this case, if the regular expression matches the name of
+ at least one of the aliases names, then it must match the names of
+ all of the aliases of the function for the directive to actually
+ suppress the diff reports for said function.
* ``parameter``
@@ -928,6 +947,7 @@ The potential properties of this sections are:
other words, this is the third parameter and it's a
reference on a type that starts with the string "foo".
+
* ``return_type_name``
Usage:
@@ -937,6 +957,7 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose return type name
equals the value of this property.
+
* ``return_type_regexp``
Usage:
@@ -946,6 +967,29 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose return type name
matches the regular expression specified as value of this property.
+
+* ``soname_regexp``
+
+ Usage:
+
+ ``soname_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+
+ Suppresses change reports about ABI artifacts that are defined in a
+ shared library which SONAME property matches the regular expression
+ specified as value of this property.
+
+
+* ``soname_not_regexp``
+
+ Usage:
+
+ ``soname_not_regexp`` ``=`` <:ref:`regular-expression <suppr_regexp_label>`>
+
+ Suppresses change reports about ABI artifacts that are defined in a
+ shared library which SONAME property does not match the regular
+ expression specified as value of this property.
+
+
* ``symbol_name``
Usage:
@@ -955,6 +999,7 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose symbol name equals
the value of this property.
+
* ``symbol_name_regexp``
Usage:
@@ -972,6 +1017,7 @@ The potential properties of this sections are:
the aliases of the function for the directive to actually suppress
the diff reports for said function.
+
* ``symbol_name_not_regexp``
Usage:
@@ -981,6 +1027,7 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose symbol name does
not match the regular expression specified as value of this property.
+
* ``symbol_version``
Usage:
@@ -990,6 +1037,7 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose symbol version
equals the value of this property.
+
* ``symbol_version_regexp``
Usage:
@@ -999,25 +1047,6 @@ The potential properties of this sections are:
Suppresses change reports involving functions whose symbol version
matches the regular expression specified as value of this property.
-* ``drop``
-
- Usage:
-
- ``drop`` ``=`` yes | no
-
- If a function is matched by a suppression specification which
- contains the "drop" property set to "yes" (or to "true") then the
- function is not even going to be represented in the internal
- representation of the ABI being analyzed. This property makes its
- enclosing suppression specification to be applied in the :ref:`early
- suppression specification mode <early_suppression_mode_label>`. The
- net effect is that it potentially reduces the memory used to
- represent the ABI being analyzed.
-
- Please note that for this property to be effective, the enclosing
- suppression specification must have at least one of the following
- properties specified: ``name_regexp``, ``name``, ``name_regexp``,
- ``source_location_not_in`` or ``source_location_not_regexp``.
``[suppress_variable]``
$$$$$$$$$$$$$$$$$$$$$$$$