Provided by: dpkg-dev_1.21.1ubuntu2.3_all 
NAAM
deb-src-symbols - Uitgebreid sjabloonbestand van Debian voor gedeelde bibliotheken
OVERZICHT
debian/pakket.symbols.arch, debian/symbols.arch, debian/pakket.symbols, debian/symbols
BESCHRIJVING
De symboolbestand-sjablonen worden geleverd met Debian bronpakketten en de indeling ervan is een
superverzameling van de symboolbestanden, geleverd in binaire pakketten, zie deb-symbols(5).
Commentaar
Commentaar wordt ondersteund in sjabloonsymboolbestanden. Elke regel met ‘#’ als eerste teken is een
commentaarregel, behalve als die regel begint met ‘#include’ (zie het onderdeel over Het gebruik van
includes). Regels die beginnen met ‘#MISSING:’ zijn een bijzondere vorm van commentaar waarin symbolen
die verdwenen zijn, gedocumenteerd worden.
Substitutie van #PACKAGE# gebruiken
In enkele zeldzame gevallen verschilt de naam van de bibliotheek naargelang de architectuur. Om de naam
van het pakket niet rechtstreeks in het symboolbestand te moeten inschrijven, kunt u gebruik maken van de
marker #PACKAGE#. Die zal tijdens de installatie van de symboolbestanden vervangen worden door de echte
pakketnaam. In tegenstelling tot de marker #MINVER#, zal #PACKAGE# nooit te vinden zijn in een
symboolbestand binnenin een binair pakket.
Symbooltags gebruiken
Het gebruik van symbooltags is nuttig om symbolen te markeren die op een of andere manier bijzonder zijn.
Aan elk symbool kan een arbitrair aantal tags gekoppeld worden. Hoewel alle tags ontleed en opgeslagen
worden, worden slechts een aantal ervan herkend door dpkg-gensymbols. Ze lokken een speciale behandeling
van de symbolen uit. Zie het onderdeel Standaard symbooltags voor een voorstelling van deze tags.
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 getagd en aangehaald symbool genoemd en heeft twee tags: tag1
met als waarde ik werd gemarkeerd en tagnaam met spatie die geen waarde heeft. Het tweede symbool met als
naam getagd_niet-aangehaald_symbool werd enkel gemarkeerd met de tag die 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 symboolbestanden die in broncodepakketten gebruikt worden (die bestanden moeten dan gezien worden
als sjablonen die gebruikt worden om de symboolbestanden te bouwen die in de binaire pakketten zitten).
Indien dpkg-gensymbols aangeroepen wordt zonder de optie -t zal het symboolbestanden 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.
Standaard symbooltags
optional
Een symbool dat als optional (facultatief) gemarkeerd is, kan om het even wanneer uit de bibliotheek
verdwijnen en dat feit zal nooit een mislukking van dpkg-gensymbols tot gevolg hebben. Nochtans
zullen verdwenen facultatieve symbolen permanent als MISSING (ontbrekend) aangegeven worden in de
diff (weergave van de veranderingen) bij elke nieuwe pakketrevisie. Dit gedrag dient als een
geheugensteuntje voor de onderhouder dat een dergelijk symbool verwijderd moet worden uit het
symboolbestand of terug toegevoegd aan de bibliotheek. Indien een facultatief symbool dat eerder als
MISSING opgetekend stond in een volgende revisie plots opnieuw terug opduikt, zal het terug
opgewaardeerd worden naar de status “existing” (bestaand) zonder wijziging van zijn minimumversie.
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.
arch=architectuurlijst
arch-bits=architectuur-bits
arch-endian=architectuur-endianness
Deze tags laten iemand toe om de set architecturen waarvoor het symbool verondersteld wordt te
bestaan, te beperken. De tags arch-bits en arch-endian worden sinds dpkg 1.18.0 ondersteund. Als de
symbolenlijst bijgewerkt wordt met de symbolen die in de bibliotheek gevonden worden, worden alle
architectuurspecifieke symbolen die van geen belang zijn voor de huidige hostarchitectuur, behandeld
alsof ze niet bestaan. Indien een architectuurspecifiek symbool dat betrekking heeft op de huidige
hostarchitectuur, ontbreekt in de bibliotheek, zijn de normale procedures die gelden voor ontbrekende
symbolen, van toepassing en dit kan het mislukken van dpkg-gensymbols tot gevolg hebben. Anderzijds,
indien het architectuurspecifieke symbool aangetroffen wordt als het er niet verondersteld wordt te
zijn (omdat de huidige hostarchitectuur niet vermeld wordt in de tag of niet overeenkomt met de
endianness of de bits), dan wordt het architectuurneutraal gemaakt (d.w.z. dat de tags arch, arch-
bits en arch-endian weggelaten worden en het symbool omwille van deze verandering in de diff
(weergave van de veranderingen) opgenomen zal worden), maar het wordt niet als nieuw beschouwd.
Als in de standaardmodus (niet-sjabloonmodus) gewerkt wordt, worden van de architectuurspecifieke
symbolen enkel die in het symboolbestand 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
symboolbestand.
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 architectuur-bits is ofwel 32 of 64.
(arch-bits=32)32bits_specifiek_symbool@Base 1.0
(arch-bits=64)64bits_specifiek_symbool@Base 1.0
De waarde van architectuur-endianness is ofwel little of 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)32bit_le_symbool@Base 1.0
allow-internal
dpkg-gensymbols hanteert een lijst van interne symbolen die niet zouden mogen voorkomen in
symboolbestanden 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 symboolbestand, moet u het symbool markeren met de tag
allow-internal. Dit kan nodig zijn voor sommige gereedschapskistbibliotheken van lagere orde zoals
“libgcc”.
ignore-blacklist
Een verouderde alias voor allow-internal (sinds dpkg 1.20.1, ondersteund sinds dpkg 1.15.3).
c++ Geeft een c++-symboolpatroon aan. Zie hierna in de subsectie Het gebruik van symboolpatronen.
symver
Geeft een symver (symboolversie) symboolpatroon aan. Zie hierna in de subsectie Het gebruik van
symboolpatronen.
regex
Geeft een regex-symboolpatroon aan. Zie hierna in de subsectie Het gebruik van symboolpatronen.
Het gebruik van symboolpatronen
Anders dan een standaardbeschrijving van een symbool, kan een patroon meerdere echte symbolen uit de
bibliotheek dekken. dpkg-gensymbols zal proberen om elk patroon te vergelijken met elk reëel symbool
waarvoor in het symboolbestand geen specifiek symbooltegenhanger gedefinieerd werd. Telkens wanneer een
eerste overeenkomst met een patroon gevonden wordt, worden alle tags en eigenschappen ervan gebruikt als
basisspecificatie voor het symbool. Indien er met geen enkel patroon een overeenkomst gevonden wordt, zal
het symbool als nieuw beschouwd worden.
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
symboolbestand-sjablonen. 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:
c++ Dit patroon wordt met de tag c++ aangeduid. Het zoekt enkel een overeenkomst met C++-symbolen aan de
hand van hun ontwarde (demangled) symboolnaam (zoals die weergegeven wordt door het hulpprogramma
c++filt(1)). Dit patroon is zeer handig om symbolen te vinden waarvan de verhaspelde naam op
verschillende architecturen anders kan zijn, terwijl hun ontwarde naam gelijk blijft. Een groep van
dergelijke symbolen is non-virtual thunks die architectuurspecifieke geheugenplaatsen ingebed hebben
in hun verhaspelde naam. Een courant voorkomend voorbeeld hiervan is een virtuele destructor die
onder een diamantovererving een niet-virtueel thunk-symbool nodig heeft. Bijvoorbeeld, zelfs als
_ZThn8_N3NSB6ClassDD1Ev@Base op 32-bits-architecturen wellicht _ZThn16_N3NSB6ClassDD1Ev@Base zal zijn
op 64-bits-architecturen, kunnen zij met één enkel c++-patroon aangeduid worden:
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 symboolbestand.
symver
Dit patroon wordt door de tag symver aangegeven. Goed onderhouden bibliotheken hebben symbolen met
versienummers, waarbij elke versie overeenkomt met de toeleveraarsversie waar het symbool toegevoegd
werd. Indien dat het geval is, kunt u een symver-patroon gebruiken om eventuele symbolen aan te
duiden die gekoppeld zijn aan de specifieke versie. Bijvoorbeeld:
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".
regex
Patronen in de vorm van reguliere expressies worden aangegeven met de tag regex. Zij zoeken naar een
overeenkomst met de in het veld symboolnaam vermelde perl reguliere expressie. Een reguliere
expressie wordt als zodanig vergeleken. Daarom mag u niet vergeten ze te laten beginnen met het teken
^. Anders kan ze een overeenkomst opleveren met om het even welk deel van de tekenreeks naam@versie
van het echte symbool. Bijvoorbeeld:
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 symboolbestand-sjabloon 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.
Het gebruik van includes
Als de set van geëxporteerde symbolen onderling verschilt tussen verschillende architecturen, kan het
inefficiënt worden om één enkel symboolbestand te gebruiken. In die gevallen kan een include-opdracht op
een aantal wijzen nuttig blijken:
• U kunt het gemeenschappelijke gedeelte afsplitsen in een extern bestand en dat bestand opnemen in uw
bestand pakket.symbols.arch met behulp van een include-opdracht op de volgende manier:
#include "I<pakketten>.symbols.common"
• Net zoals om het even welk symbool kan ook een include-opdracht tags krijgen:
(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
symboolbestanden 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
De symboolbestanden 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
ZIE OOK
deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).
1.21.1 2024-02-23 deb-src-symbols(5)