Kennzeichnungsspezifikationen kommen direkt vor dem Symbolnamen (dazwischen sind keine Leerraumzeichen erlaubt). Sie beginnen immer mit einer öffnenden Klammer (, enden mit einer schließenden Klammer ) und müssen mindestens eine Kennzeichnung enthalten. Mehrere Kennzeichnungen werden durch das Zeichen | getrennt. Jede der Kennzeichnungen kann optional einen Wert enthalten, der von der Kennzeichnung durch das Zeichen = getrennt wird. Kennzeichennamen und -werte können beliebige Zeichenketten sein, sie dürfen allerdings keine der der besonderen Zeichen ) | = enthalten. Symbolnamen, die einer Kennzeichnungsspezifikation folgen, können optional mit den Zeichen ' oder " zitiert werden, um Leerraumzeichen darin zu erlauben. Falls keine Kennzeichnungen für das Symbol spezifiziert sind, werden Anführungszeichen als Teil des Symbolnamens behandelt, der bis zum ersten Leerzeichen geht.
(Kennz1=bin markiert|Name mit Leerraum)"zitiertes gekennz Symbol"@Base 1.0 (optional)gekennzeichnet_unzitiertes_Symbol@Base 1.0 1 ungekennzeichnetes_Symbol@Base 1.0 Das erste Symbol im Beispiel heißt I<zitiertes gekennz Symbol> und hat zwei Kennzeichnungen: I<Kennz1> mit dem Wert I<bin markiert> und I<Name mit Leerraum> ohne Wert. Das zweite Symbol heißt I<gekennzeichnet_unzitiertes_Symbol> und ist nur mit dem Kennzeichen namens I<optional> gekennzeichnet. Das letzte Symbol ist ein Beispiel eines normalen, nicht gekennzeichneten Symbols.
Da Symbolkennzeichnungen eine Erweiterung des Formats deb-symbols(5) sind, können sie nur Teil der in Quellpaketen verwandten Symboldateien sein (diese Dateien sollten dann als Vorlagen zum Bau der Symboldateien, die in Binärpakete eingebettet werden, gesehen werden). Wenn dpkg-gensymbols ohne die Option -t aufgerufen wird, wird es alle Symbole ausgeben, die zum Format deb-symbols(5) kompatibel sind: Es verarbeitet die Symbole entsprechend der Anforderungen ihrer Standardkennzeichnungen und entfernt alle Kennzeichnungen aus der Ausgabe. Im Gegensatz dazu werden alle Symbole und ihre Kennzeichnungen (sowohl die Standardkennzeichnungen als auch die unbekannten) im Vorlagenmodus (-t) in der Ausgabe beibehalten und in ihrer Originalform, wie sie geladen wurden, auch geschrieben.
Diese Markierung ist für private Symbole nützlich, deren Verschwinden keinen ABI-Bruch auslöst. Beispielsweise fallen die meisten C++-Template-Instanziierungen in diese Kategorie. Wie jede andere Markierung kann auch diese einen beliebigen Wert haben: sie könnte angeben, warum dieses Symbol als optional betrachtet wird.
Beim Betrieb im standardmäßigen nicht-Vorlagen-Modus werden unter den architekturspezifischen Symbolen nur die in die Symboldatei geschrieben, die auf die aktuelle Host-Architektur passen. Auf der anderen Seite werden beim Betrieb im Vorlagenmodus alle architekturspezifischen Symbole (darunter auch die von fremden Architekturen) immer in die Symboldatei geschrieben.
Das Format der Architekturliste ist das gleiche wie das des Feldes Build-Depends in debian/control (außer den einschließenden eckigen Klammern []). Beispielsweise wird das erste Symbol aus der folgenden Liste nur auf den Architekturen Alpha, Any-amd64 und Ia64 betrachtet, das zweite nur auf Linux-Architekturen, während das dritte überall außer auf Armel betrachtet wird.
(arch=alpha any-amd64 ia64)64_Bit_spezifisches_Symbol@Base 1.0 (arch=linux-any)Linux_spezifisches_Symbol@Base 1.0 (arch=!armel)Symbol_das_Armel_nicht_hat@Base 1.0
Architektur-Bits ist entweder 32 oder 64.
(arch-bits=32)32_Bit_spezifisches_Symbol@Base 1.0 (arch-bits=64)64_Bit_spezifisches_Symbol@Base 1.0
Architektur-Bytereihenfolge ist entweder little oder big.
(arch-endian=little)Little_Endian_spezifisches_Symbol@Base 1.0 (arch-endian=big)Big_Endian_spezifisches_Symbol@Base 1.0
Mehrere Einschränkungen können aneinandergehängt werden.
(arch-bits=32|arch-endian=little)32_Bit_Le_Symbol@Base 1.0
Ein Muster wird als verloren betrachtet, falls es auf kein Symbol in der Bibliothek passt. Standardmäßig wird dies ein Versagen von dpkg-gensymbols in der Stufe -c1 oder höher auslösen. Falls der Fehlschlag allerdings unerwünscht ist, kann das Muster mit der Kennzeichnung optional markiert werden. Falls das Muster dann auf nichts passt, wird es im Diff nur als MISSING (fehlend) auftauchen. Desweiteren kann das Muster wie jedes Symbol auf die spezielle Architektur mit der Kennzeichnung arch beschränkt werden. Bitte lesen Sie den Unterabschnitt Standard-Symbolkennzeichnungen oben für weitere Informationen.
Muster sind eine Erweiterung des Formats deb-symbols(5); sie sind daher nur in Symboldatei-Vorlagen gültig. Die Musterspezifikationssyntax unterscheidet sich nicht von der eines spezifischen Symbols. Allerdings dient der Symbolnamenteil der Spezifikation als Ausdruck, der gegen Name@Version eines realen Symbols abgeglichen wird. Um zwischen den verschiedenen Mustertypen zu unterscheiden, wird es typischerweise mit einer speziellen Kennzeichnung gekennzeichnet.
Derzeit unterstützt dpkg-gensymbols drei grundlegene Mustertypen:
libdummy.so.1 libdummy1 #MINVER# […] (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0 […]
Der entworrene Name oben kann durch Ausführung folgenden Befehls erhalten werden:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Bitte beachten Sie, dass per Definition zwar der verworrene Name in der Bibliothek eindeutig ist, die aber nicht notwendigerweise für die entworrenen Namen zutrifft. Ein Satz von unterschiedlichen realen Symbolen können den gleichen entworrenen Namen haben. Beispielsweise ist das der Fall bei nicht-virtuellen Thunk-Symbolen in komplexen Vererbungskonfigurationen oder bei den meisten Konstruktoren und Destruktoren (da g++ typischerweise zwei reale Symbole für sie generiert). Da diese Kollisionen aber auf dem ABI-Niveau passieren, sollten sie nicht die Qualität der Symboldatei reduzieren.
libc.so.6 libc6 #MINVER# (symver)GLIBC_2.0 2.0 […] (symver)GLIBC_2.7 2.7 access@GLIBC_2.0 2.2
Alle den Versionen GLIBC_2.0 und GLIBC_2.7 zugeordneten Symbole werden zu einer minimalen Version 2.0 bzw. 2.7 führen, wobei das Symbol access@GLIBC_2.0 die Ausnahme darstellt. Es wird zu einer minimalen Abhängigkeit auf libc6 Version 2.2 führen, obwohl es im Geltungsbereich des Musters Bq(symver)GLIBC_2.0" gehört, da spezielle Symbole vor Mustern Vorrang haben.
Bitte beachten Sie, dass Platzhaltermuster im alten Format (angezeigt durch Bq*@version" im Symbolnamenfeld) zwar noch unterstützt werden, sie aber durch die Syntax im neuen Format Bq(symver|optional)version" abgelöst wurden. Beispielsweise sollte Bq*@GLIBC_2.0 2.0" als Bq(symver|optional)GLIBC_2.0 2.0" geschrieben werden, falls das gleiche Verhalten benötigt wird.
libdummy.so.1 libdummy1 #MINVER# (regex)"^mystack_.*@Base$" 1.0 (regex|optional)"private" 1.0
Symbole wie Bqmystack_new@Base", Bqmystack_push@Base", Bqmystack_pop@Base" usw. passen auf das erste Muster, während dies z.B. für Bqng_mystack_new@Base" nicht der Fall ist. Das zweite Muster wird auf alle Symbole, die die Zeichenkette Bqprivate" in ihren Namen enthalten, passen und die abgeglichenen Symbole erben die Kennzeichnung optional vom Muster.
Die oben aufgeführten grundlegenden Muster können - wo es Sinn ergibt - kombiniert werden. In diesem Fall werden sie in der Reihenfolge verarbeitet, in der die Kennzeichnungen angegeben sind. Im Beispiel
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0 (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
werden die Symbole Bq_ZN3NSA6ClassA7Private11privmethod1Ei@Base" und Bq_ZN3NSA6ClassA7Private11privmethod2Ei@Base" verglichen. Beim Vergleichen des ersten Musters wird das rohe Symbol erst als C++-Symbol entworren, dann wird der entworrene Name mit den regulären Ausdruck verglichen. Auf der anderen Seite wird beim Vergleichen des zweiten Musters der reguläre Ausdruck gegen den rohen Symbolnamen verglichen, dann wird das Symbol überprüft, ob es ein C++-Symbol ist, indem das Entwirren versucht wird. Ein Fehlschlag eines einfachen Musters wird zum Fehlschlag des gesamten Musters führen. Daher wird beispielsweise Bq__N3NSA6ClassA7Private11privmethod\dEi@Base" auf keines der Muster passen, da es kein gültiges C++-Symbol ist.
Im Allgemeinen werden die Muster in zwei Kategorien eingeteilt: Aliase (grundlegende c++- und symver-Muster) und generische Muster (regex und alle Kombinationen grundlegender Muster). Abgleichen von grundlegenden alias-basierenden Mustern ist schnell (O(1)), während generische Muster O(N) (wobei N die Anzahl der generischen Muster ist) für jedes Symbol ist. Daher wird empfohlen, generische Muster nicht zu viel zu verwenden.
Wenn mehrere Muster auf das gleiche Symbol passen, werden Aliase (zuerst c++, dann symver) gegenüber den generischen Mustern bevorzugt. Generische Muster werden in der Reihenfolge, in der sie in der Symboldateivorlage gefunden werden, verglichen, bis zum ersten Erfolg. Beachten Sie aber, dass das manuelle Anordnen der Vorlagendateieinträge nicht empfohlen wird, da dpkg-gensymbols Diffs basierend auf der alphanumerischen Reihenfolge ihrer Namen erstellt.
#include "I<Pakete>.symbols.common"
(Kennzeichen|…|KennzeichenN)#include "einzubindende-Datei"
Als Ergebnis werden alle Symbole aus der einzubindende-Datei standardmäßig als mit Kennzeichen … KennzeichenN gekennzeichnet betrachtet. Sie können diese Funktionalität benutzen, um eine gemeinsame Datei Paket.symbols zu erstellen, die architekturspezifische Symboldateien einbindet:
gemeinsames_Symbol1@Base 1.0 (arch=amd64 ia64 alpha)#include "Paket.symbols.64bit" (arch=!amd64 !ia64 !alpha)#include "Paket.symbols.32bit" gemeinsames_Symbol2@Base 1.0
Die Symboldateien werden Zeile für Zeile gelesen und include-Direktiven werden bearbeitet, sobald sie erkannt werden. Das bedeutet, dass der Inhalt der mit include eingebundenen Datei jeden Inhalt überschreiben kann, der vor der Include-Direktive aufgetaucht ist und Inhalt nach der Direktive alles aus der eingebundenen Datei überschreiben kann. Jedes Symbol (oder sogar weitere #include-Direktiven) in der eingebundenen Datei kann zusätzliche Kennzeichnungen spezifizieren oder Werte der vererbten Kennzeichnungen in ihrer Kennzeichnungsspezifikation überschreiben. Allerdings gibt es keine Möglichkeit für ein Symbol, die ererbten Kennzeichnungen zu überschreiben.
Eine eingebundene Datei kann die Kopfzeile wiederholen, die den SONAME der Bibliothek enthält. In diesem Fall überschreibt sie jede vorher gelesene Kopfzeile. Allerdings ist es im Allgemeinen am besten, die Wiederholung von Kopfzeilen zu vermeiden. Eine Art, dies zu erreichen, ist wie folgt:
#include "libirgendwas1.symbols.common" arch_spezifisches_Symbol@Base 1.0