Ubuntu Manpage: deb-symbols - Debians erweiterte Vorlagendatei für Laufzeitbibliotheken

bezeichnung
übersicht
beschreibung
siehe auch
übersetzung

Provided by: dpkg-dev_1.22.15ubuntu1_all

BEZEICHNUNG

       deb-symbols - Debians erweiterte Vorlagendatei für Laufzeitbibliotheken

ÜBERSICHT

       debian/Paket.symbols.Arch, debian/symbols.Arch, debian/Paket.symbols, debian/symbols

BESCHREIBUNG

Die Symboldateivorlagen werden in Debian-Quellpaketen ausgeliefert. Deren Format ist eine Obermenge der
in Binärpaketen ausgelieferten Symboldateien, siehe deb-symbols(5).

Kommentare
In Symboldateien werden Kommentare unterstützt. Jede Zeile, die mit ‚#’ als erstem Zeichen beginnt, ist
ein Kommentar, falls sie nicht mit ‚#include’ beginnt (siehe Abschnitt "Includes verwenden"). Zeilen, die
mit ‚#MISSING:’ anfangen, sind besondere Kommentare, die verschwundene Symbole dokumentieren.

Verwendung der #PACKAGE#-Ersetzung
In einigen seltenen Fällen sind die Namen der Bibliotheken nicht auf allen Architekturen gleich. Um zu
vermeiden, dass der Paketname in der Symboldatei fest kodiert wird, können Sie die Markierung #PACKAGE#
verwenden. Während der Installation der Symboldatei wird sie durch den echten Paketnamen ersetzt. Anders
als die Markierung #MINVER# wird #PACKAGE# nie in der Symboldatei innerhalb eines Binärpakets auftauchen.

Verwendung von Symbolkennzeichnungen
Symbolkennzeichnungen sind nützlich, um Symbole zu markieren, die in irgendeiner Weise besonders sind.
Jedes Symbol kann eine beliebige Anzahl zugeordneter Kennzeichnungen besitzen. Während alle
Kennzeichnungen ausgewertet und gespeichert werden, werden nur einige von dpkg-gensymbols verstanden und
lösen eine Spezialbehandlung der Symbole aus. Lesen Sie den Unterabschnitt
"Standardsymbolkennzeichnungen" für eine Referenz dieser Kennzeichnungen.

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.

Standard-Symbolkennzeichnungen
optional
Ein als „optional“ gekennzeichnetes Symbol kann jederzeit von der Bibliothek verschwinden und wird
nie zum Fehlschlag von dpkg-gensymbols führen. Verschwundene optionale Symbole werden kontinuierlich
als MISSING (Fehlend) in dem Diff in jeder neuen Paketversion auftauchen. Dieses Verhalten dient als
Erinnerung für den Betreuer, dass so ein Symbol aus der Symboldatei entfernt oder wieder der
Bibliothek hinzugefügt werden muss. Wenn das optionale Symbol, das bisher als MISSING angegeben
gewesen war, plötzlich in der nächsten Version wieder auftaucht, wird es wieder auf den Status
„existing“ (existierend) gebracht, wobei die minimale Version unverändert bleibt.

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.

arch=Architekturliste
arch-bits=Architektur-Bits
arch-endian=Architektur-Bytereihenfolge
Diese Markierungen erlauben es, den Satz an Architekturen einzugrenzen, auf denen das Symbol
existieren sollte. Die Markierungen arch-bits und arch-endian werden seit Dpkg 1.18.0 unterstützt.
Wenn die Symbolliste mit den in der Bibliothek entdeckten Symbolen aktualisiert wird, werden alle
architekturspezifischen Symbole, die nicht auf die aktuelle Host-Architektur passen, so behandelt,
als ob sie nicht existierten. Falls ein architekturspezifisches Symbol, das auf die aktuelle Host-
Architektur passt, in der Bibliothek nicht existiert, werden die normalen Regeln für fehlende Symbole
angewandt und dpkg-gensymbols könnte dadurch fehlschlagen. Auf der anderen Seite, falls das
architekturspezifische Symbol gefunden wurde, wenn es nicht existieren sollte (da die aktuelle Host-
Architektur nicht in der Markierung aufgeführt ist oder nicht auf die Bytereihenfolge und Bits
passt), wird sie architekturneutral gemacht (d.h. die Architektur-, Architektur-Bits- und
Architektur-Bytereihenfolgemarkierungen werden entfernt und das Symbol wird im Diff aufgrund dieser
Änderung auftauchen), aber es wird nicht als neu betrachtet.

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 Arm64, Any-amd64 und Riscv64 betrachtet, das zweite nur auf
Linux-Architekturen, während das dritte überall außer auf Armel betrachtet wird.

(arch=arm64 any-amd64 riscv64)Arch_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

allow-internal
dpkg-gensymbols verfügt über eine interne Liste von Symbolen, die nicht in Symboldateien auftauchen
sollten, da sie normalerweise nur Nebeneffekte von Implementierungsdetails in der Werkzeugkette
darstellen (seit Dpkg 1.20.1). Falls Sie aus irgendeinem Grund wollen, dass diese Symbole in der
Symboldatei aufgenommen werden, sollten Sie das Symbol mit allow-internal kennzeichnen. Dies kann für
einige grundlegende Bibliotheken der Werkzeugkette wie „libgcc“ notwendig sein.

ignore-blacklist
Ein veralteter Alias für allow-internal (seit Dpkg 1.20.1, unterstützt seit Dpkg 1.15.3).

c++ Gibt c++-Symbolmuster an. Lesen Sie den nachfolgenden Unterabschnitt "Verwendung von Symbolmustern".

symver
Gibt symver (Symbolversion)-Symbolmuster an. Lesen Sie den nachfolgenden Unterabschnitt "Verwendung
von Symbolmustern".

regex
Gibt regex-Symbolmuster an. Lesen Sie den nachfolgenden Unterabschnitt "Verwendung von
Symbolmustern".

Verwendung von Symbolmustern
Anders als die Standardsymbolspezifikation kann ein Muster mehrere reale Symbole aus der Bibliothek
abdecken. dpkg-gensymbols wird versuchen, jedes Muster auf jedes reale Symbol, für das kein spezifisches
Symbolgegenstück in der Symboldatei definiert ist, abzugleichen. Wann immer das erste passende Muster
gefunden wurde, werden alle Kennzeichnungen und Eigenschaften als Basisspezifikation des Symbols
verwandt. Falls keines der Muster passt, wird das Symbol als neu betrachtet.

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:

c++ Dieses Muster wird durch die Kennzeichnung c++ verzeichnet. Es passt nur auf die entworrenen
(„demangled“) Symbolnamen (wie sie vom Hilfswerkzeug c++filt(1) ausgegeben werden). Dieses Muster ist
sehr hilfreich, um auf Symbole zu passen, bei dem die verworrenen („mangled“) Namen sich auf
verschiedenen Architekturen unterscheiden während die entworrenen die gleichen bleiben. Eine Gruppe
solcher Symbole ist non-virtual thunks, die einen architekturspezifischen Versatz in ihren
verworrenen Namen eingebettet haben. Eine häufige Instanz dieses Falles ist ein virtueller
Destruktor, der unter rautenförmiger Vererbung ein nicht-virtuelles Thunk-Symbol benötigt. Selbst
wenn beispielsweise _ZThn8_N3NSB6ClassDD1Ev@Base auf 32 Bit-Architekturen
_ZThn16_N3NSB6ClassDD1Ev@Base auf 64 Bit-Architekturen ist, kann es mit einem einzigen c++-Muster
abgeglichen werden:

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.

symver
Dieses Muster wird durch die Kennzeichnung symver verzeichnet. Gut betreute Bibliotheken verfügen
über versionierte Symbole, wobei jede Version zu der Version der Originalautoren passt, in der dieses
Symbol hinzugefügt wurde. Falls das der Fall ist, können Sie ein symver-Muster verwenden, das auf
jedes zu einer spezifizierten Version zugehörige Symbol passt. Beispiel:

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
„(symver)GLIBC_2.0“ gehört, da spezielle Symbole vor Mustern Vorrang haben.

Bitte beachten Sie, dass Platzhaltermuster im alten Format (angezeigt durch „*@version“ im
Symbolnamenfeld) zwar noch unterstützt werden, sie aber durch die Syntax im neuen Format
„(symver|optional)version“ abgelöst wurden. Beispielsweise sollte „*@GLIBC_2.0 2.0“ als
„(symver|optional)GLIBC_2.0 2.0“ geschrieben werden, falls das gleiche Verhalten benötigt wird.

regex
Muster mit regulären Ausdrücken werden durch die Kennzeichnung regex verzeichnet. Sie passen auf den
regulären Ausdruck von Perl, der im Symbolnamenfeld angegeben ist. Ein regulärer Ausdruck wird wie er
ist abgeglichen. Denken Sie daher daran, ihn mit dem Zeichen ^ zu beginnen, da er ansonsten auf jeden
Teil der Zeichenkette des realen Symbols name@version passt. Beispiel:

libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0

Symbole wie „mystack_new@Base“, „mystack_push@Base“, „mystack_pop@Base“ usw. passen auf das erste
Muster, während dies für „ng_mystack_new@Base“ nicht der Fall ist. Das zweite Muster wird auf alle
Symbole, die die Zeichenkette „private“ 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 „_ZN3NSA6ClassA7Private11privmethod1Ei@Base“ und
„_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 „__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.

Includes verwenden
Wenn der Satz der exportierten Symbole sich zwischen Architekturen unterscheidet, kann es ineffizient
werden, eine einzige Symboldatei zu verwenden. In diesen Fällen kann sich eine Include-Direktive in einer
Reihe von Arten als nützlich erweisen:

• Sie können den gemeinsamen Teil in eine externe Datei auslagern und diese Datei dann in Ihre
Paket.symbols.Arch-Datei mit einer include-Direktive wie folgt einbinden:

#include "I<Pakete>.symbols.common"

• Die Include-Direktive kann auch wie jedes Symbol gekennzeichnet werden:

(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-bits=64)#include "Paket.symbols.64-bit"
(arch-bits=32)#include "Paket.symbols.32-bit"
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

SIEHE AUCH

       deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(1).

ÜBERSETZUNG

       Die deutsche Übersetzung wurde 2004, 2006-2025 von Helge Kreutzmann <debian@helgefjell.de>, 2007 von
       Florian Rehnisch <eixman@gmx.de> und 2008 von Sven Joachim <svenjoac@gmx.de> angefertigt. Diese
       Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 2 oder neuer für
       die Kopierbedingungen. Es gibt KEINE HAFTUNG.