{
    "mode": "man",
    "parameter": "deb-src-symbols",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/deb-src-symbols/5/json",
    "generated": "2026-10-09T17:03:58Z",
    "synopsis": "debian/package.symbols.arch, debian/symbols.arch, debian/package.symbols, debian/symbols",
    "sections": {
        "NAME": {
            "content": "deb-src-symbols - Debian's extended shared library template file\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "debian/package.symbols.arch, debian/symbols.arch, debian/package.symbols, debian/symbols\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The symbol file templates are shipped in Debian source packages, and its format is a superset\nof the symbols files shipped in binary packages, see deb-symbols(5).\n",
            "subsections": [
                {
                    "name": "Comments",
                    "content": "Comments are supported in template symbol files.  Any line with ‘#’ as the first character is\na comment except if it starts with ‘#include’ (see section \"Using includes\").  Lines starting\nwith ‘#MISSING:’ are special comments documenting symbols that have disappeared.\n"
                },
                {
                    "name": "Using #PACKAGE# substitution",
                    "content": "In some rare cases, the name of the library varies between architectures.  To avoid\nhardcoding the name of the package in the symbols file, you can use the marker #PACKAGE#.  It\nwill be replaced by the real package name during installation of the symbols files.  Contrary\nto the #MINVER# marker, #PACKAGE# will never appear in a symbols file inside a binary\npackage.\n"
                },
                {
                    "name": "Using symbol tags",
                    "content": "Symbol tagging is useful for marking symbols that are special in some way.  Any symbol can\nhave an arbitrary number of tags associated with it.  While all tags are parsed and stored,\nonly some of them are understood by dpkg-gensymbols and trigger special handling of the\nsymbols.  See subsection \"Standard symbol tags\" for reference of these tags.\n\nTag specification comes right before the symbol name (no whitespace is allowed in between).\nIt always starts with an opening bracket (, ends with a closing bracket ) and must contain at\nleast one tag.  Multiple tags are separated by the | character.  Each tag can optionally have\na value which is separated form the tag name by the = character.  Tag names and values can be\narbitrary strings except they cannot contain any of the special ) | = characters.  Symbol\nnames following a tag specification can optionally be quoted with either ' or \" characters to\nallow whitespaces in them.  However, if there are no tags specified for the symbol, quotes\nare treated as part of the symbol name which continues up until the first space.\n\n(tag1=i am marked|tag name with space)\"tagged quoted symbol\"@Base 1.0\n(optional)taggedunquotedsymbol@Base 1.0 1\nuntaggedsymbol@Base 1.0\n\nThe first symbol in the example is named tagged quoted symbol and has two tags: tag1 with\nvalue i am marked and tag name with space that has no value.  The second symbol named\ntaggedunquotedsymbol is only tagged with the tag named optional.  The last symbol is an\nexample of the normal untagged symbol.\n\nSince symbol tags are an extension of the deb-symbols(5) format, they can only be part of the\nsymbols files used in source packages (those files should then be seen as templates used to\nbuild the symbols files that are embedded in binary packages).  When dpkg-gensymbols is\ncalled without the -t option, it will output symbols files compatible to the deb-symbols(5)\nformat: it fully processes symbols according to the requirements of their standard tags and\nstrips all tags from the output.  On the contrary, in template mode (-t) all symbols and\ntheir tags (both standard and unknown ones) are kept in the output and are written in their\noriginal form as they were loaded.\n"
                },
                {
                    "name": "Standard symbol tags",
                    "content": ""
                },
                {
                    "name": "optional",
                    "content": "A  symbol  marked  as  optional  can disappear from the library at any time and that will\nnever  cause  dpkg-gensymbols  to  fail.   However,  disappeared  optional  symbols  will\ncontinuously  appear  as MISSING in the diff in each new package revision.  This behavior\nserves as a reminder for the maintainer that such a symbol needs to be removed  from  the\nsymbol  file  or  readded to the library.  When the optional symbol, which was previously\ndeclared as MISSING, suddenly reappears in the next revision, it will be upgraded back to\nthe “existing” status with its minimum version unchanged.\n\nThis tag is useful for symbols which are private where their disappearance do  not  cause\nABI  breakage.  For example, most of C++ template instantiations fall into this category.\nLike any other tag, this one may also have an  arbitrary  value:  it  could  be  used  to\nindicate why the symbol is considered optional.\n\narch=architecture-list\narch-bits=architecture-bits\narch-endian=architecture-endianness\nThese tags allow one to restrict the set of architectures where the symbol is supposed to\nexist.   The  arch-bits  and  arch-endian tags are supported since dpkg 1.18.0.  When the\nsymbols list is updated with the symbols discovered in  the  library,  all  arch-specific\nsymbols which do not concern the current host architecture are treated as if they did not\nexist.   If an arch-specific symbol matching the current host architecture does not exist\nin the library, normal procedures for missing  symbols  apply  and  it  may  cause  dpkg-\ngensymbols  to fail.  On the other hand, if the arch-specific symbol is found when it was\nnot supposed to exist (because the current host architecture is not listed in the tag  or\ndoes  not  match  the endianness and bits), it is made arch neutral (i.e. the arch, arch-\nbits and arch-endian tags are dropped and the symbol will appear in the diff due to  this\nchange), but it is not considered as new.\n\nWhen  operating  in the default non-template mode, among arch-specific symbols only those\nthat match the current host architecture  are  written  to  the  symbols  file.   On  the\ncontrary,  all  arch-specific  symbols  (including  those from foreign arches) are always\nwritten to the symbol file when operating in template mode.\n\nThe format of architecture-list is the same as the one used in the Build-Depends field of\ndebian/control (except the enclosing square brackets []).  For example, the first  symbol\nfrom  the  list below will be considered only on alpha, any-amd64 and ia64 architectures,\nthe second only on linux architectures, while the third one anywhere except on armel.\n\n(arch=alpha any-amd64 ia64)64bitspecificsymbol@Base 1.0\n(arch=linux-any)linuxspecificsymbol@Base 1.0\n(arch=!armel)symbolarmeldoesnothave@Base 1.0\n\nThe architecture-bits is either 32 or 64.\n\n(arch-bits=32)32bitspecificsymbol@Base 1.0\n(arch-bits=64)64bitspecificsymbol@Base 1.0\n\nThe architecture-endianness is either little or big.\n\n(arch-endian=little)littleendianspecificsymbol@Base 1.0\n(arch-endian=big)bigendianspecificsymbol@Base 1.0\n\nMultiple restrictions can be chained.\n\n(arch-bits=32|arch-endian=little)32bitlesymbol@Base 1.0\n"
                },
                {
                    "name": "allow-internal",
                    "content": "dpkg-gensymbols has a list of internal symbols that should not appear in symbols files as\nthey are usually only side-effects of implementation details of the toolchain (since dpkg\n1.20.1).  If for some reason, you really want one of those symbols to be included in  the\nsymbols  file,  you  should  tag the symbol with allow-internal.  It can be necessary for\nsome low level toolchain libraries like “libgcc”.\n"
                },
                {
                    "name": "ignore-blacklist",
                    "content": "A deprecated alias for allow-internal (since dpkg 1.20.1, supported since dpkg 1.15.3).\n\nc++ Denotes c++ symbol pattern.  See \"Using symbol patterns\" subsection below.\n"
                },
                {
                    "name": "symver",
                    "content": "Denotes symver (symbol version) symbol pattern.  See \"Using symbol  patterns\"  subsection\nbelow.\n"
                },
                {
                    "name": "regex",
                    "content": "Denotes regex symbol pattern.  See \"Using symbol patterns\" subsection below.\n"
                },
                {
                    "name": "Using symbol patterns",
                    "content": "Unlike  a  standard  symbol specification, a pattern may cover multiple real symbols from the\nlibrary.  dpkg-gensymbols will attempt to match each pattern against each  real  symbol  that\ndoes  not  have a specific symbol counterpart defined in the symbol file.  Whenever the first\nmatching pattern is found, all its tags and properties will be used as a basis  specification\nof the symbol.  If none of the patterns matches, the symbol will be considered as new.\n\nA pattern is considered lost if it does not match any symbol in the library.  By default this\nwill trigger a dpkg-gensymbols failure under -c1 or higher level.  However, if the failure is\nundesired,  the  pattern  may  be marked with the optional tag.  Then if the pattern does not\nmatch anything, it will only appear in the diff as MISSING.  Moreover, like any  symbol,  the\npattern  may  be  limited  to  the specific architectures with the arch tag.  Please refer to\n\"Standard symbol tags\" subsection above for more information.\n\nPatterns are an extension of the deb-symbols(5) format hence they are only  valid  in  symbol\nfile templates.  Pattern specification syntax is not any different from the one of a specific\nsymbol.  However, symbol name part of the specification serves as an expression to be matched\nagainst  name@version  of  the  real symbol.  In order to distinguish among different pattern\ntypes, a pattern will typically be tagged with a special tag.\n\nAt the moment, dpkg-gensymbols supports three basic pattern types:\n\nc++ This pattern is denoted by the c++ tag.  It matches only C++ symbols by  their  demangled\nsymbol  name (as emitted by c++filt(1) utility).  This pattern is very handy for matching\nsymbols which mangled  names  might  vary  across  different  architectures  while  their\ndemangled  names  remain the same.  One group of such symbols is non-virtual thunks which\nhave architecture specific offsets embedded in their mangled names.  A common instance of\nthis case is a virtual destructor which under diamond  inheritance  needs  a  non-virtual\nthunk  symbol.  For example, even if ZThn8N3NSB6ClassDD1Ev@Base on 32-bit architectures\nwill probably be ZThn16N3NSB6ClassDD1Ev@Base on 64-bit ones, it can be matched  with  a\nsingle c++ pattern:\n\nlibdummy.so.1 libdummy1 #MINVER#\n[...]\n(c++)\"non-virtual thunk to NSB::ClassD::~ClassD()@Base\" 1.0\n[...]\n\nThe demangled name above can be obtained by executing the following command:\n\n$ echo 'ZThn8N3NSB6ClassDD1Ev@Base' | c++filt\n\nPlease  note  that while mangled name is unique in the library by definition, this is not\nnecessarily true for demangled names.  A couple of distinct real  symbols  may  have  the\nsame  demangled  name.   For  example,  that's the case with non-virtual thunk symbols in\ncomplex inheritance configurations or with most constructors and destructors  (since  g++\ntypically  generates  two real symbols for them).  However, as these collisions happen on\nthe ABI level, they should not degrade quality of the symbol file.\n"
                },
                {
                    "name": "symver",
                    "content": "This pattern is denoted by the symver tag.   Well  maintained  libraries  have  versioned\nsymbols  where  each  version  corresponds  to  the upstream version where the symbol got\nadded.  If that's the case, you can use a symver pattern to match any  symbol  associated\nto the specific version.  For example:\n\nlibc.so.6 libc6 #MINVER#\n(symver)GLIBC2.0 2.0\n[...]\n(symver)GLIBC2.7 2.7\naccess@GLIBC2.0 2.2\n\nAll symbols associated with versions GLIBC2.0 and GLIBC2.7 will lead to minimal version\nof  2.0  and  2.7  respectively  with  the exception of the symbol access@GLIBC2.0.  The\nlatter will lead to a minimal dependency on libc6 version 2.2 despite being in the  scope\nof  the  \"(symver)GLIBC2.0\"  pattern  because  specific  symbols  take  precedence  over\npatterns.\n\nPlease note that while old style wildcard patterns (denoted by \"*@version\" in the  symbol\nname  field)  are  still  supported,  they  have  been  deprecated  by  new  style syntax\n\"(symver|optional)version\".   For  example,  \"*@GLIBC2.0  2.0\"  should  be  written   as\n\"(symver|optional)GLIBC2.0 2.0\" if the same behavior is needed.\n"
                },
                {
                    "name": "regex",
                    "content": "Regular expression patterns are denoted by the regex tag.  They match by the perl regular\nexpression specified in the symbol name field.  A regular expression is matched as it is,\ntherefore  do not forget to start it with the ^ character or it may match any part of the\nreal symbol name@version string.  For example:\n\nlibdummy.so.1 libdummy1 #MINVER#\n(regex)\"^mystack.*@Base$\" 1.0\n(regex|optional)\"private\" 1.0\n\nSymbols like \"mystacknew@Base\", \"mystackpush@Base\", \"mystackpop@Base\", etc.,  will  be\nmatched  by  the first pattern while \"ngmystacknew@Base\" would not.  The second pattern\nwill match all symbols having the string  \"private\"  in  their  names  and  matches  will\ninherit optional tag from the pattern.\n\nBasic  patterns  listed  above  can be combined where it makes sense.  In that case, they are\nprocessed in the order in which the tags are specified.  For example, both:\n\n(c++|regex)\"^NSA::ClassA::Private::privmethod\\d\\(int\\)@Base\" 1.0\n(regex|c++)N3NSA6ClassA7Private11privmethod\\dEi@Base 1.0\n\nwill       match       symbols        \"ZN3NSA6ClassA7Private11privmethod1Ei@Base\"        and\n\"ZN3NSA6ClassA7Private11privmethod2Ei@Base\".   When  matching  the  first  pattern,  the raw\nsymbol is first demangled as C++ symbol, then the  demangled  name  is  matched  against  the\nregular  expression.  On the other hand, when matching the second pattern, regular expression\nis matched against the raw symbol name, then the symbol  is  tested  if  it  is  C++  one  by\nattempting  to demangle it.  A failure of any basic pattern will result in the failure of the\nwhole pattern.  Therefore, for  example,  \"N3NSA6ClassA7Private11privmethod\\dEi@Base\"  will\nnot match either of the patterns because it is not a valid C++ symbol.\n\nIn  general,  all  patterns  are  divided into two groups: aliases (basic c++ and symver) and\ngeneric patterns (regex, all combinations of multiple basic  patterns).   Matching  of  basic\nalias-based  patterns  is  fast  (O(1))  while generic patterns are O(N) (N - generic pattern\ncount) for each symbol.  Therefore, it is recommended not to overuse generic patterns.\n\nWhen multiple patterns match the same real symbol,  aliases  (first  c++,  then  symver)  are\npreferred over generic patterns.  Generic patterns are matched in the order they are found in\nthe  symbol  file  template  until  the  first  success.   Please  note, however, that manual\nreordering of template file entries is  not  recommended  because  dpkg-gensymbols  generates\ndiffs based on the alphanumerical order of their names.\n"
                },
                {
                    "name": "Using includes",
                    "content": "When  the  set of exported symbols differ between architectures, it may become inefficient to\nuse a single symbol file.  In those cases, an include directive may prove to be useful  in  a\ncouple of ways:\n\n•   You  can  factorize  the  common part in some external file and include that file in your\npackage.symbols.arch file by using an include directive like this:\n\n#include \"I<packages>.symbols.common\"\n\n•   The include directive may also be tagged like any symbol:\n\n(tag|...|tagN)#include \"file-to-include\"\n\nAs a result, all symbols included from file-to-include will be considered  to  be  tagged\nwith   tag  ...  tagN  by  default.   You  can  use  this  feature  to  create  a  common\npackage.symbols file which includes architecture specific symbol files:\n\ncommonsymbol1@Base 1.0\n(arch=amd64 ia64 alpha)#include \"package.symbols.64-bit\"\n(arch=!amd64 !ia64 !alpha)#include \"package.symbols.32-bit\"\ncommonsymbol2@Base 1.0\n\nThe symbols files are read line by line, and include directives are processed as soon as they\nare encountered.  This means that the content of the included file can override  any  content\nthat  appeared  before  the  include  directive  and that any content after the directive can\noverride anything contained in the included file.   Any  symbol  (or  even  another  #include\ndirective)  in  the  included  file  can  specify  additional  tags or override values of the\ninherited tags in its tag specification.  However, there is no way for the symbol  to  remove\nany of the inherited tags.\n\nAn  included  file  can repeat the header line containing the SONAME of the library.  In that\ncase, it overrides any header line previously read.  However, in general it's best  to  avoid\nduplicating header lines.  One way to do it is the following:\n\n#include \"libsomething1.symbols.common\"\narchspecificsymbol@Base 1.0\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).\n\n1.22.6                                       2026-05-06                           deb-src-symbols(5)",
            "subsections": []
        }
    },
    "summary": "deb-src-symbols - Debian's extended shared library template file",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "deb-symbols",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/deb-symbols/5/json"
        },
        {
            "name": "dpkg-shlibdeps",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/dpkg-shlibdeps/1/json"
        },
        {
            "name": "dpkg-gensymbols",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/dpkg-gensymbols/1/json"
        }
    ]
}