Tags worden vlak voor de symboolnaam opgegeven (tussenin mag er geen witruimte zijn). Een opgave begint steeds met het openen van een haakje ( en eindigt met het sluiten ervan ) en moet minstens één tag bevatten. Meerdere tags worden onderling gescheiden door een |-teken. Elke tag kan een facultatieve waarde hebben die van de naam van de tag gescheiden wordt door het teken =. Namen van tags en waarden kunnen arbitraire tekenreeksen zijn, behalve dat zij niet de speciale tekens ) | = mogen bevatten. De symboolnaam die na een tagopgave komt kan facultatief tussen aanhalingstekens geplaatst worden, ofwel met ' of met ", waardoor hij witruimte mag bevatten. Evenwel, indien er voor het symbool geen tags opgegeven werden, zullen de aanhalingstekens behandeld worden als onderdeel van de naam van het symbool die eindigt bij de eerste spatie.
(tag1=ik werd gemarkeerd|tagnaam met spatie)"getagd aangehaald symbool"@Base 1.0 (optioneel)getagd_niet-aangehaald_symbool@Base 1.0 1 niet-getagd_symbool@Base 1.0 Het eerste symbool in het voorbeeld werd I<getagd en aangehaald symbool> genoemd en heeft twee tags: I<tag1> met als waarde I<ik werd gemarkeerd> en I<tagnaam met spatie> die geen waarde heeft. Het tweede symbool met als naam I<getagd_niet-aangehaald_symbool> werd enkel gemarkeerd met de tag die I<optioneel> als naam heeft. Het laatste symbool is een voorbeeld van een normaal niet-getagd symbool.
Aangezien symbooltags een uitbreiding zijn van het deb-symbols(5)-systeem, kunnen zij enkel deel uitmaken van de symbolenbestanden die in broncodepakketten gebruikt worden (die bestanden moeten dan gezien worden als sjablonen die gebruikt worden om de symbolenbestanden te bouwen die in de binaire pakketten zitten). Indien dpkg-gensymbols aangeroepen wordt zonder de optie -t zal het symbolenbestanden produceren die compatibel zijn met het deb-symbols(5)-systeem: er gebeurt een volledige verwerking van de symbolen in overeenstemming met de vereisten van hun standaardtags en de uitvoer wordt ontdaan van alle tags. In sjabloonmodus (-t) daarentegen blijven in de uitvoer alle symbolen en hun tags (zowel de standaardtags als de niet-gekende) behouden en worden ze in hun originele vorm neergeschreven zoals ze geladen werden.
Deze tag is nuttig voor private symbolen waarvan de verdwijning geen ABI-breuk veroorzaakt. De meeste van de C++-sjabloon-instantiaties vallen bijvoorbeeld onder deze categorie. Zoals elke andere tag kan ook deze een arbitraire waarde hebben: die kan gebruikt worden om aan te geven waarom het symbool als facultatief beschouwd wordt.
Als in de standaardmodus (niet-sjabloonmodus) gewerkt wordt, worden van de architectuurspecifieke symbolen enkel die in het symbolenbestand opgeschreven die overeenkomen met de huidige hostarchitectuur. Als daarentegen in de sjabloonmodus gewerkt wordt, worden steeds alle architectuurspecifieke symbolen (ook die voor vreemde architecturen) opgeschreven in het symbolenbestand.
De indeling voor de architectuurlijst is dezelfde als die welke gebruikt wordt voor het veld Build-Depends van debian/control (behalve de omsluitende vierkante haakjes []). Met het eerste symbool uit de onderstaande lijst zal bijvoorbeeld enkel rekening gehouden worden bij de architecturen alpha, any-amd64 en ia64, met het tweede enkel op linux-architecturen en met het derde overal behalve op armel.
(arch=alpha any-amd64 ia64)64bits_specifiek_symbool@Base 1.0 (arch=linux-any)linux_specifiek_symbool@Base 1.0 (arch=!armel)symbool_dat_armel_niet_heeft@Base 1.0 De waarde van I<architectuur-bits> is ofwel B<32> of B<64>. (arch-bits=32)32bits_specifiek_symbool@Base 1.0 (arch-bits=64)64bits_specifiek_symbool@Base 1.0 De waarde van I<architectuur-endianness> is ofwel B<little> of B<big>. (arch-endian=little)little_endian_specifiek_symbool@Base 1.0 (arch-endian=big)big_endian_specifiek_symbool@Base 1.0 Meerdere beperkingen kunnen aaneengeregen worden. (arch-bits=32|arch-endian=little)32bits_le_symbool@Base 1.0 =item B<allow-internal>
dpkg-gensymbols hanteert een lijst van interne symbolen die niet zouden mogen voorkomen in symbolenbestanden omdat ze gewoonlijk slechts een neveneffect zijn van details in de wijze waarop de gereedschapskist (toolchain) geïmplementeerd wordt. Indien u om een of andere reden echt wilt dat een van deze symbolen opgenomen wordt in het symbolenbestand, moet u het symbool markeren met de tag allow-internal. Dit kan nodig zijn voor sommige gereedschapskistbibliotheken van lagere orde zoals libgcc
Een patroon wordt als verloren beschouwd als het met geen enkel symbool uit de bibliotheek overeenkomt. Standaard zal dit onder -c1 of een hoger niveau een mislukking van dpkg-gensymbols uitlokken. Indien een dergelijke mislukking echter onwenselijk is, kan het patroon gemarkeerd worden met de tag optional. Als het patroon in dat geval geen overeenkomst oplevert, zal het enkel in de diff (weergave van de wijzigingen) als MISSING (ontbrekend) vermeld worden. Zoals elk ander symbool kan ook een patroon beperkt worden tot specifieke architecturen met de tag arch. Raadpleeg het onderdeel Standaard symbooltags hierboven voor meer informatie.
Patronen vormen een uitbreiding van het deb-symbols(5)-systeem en zijn daarom enkel geldig in symbolenbestandsjablonen. De syntaxis voor het opgeven van patronen verschilt niet van die voor een specifiek symbool. Het onderdeel symboolnaam van de specificatie fungeert echter als een expressie die vergeleken wordt met naam@versie van het echte symbool. Om het onderscheid te maken tussen verschillende types patronen, wordt een patroon doorgaans gemarkeerd met een speciale tag
Op dit ogenblik ondersteunt dpkg-gensymbols drie fundamentele patroontypes:
libdummy.so.1 libdummy1 #MINVER# [...] (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0 [...]
De bovenstaande ontwarde naam kan verkregen worden door het volgende commando uit te voeren:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Merk op dat een verhaspelde naam per definitie uniek is in de bibliotheek, maar dat dit niet noodzakelijk het geval is voor ontwarde namen. Een aantal verschillende echte symbolen kan dezelfde ontwarde naam hebben. Dat is bijvoorbeeld het geval met niet-virtuele thunk-symbolen in complexe overervingsconfiguraties of met de meeste constructors en destructors (vermits g++ voor hen doorgaans twee echte symbolen genereert). Vermits deze collisies zich op het ABI-niveau voordoen, verminderen zij evenwel niet de kwaliteit van het symbolenbestand.
libc.so.6 libc6 #MINVER# (symver)GLIBC_2.0 2.0 [...] (symver)GLIBC_2.7 2.7 access@GLIBC_2.0 2.2
Alle symbolen die horen bij de versies GLIBC_2.0 en GLIBC_2.7 zullen resulteren in de respectieve minimale versies 2.0 en 2.7, met uitzondering van het symbool access@GLIBC_2.0. Dit laatste zal resulteren in een minimale vereiste van libc6 versie 2.2 en dit ondanks het feit dat het valt binnen het bereik van het patroon ``(symver)GLIBC_2.0''. De reden hiervoor is dat specifieke symbolen voorrang hebben op patronen.
Merk op dat hoewel patronen met jokertekens volgens de oude stijl (in het veld symboolnaam aangegeven door ``*@version'') nog steeds ondersteund worden, zij vervangen werden door een syntaxis volgens de nieuwe stijl ``(symver|optional)version''. Als hetzelfde effect gewenst wordt moet bijvoorbeeld ``*@GLIBC_2.0 2.0'' geschreven worden als ``(symver|optional)GLIBC_2.0 2.0''.
libdummy.so.1 libdummy1 #MINVER# (regex)"^mystack_.*@Base$" 1.0 (regex|optional)"private" 1.0
Symbolen zoals ``mystack_new@Base'', ``mystack_push@Base'', ``mystack_pop@Base'' enz. zullen door het eerste patroon gevonden worden, terwijl ``ng_mystack_new@Base'' bijvoorbeeld niet. Het tweede patroon zal een overeenkomst opleveren met alle symbolen die in hun naam de tekenreeks ``private'' hebben en de gevonden symbolen zullen de tag optional overerven van het patroon.
De hierboven vermelde basispatronen kunnen met elkaar gecombineerd worden als dat zinvol is. In dat geval worden zij verwerkt in de volgorde waarin de tags opgegeven werden. Bijvoorbeeld, beide onderstaande patronen
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0 (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
zullen de symbolen ``_ZN3NSA6ClassA7Private11privmethod1Ei@Base'' en ``_ZN3NSA6ClassA7Private11privmethod2Ei@Base'' vinden. Bij het vergelijken met het eerste patroon wordt het rauwe symbool eerst ontward als een C++-symbool en vervolgens wordt de ontwarde naam vergeleken met de reguliere expressie. Bij het vergelijken met het tweede patroon daarentegen, wordt de reguliere expressie vergeleken met de rauwe symboolnaam en vervolgens wordt nagegaan of het een C++-symbool is door het te proberen ontwarren. Als een basispatroon een mislukking oplevert, betekent dit het mislukken van het hele patroon. Om die reden zal ``__N3NSA6ClassA7Private11privmethod\dEi@Base'' bijvoorbeeld met geen van beide patronen een overeenkomst opleveren, aangezien het geen geldig C++-symbool is.
Over het algemeen genomen kunnen alle patronen in twee groepen onderverdeeld worden: aliassen (basale c++- en symver-patronen) en generieke patronen (regex, alle combinaties van meerdere basale patronen). Het vergelijken met basale patronen van het alias-type verloopt snel (O(1)), terwijl dat bij generieke patronen voor elk symbool O(N) is (waarbij N het aantal generieke patronen is). Daarom wordt aangeraden om geen overdadig gebruik te maken van generieke patronen.
Indien meerdere patronen een overeenkomst opleveren met hetzelfde echte symbool, krijgen aliassen (eerst c++, dan symver) de voorkeur boven generieke patronen. Generieke patronen worden vergeleken in de volgorde waarin zij aangetroffen worden in het symbolenbestandsjabloon tot er een eerste succes volgt. Merk nochtans op dat het manueel herordenen van items uit het sjabloonbestand niet aangeraden wordt, aangezien dpkg-gensymbols diffs (weergave van de veranderingen) genereert op basis van de alfanumerieke volgorde van hun namen.
#include "I<pakketten>.symbols.common"
(tag|...|tagN)#include "in-te-voegen-bestand"
Als gevolg daarvan zal er standaard van uitgegaan worden dat alle symbolen die uit in-te-voegen-bestand opgenomen worden, gemarkeerd zijn met tag ... tagN. U kunt van deze functionaliteit gebruik maken om een gemeenschappelijk bestand pakket.symbols te maken waarin architectuurspecifieke symbolenbestanden opgenomen worden:
gemeenschappelijk_symbool1@Base 1.0 (arch=amd64 ia64 alpha)#include "pakket.symbols.64bit" (arch=!amd64 !ia64 !alpha)#include "pakket.symbols.32bit" gemeenschappelijk_symbool2@Base 1.0 =back
De symbolenbestanden worden regel per regel gelezen en include-opdrachten worden verwerkt van zodra ze tegengekomen worden. Dit betekent dat de inhoud van het ingevoegde bestand eventueel zaken kan vervangen die voor de include-opdracht stonden en dat zaken die na de opdracht komen, eventueel inhoud uit het ingevoegde bestand kunnen vervangen. Elk symbool (of zelfs een andere #include-opdracht) uit het ingevoegde bestand kan bijkomende tags opgeven of via zijn tag-vermeldingen waarden van de overgeërfde tags vervangen. Er bestaat nochtans geen manier waarop een symbool eventueel overgeërfde tags zou kunnen verwijderen.
Een ingevoegd bestand kan de kopregel die de SONAME van de bibliotheek bevat, herhalen. In dat geval vervangt het een eventueel eerder ingelezen kopregel. Het is over het algemeen nochtans best om het dupliceren van kopregels te vermijden. Een manier om dat te doen is de volgende:
#include "libding1.symbols.common" arch_specifiek_symbool@Base 1.0