Provided by: dpkg-dev_1.22.6ubuntu6.1_all bug

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 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

       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 KennzeichenKennzeichenN 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.64-bit"
            (arch=!amd64 !ia64 !alpha)#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-2023 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.

1.22.6                                             2024-07-17                                 deb-src-symbols(5)