# deb-src-symbols

## NAME



           deb-src-symbols - Debian's extended shared library template file
    


## SYNOPSIS



           **debian/**_package_**.symbols.**_arch_ , **debian/symbols.**_arch_ ,
           **debian/**_package_**.symbols** , **debian/symbols**
    


## DESCRIPTION



           The symbol file templates are shipped in Debian source packages,
           and its format is a superset of the symbols files shipped in
           binary packages, see deb-symbols(5).
    
       **Comments**
           Comments are supported in template symbol files.  Any line with
           ‘#’ as the first character is a comment except if it starts with
           ‘#include’ (see section "Using includes").  Lines starting with
           ‘#MISSING:’ are special comments documenting symbols that have
           disappeared.
    
       **Using #PACKAGE# substitution**
           In some rare cases, the name of the library varies between
           architectures.  To avoid hardcoding the name of the package in the
           symbols file, you can use the marker _#PACKAGE#_.  It will be
           replaced by the real package name during installation of the
           symbols files.  Contrary to the _#MINVER#_ marker, _#PACKAGE#_ will
           never appear in a symbols file inside a binary package.
    
       **Using symbol tags**
           Symbol tagging is useful for marking symbols that are special in
           some way.  Any symbol can have an arbitrary number of tags
           associated with it.  While all tags are parsed and stored, only
           some of them are understood by **dpkg-gensymbols** and trigger special
           handling of the symbols.  See subsection "Standard symbol tags"
           for reference of these tags.
    
           Tag specification comes right before the symbol name (no
           whitespace is allowed in between).  It always starts with an
           opening bracket **(** , ends with a closing bracket **)** and must contain
           at least one tag.  Multiple tags are separated by the **|** character.
           Each tag can optionally have a value which is separated form the
           tag name by the **=** character.  Tag names and values can be
           arbitrary strings except they cannot contain any of the special **)**
           **| =** characters.  Symbol names following a tag specification can
           optionally be quoted with either **'** or **"** characters to allow
           whitespaces in them.  However, if there are no tags specified for
           the symbol, quotes are treated as part of the symbol name which
           continues up until the first space.
    
             (tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
             (optional)tagged_unquoted_symbol@Base 1.0 1
             untagged_symbol@Base 1.0
    
           The first symbol in the example is named _tagged quoted symbol_ and
           has two tags: _tag1_ with value _i am marked_ and _tag name with space_
           that has no value.  The second symbol named _tagged_unquoted_symbol_
           is only tagged with the tag named _optional_.  The last symbol is an
           example of the normal untagged symbol.
    
           Since symbol tags are an extension of the deb-symbols(5) format,
           they can only be part of the symbols files used in source packages
           (those files should then be seen as templates used to build the
           symbols files that are embedded in binary packages).  When
           **dpkg-gensymbols** is called without the **-t** option, it will output
           symbols files compatible to the deb-symbols(5) format: it fully
           processes symbols according to the requirements of their standard
           tags and strips all tags from the output.  On the contrary, in
           template mode (**-t**) all symbols and their tags (both standard and
           unknown ones) are kept in the output and are written in their
           original form as they were loaded.
    
       **Standard symbol tags**
           **optional**
               A symbol marked as optional can disappear from the library at
               any time and that will never cause **dpkg-gensymbols** to fail.
               However, disappeared optional symbols will continuously appear
               as MISSING in the diff in each new package revision.  This
               behavior serves as a reminder for the maintainer that such a
               symbol needs to be removed from the symbol file or readded to
               the library.  When the optional symbol, which was previously
               declared as MISSING, suddenly reappears in the next revision,
               it will be upgraded back to the “existing” status with its
               minimum version unchanged.
    
               This tag is useful for symbols which are private where their
               disappearance do not cause ABI breakage.  For example, most of
               C++ template instantiations fall into this category.  Like any
               other tag, this one may also have an arbitrary value: it could
               be used to indicate why the symbol is considered optional.
    
           **arch=**_architecture-list_
           **arch-bits=**_architecture-bits_
           **arch-endian=**_architecture-endianness_
               These tags allow one to restrict the set of architectures
               where the symbol is supposed to exist.  The **arch-bits** and
               **arch-endian** tags are supported since dpkg 1.18.0.  When the
               symbols list is updated with the symbols discovered in the
               library, all arch-specific symbols which do not concern the
               current host architecture are treated as if they did not
               exist.  If an arch-specific symbol matching the current host
               architecture does not exist in the library, normal procedures
               for missing symbols apply and it may cause **dpkg-gensymbols** to
               fail.  On the other hand, if the arch-specific symbol is found
               when it was not supposed to exist (because the current host
               architecture is not listed in the tag or does not match the
               endianness and bits), it is made arch neutral (i.e. the arch,
               arch-bits and arch-endian tags are dropped and the symbol will
               appear in the diff due to this change), but it is not
               considered as new.
    
               When operating in the default non-template mode, among
               arch-specific symbols only those that match the current host
               architecture are written to the symbols file.  On the
               contrary, all arch-specific symbols (including those from
               foreign arches) are always written to the symbol file when
               operating in template mode.
    
               The format of _architecture-list_ is the same as the one used in
               the **Build-Depends** field of _debian/control_ (except the
               enclosing square brackets []).  For example, the first symbol
               from the list below will be considered only on arm64,
               any-amd64 and riscv64 architectures, the second only on linux
               architectures, while the third one anywhere except on armel.
    
                 (arch=arm64 any-amd64 riscv64)arch_specific_symbol@Base 1.0
                 (arch=linux-any)linux_specific_symbol@Base 1.0
                 (arch=!armel)symbol_armel_does_not_have@Base 1.0
    
               The _architecture-bits_ is either **32** or **64**.
    
                 (arch-bits=32)32bit_specific_symbol@Base 1.0
                 (arch-bits=64)64bit_specific_symbol@Base 1.0
    
               The _architecture-endianness_ is either **little** or **big**.
    
                 (arch-endian=little)little_endian_specific_symbol@Base 1.0
                 (arch-endian=big)big_endian_specific_symbol@Base 1.0
    
               Multiple restrictions can be chained.
    
                 (arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0
    
           **allow-internal**
               dpkg-gensymbols has a list of internal symbols that should not
               appear in symbols files as they are usually only side-effects
               of implementation details of the toolchain (since dpkg
               1.20.1).  If for some reason, you really want one of those
               symbols to be included in the symbols file, you should tag the
               symbol with **allow-internal**.  It can be necessary for some low
               level toolchain libraries like “libgcc”.
    
           **c++** Denotes _c++_ symbol pattern.  See "Using symbol patterns"
               subsection below.
    
           **symver**
               Denotes _symver_ (symbol version) symbol pattern.  See "Using
               symbol patterns" subsection below.
    
           **regex**
               Denotes _regex_ symbol pattern.  See "Using symbol patterns"
               subsection below.
    
       **Using symbol patterns**
           Unlike a standard symbol specification, a pattern may cover
           multiple real symbols from the library.  **dpkg-gensymbols** will
           attempt to match each pattern against each real symbol that does
           _not_ have a specific symbol counterpart defined in the symbol file.
           Whenever the first matching pattern is found, all its tags and
           properties will be used as a basis specification of the symbol.
           If none of the patterns matches, the symbol will be considered as
           new.
    
           A pattern is considered lost if it does not match any symbol in
           the library.  By default this will trigger a **dpkg-gensymbols**
           failure under **-c1** or higher level.  However, if the failure is
           undesired, the pattern may be marked with the _optional_ tag.  Then
           if the pattern does not match anything, it will only appear in the
           diff as MISSING.  Moreover, like any symbol, the pattern may be
           limited to the specific architectures with the _arch_ tag.  Please
           refer to "Standard symbol tags" subsection above for more
           information.
    
           Patterns are an extension of the deb-symbols(5) format hence they
           are only valid in symbol file templates.  Pattern specification
           syntax is not any different from the one of a specific symbol.
           However, symbol name part of the specification serves as an
           expression to be matched against _name@version_ of the real symbol.
           In order to distinguish among different pattern types, a pattern
           will typically be tagged with a special tag.
    
           At the moment, **dpkg-gensymbols** supports three basic pattern types:
    
           **c++** This pattern is denoted by the _c++_ tag.  It matches only C++
               symbols by their demangled symbol name (as emitted by
               c++filt(1) utility).  This pattern is very handy for matching
               symbols which mangled names might vary across different
               architectures while their demangled names remain the same.
               One group of such symbols is _non-virtual thunks_ which have
               architecture specific offsets embedded in their mangled names.
               A common instance of this case is a virtual destructor which
               under diamond inheritance needs a non-virtual thunk symbol.
               For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32-bit
               architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base
               on 64-bit ones, it can be matched with a single _c++_ pattern:
    
                libdummy.so.1 libdummy1 #MINVER#
                 [...]
                 (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
                 [...]
    
               The demangled name above can be obtained by executing the
               following command:
    
                 $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
    
               Please note that while mangled name is unique in the library
               by definition, this is not necessarily true for demangled
               names.  A couple of distinct real symbols may have the same
               demangled name.  For example, that's the case with non-virtual
               thunk symbols in complex inheritance configurations or with
               most constructors and destructors (since g++ typically
               generates two real symbols for them).  However, as these
               collisions happen on the ABI level, they should not degrade
               quality of the symbol file.
    
           **symver**
               This pattern is denoted by the _symver_ tag.  Well maintained
               libraries have versioned symbols where each version
               corresponds to the upstream version where the symbol got
               added.  If that's the case, you can use a _symver_ pattern to
               match any symbol associated to the specific version.  For
               example:
    
                libc.so.6 libc6 #MINVER#
                 (symver)GLIBC_2.0 2.0
                 [...]
                 (symver)GLIBC_2.7 2.7
                 access@GLIBC_2.0 2.2
    
               All symbols associated with versions GLIBC_2.0 and GLIBC_2.7
               will lead to minimal version of 2.0 and 2.7 respectively with
               the exception of the symbol access@GLIBC_2.0.  The latter will
               lead to a minimal dependency on libc6 version 2.2 despite
               being in the scope of the "(symver)GLIBC_2.0" pattern because
               specific symbols take precedence over patterns.
    
               Please note that while old style wildcard patterns (denoted by
               "*@version" in the symbol name field) are still supported,
               they have been deprecated by new style syntax
               "(symver|optional)version".  For example, "*@GLIBC_2.0 2.0"
               should be written as "(symver|optional)GLIBC_2.0 2.0" if the
               same behavior is needed.
    
           **regex**
               Regular expression patterns are denoted by the _regex_ tag.
               They match by the perl regular expression specified in the
               symbol name field.  A regular expression is matched as it is,
               therefore do not forget to start it with the _^_ character or it
               may match any part of the real symbol _name@version_ string.
               For example:
    
                libdummy.so.1 libdummy1 #MINVER#
                 (regex)"^mystack_.*@Base$" 1.0
                 (regex|optional)"private" 1.0
    
               Symbols like "mystack_new@Base", "mystack_push@Base",
               "mystack_pop@Base", etc., will be matched by the first pattern
               while "ng_mystack_new@Base" would not.  The second pattern
               will match all symbols having the string "private" in their
               names and matches will inherit _optional_ tag from the pattern.
    
           Basic patterns listed above can be combined where it makes sense.
           In that case, they are processed in the order in which the tags
           are specified.  For example, both:
    
             (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
             (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
    
           will match symbols "_ZN3NSA6ClassA7Private11privmethod1Ei@Base"
           and "_ZN3NSA6ClassA7Private11privmethod2Ei@Base".  When matching
           the first pattern, the raw symbol is first demangled as C++
           symbol, then the demangled name is matched against the regular
           expression.  On the other hand, when matching the second pattern,
           regular expression is matched against the raw symbol name, then
           the symbol is tested if it is C++ one by attempting to demangle
           it.  A failure of any basic pattern will result in the failure of
           the whole pattern.  Therefore, for example,
           "__N3NSA6ClassA7Private11privmethod\dEi@Base" will not match
           either of the patterns because it is not a valid C++ symbol.
    
           In general, all patterns are divided into two groups: aliases
           (basic _c++_ and _symver_) and generic patterns (_regex_ , all
           combinations of multiple basic patterns).  Matching of basic
           alias-based patterns is fast (O(1)) while generic patterns are
           O(N) (N - generic pattern count) for each symbol.  Therefore, it
           is recommended not to overuse generic patterns.
    
           When multiple patterns match the same real symbol, aliases (first
           _c++_ , then _symver_) are preferred over generic patterns.  Generic
           patterns are matched in the order they are found in the symbol
           file template until the first success.  Please note, however, that
           manual reordering of template file entries is not recommended
           because **dpkg-gensymbols** generates diffs based on the
           alphanumerical order of their names.
    
       **Using includes**
           When the set of exported symbols differ between architectures, it
           may become inefficient to use a single symbol file.  In those
           cases, an include directive may prove to be useful in a couple of
           ways:
    
           •   You can factorize the common part in some external file and
               include that file in your _package_.symbols._arch_ file by using
               an include directive like this:
    
                #include "I<packages>.symbols.common"
    
           •   The include directive may also be tagged like any symbol:
    
                (tag|...|tagN)#include "file-to-include"
    
               As a result, all symbols included from _file-to-include_ will be
               considered to be tagged with _tag_ ... _tagN_ by default.  You can
               use this feature to create a common _package_.symbols file which
               includes architecture specific symbol files:
    
                 common_symbol1@Base 1.0
                (arch-bits=64)#include "package.symbols.64-bit"
                (arch-bits=32)#include "package.symbols.32-bit"
                 common_symbol2@Base 1.0
    
           The symbols files are read line by line, and include directives
           are processed as soon as they are encountered.  This means that
           the content of the included file can override any content that
           appeared before the include directive and that any content after
           the directive can override anything contained in the included
           file.  Any symbol (or even another #include directive) in the
           included file can specify additional tags or override values of
           the inherited tags in its tag specification.  However, there is no
           way for the symbol to remove any of the inherited tags.
    
           An included file can repeat the header line containing the SONAME
           of the library.  In that case, it overrides any header line
           previously read.  However, in general it's best to avoid
           duplicating header lines.  One way to do it is the following:
    
            #include "libsomething1.symbols.common"
             arch_specific_symbol@Base 1.0
    


* * *