Spezifikation der Funktion-Test-Makro-Anforderungen in Handbuchseiten

Wenn eine Funktion die Definition eines Feature-Test-Makros erfordert, enthält die ÜBERSICHT einer Handbuchseit in der Regel einen Vermerk der folgenden Form (dieses Beispiel finden Sie in der Handbuchseite von acct(2)):

Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

Das || bedeutet, dass zwecks Ermittlung der Deklaration von acct(2) aus <unistd.h> eine der beiden folgenden Makro-Definitionen vor dem Einfügen jeglicher Header-Dateien erfolgen muss:

#define _BSD_SOURCE
#define _XOPEN_SOURCE        /* oder jeder Wert < 500 */

Alternativ können gleichwertige Definitionen in den Kompilierbefehl eingebettet werden:

cc -D_BSD_SOURCE
cc -D_XOPEN_SOURCE           # Oder jeder Wert < 500

Beachten Sie, dass einige Feature-Test-Makros standardmäßig definiert sind. Daher ist es nicht immer erforderlich, die in der ÜBERSICHT angegebenen Feature-Test-Makro(s) explizit anzugeben.

In wenigen Fällen verwenden Handbuchseiten eine Abkürzung für die Anforderungen der Feature-Test-Makros (dieses Beispiel stammt aus readahead(2)):

#define _GNU_SOURCE
#include <fcntl.h>

ssize_t readahead(int fd, off64_t *offset, size_t count);

Dieses Format wird immer dann angewendet, wenn nur ein einziges Feature-Test-Makro die Verwendung der Funktions-Deklaration ermöglicht und das Makro nicht standardmäßig definiert wird.

Von Glibc »verstandene« Feature-Test-Makros

In den Absätzen weiter unten wird erläutert, wie Feature-Test-Makros in Linux-Glibc 2.x, x > 0, behandelt werden.

Zuerst eine Zusammenfassung einiger Details für den Ungeduldigen:

• In modernem Quellcode müssen Sie höchstwahrscheinlich _POSIX_C_SOURCE (für Definitionen aus verschiedenen Versionen von POSIX.1), _XOPEN_SOURCE (für Definitionen aus verschiedenen Versionen von SUS), _GNU_SOURCE (für GNU- und/oder Linux-spezifischem Zeug) und _DEFAULT_SOURCE (für normalerweise standardmäßig bereitgestellte Definitionen) verwenden.
• Bestimmte Makros sind mit Vorgabewerten definiert. Daher mag es nicht notwendig sein, sie explizit zu definieren, obwohl eine oder mehrere Makros in der ÜBERSICHT einer Handbuchseite als benötigt markiert sind. Die vollständigen Details der Vorgaben sind später in dieser Handbuchseite dargestellt.
• Die Definition von _XOPEN_SOURCE mit einem Wert von 600 oder mehr bewirkt den gleichen Effekt wie die Definition von _POSIX_C_SOURCE mit einem Wert von 200112L oder größer. Hierbei kann

_POSIX_C_SOURCE >= 200112L
    

in den Feature-Test-Makro-Anforderungen in der ÜBERSICHT einer Handbuchseite ist implizit angenommen, dass das Folgende den gleichen Effekt hat:

_XOPEN_SOURCE >= 600
    

*

Die Definition von _XOPEN_SOURCE mit einem Wert von 700 oder mehr bewirkt den gleichen Effekt wie die Definition von _POSIX_C_SOURCE mit einem Wert von 200809L oder größer. Hierbei kann

_POSIX_C_SOURCE >= 200809L
    

in den Feature-Test-Makro-Anforderungen in der ÜBERSICHT einer Handbuchseite ist implizit angenommen, dass das Folgende den gleichen Effekt hat:

_XOPEN_SOURCE >= 700
    

Die Linux-Glibc »versteht« die folgenden Feature-Test-Makros:

__STRICT_ANSI__

ISO Standard C. Dieses Makro wird impliziert definiert, wenn gcc(1) beispielsweise mit den Schaltern -std=c99 oder -ansi aufgerufen wird.

_POSIX_C_SOURCE

Mit der Definition dieses Makros stellen Header-Dateien Definitionen wie folgt bereit:

_POSIX_SOURCE

Die Definition dieses überholten Makros mit einem beliebigen Wert hat die gleiche Wirkung wie die Definition von _POSIX_C_SOURCE mit dem Wert 1.

Da dieses Makro veraltet ist, ist es im Allgemeinen nicht dokumentiert, wenn Feature-Test-Makro-Anforderungen in Handbuchseiten beschrieben werden.

_XOPEN_SOURCE

Mit der Definition dieses Makros stellen Header-Dateien Definitionen wie folgt bereit:

Falls __STRICT_ANSI__ nicht definiert ist oder _XOPEN_SOURCE mit einem Wert identisch zu oder größer als 500 und weder _POSIX_SOURCE noch _POSIX_C_SOURCE explizit definiert sind dann werden die folgenden Makros implizit definiert:

Zusätzlich bewirkt die Definition von _XOPEN_SOURCE mit einem Wert von 500 oder mehr den gleichen Effekt wie die Definition von _XOPEN_SOURCE_EXTENDED.

_XOPEN_SOURCE_EXTENDED

Wenn dieses Makro und _XOPEN_SOURCE definiert sind, dann werden Definitionen entsprechend den XPG4v2- (SUSv1-)UNIX-Erweiterungen (UNIX 95) aktiviert. Wird _XOPEN_SOURCE mit einem Wert von 500 oder mehr definiert, ist der Effekt identisch zur Definition von _XOPEN_SOURCE_EXTENDED. Der Einsatz von _XOPEN_SOURCE_EXTENDED in neuem Quellcode sollte vermieden werden.

Da die Definition von _XOPEN_SOURCE mit einem Wert von 500 oder mehr den gleichen Effekt wie die Definition von _XOPEN_SOURCE_EXTENDED hat, wird das letztere (veraltete) Makro im Allgemeinen in der ÜBERSICHT in Handbuchseiten nicht beschrieben.

_ISOC99_SOURCE (seit Glibc 2.1.3)

Aktiviert Deklarationen, die mit dem ISO-C99-Standard konsistent sind.

Frühere Glibc 2.1.x-Versionen verarbeiteten ein gleichwertiges Makro _ISOC9X_SOURCE (weil der C99-Standard noch nicht fertig war). Obwohl die Verwendung dieses Makros obsolet ist, wird es von der Glibc weiter zwecks Abwärtskompatibilität unterstützt.

Die Definition von _ISOC99_SOURCE aktiviert auch ISO C (1990) Anhang 1-Definitionen (»C95«). (Die hauptsächliche Änderung in C95 war die Unterstützung für internationale Zeichensätze.)

Der Aufruf des C-Compilers mit der Option -std=c99 bewirkt den gleichen Effekt wir die Definition dieses Makros.

_ISOC11_SOURCE (seit Glibc 2.16)

Aktiviert Deklarationen, die mit dem ISO-C11-Standard konsistent sind. Die Definition dieses Makros aktiviert auch C99- und C95-Funktionalitäten (wie _ISOC99_SOURCE).

Der Aufruf des C-Compilers mit der Option -std=c11 bewirkt den gleichen Effekt wie die Definition dieses Makros.

_LARGEFILE64_SOURCE

Aktiviert Definitionen für das durch LFS (Large File Summit) definierte alternative API als »Übergangserweiterungen« zu der »Single UNIX Specification«. (Siehe http://opengroup.org/platform/lfs.html.) Das alternative API besteht aus einer Reihe von neuen Objekten (d.h. Funktionen und Typen), deren Namen mit »64« endet (z. B. off64_t versus off_t, lseek64() versus lseek(), usw.). Neue Programme sollten dieses Makro nicht verwenden, sondern _FILE_OFFSET_BITS=64 einsetzen.

_LARGEFILE_SOURCE

Dieses Makro wurde traditionell verwandt, um bestimmte Funktionen (insbesondere fseeko(3) und ftello(3)) bereitzustellen, die sich um Beschränkungen älterer APIs (fseek(3) und ftell(3)) kümmerten, die long für Datei-Offsets verwandten. Dieses Makro ist implizit definiert, falls _XOPEN_SOURCE mit einem Wert gleich oder größer als 500 definiert ist. Neue Programme sollten dieses Makro nicht einsetzen; um das gleiche Ergebnis zu erhalten, ist der empfohlene Mechanismus, _XOPEN_SOURCE wie gerade beschrieben oder _FILE_OFFSET_BITS mit einem Wert von 64 zu definieren.

_FILE_OFFSET_BITS

Wird diesem Makro der Wert 64 zugewiesen, werden automatisch Verweise auf 32-Bit-Funktionen und -Datentypen für Datei-Ein/Ausgabe und Dateisystem-Operationen in Verweise auf ihre 64-Bit-Pendants konvertiert. Dies ist für die Ein-/Ausgabe in und aus großen Dateien (> 2 Gigabyte) auf 32-Bit-Systemen nützlich. (Mit der Definition dieses Makros können korrekt geschriebene Programme nach einer einfachen Neukompilierung große Dateien bearbeiten.)

64-Bit-Systeme erlauben natürlich Dateigrößen größer als 2 Gigabyte. Auf diesen Systemen dieses Makro hat keine Wirkung.

_BSD_SOURCE (misbilligt seit Glibc 2.20)

Mit der Definition dieses Makros mit irgend einem Wert stellen Header-Dateien BSD-abgeleitete Definitionen bereit.

In Glibc bis einschließlich 2.18 bewirkte die Definition dieses Makros auch, dass BSD-Definitionen in manchen Situationen vorgezogen werden, wenn sich Standards widersprechen. Sind aber eines oder mehrere Makros aus der Gruppe _SVID_SOURCE, _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED oder _GNU_SOURCE definiert, werden BSD-Definitionen missachtet. Seit Glibc 2.19 führt _BSD_SOURCE nicht mehr dazu, dass BSD-Definitionen im Konfliktfall bevorzugt werden.

Seit Glibc 2.20 wird dieses Makro misbilligt. Es hat jetzt den gleichen Effekt wie die Definition von _DEFAULT_SOURCE, erzeugt aber eine Compiler-Warnung (außer _DEFAULT_SOURCE ist auch definiert). Verwenden Sie stattdessen _DEFAULT_SOURCE. Um Code zu erlauben, der bis Glibc 2.19 _BSD_SOURCE und _DEFAULT_SOURCE ab Glibc 2.20 benötigt, um ohne Warnung übersetzt zu werden, definieren Sie sowohl _BSD_SOURCE als auch _DEFAULT_SOURCE.

_SVID_SOURCE (misbilligt seit Glibc 2.20)

Die Definition dieses Makros mit einem beliebigen Wert veranlasst Header-Dateien zur Aktivierung von von System V abgeleiteten Definitionen. (SVID steht für System V Interface Definition; siehe standards(7).)

Dieses Makro wird in der gleichen Art wie _BSD_SOURCE seit Glibc 2.20 misbilligt.

_DEFAULT_SOURCE (seit Glibc 2.19)

Dieses Makro kann definiert werden, um sicherzustellen, dass die »Standarddefinitionen« bereitgestellt werden, selbst wenn die Vorgaben ansonsten deaktiviert würden. Dies passiert beispielsweise, wenn individuelle Makros explizit definiert sind oder der Compiler in einem seiner »Standardmodi« aufgerufen wird (z.B. cc -std=c99).

Die »Standard«-Definition umfasst die von POSIX.1-2008 und C99 umfassten sowie verschiedene ursprünglich aus BDS und System V abgeleitete Definitionen. Bis Glibc 2.19 waren diese Standardwerte ungefähr zu der folgenden, expliziten Definition identisch:

cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809

_ATFILE_SOURCE (seit Glibc 2.4)

Die Definition dieses Makros mit einem beliebigen Wert veranlasst Header-Dateien zur Aktivierung einer Auswahl von Funktion mit der Endung »at«, siehe openat(2). Seit Glibc 2.10 wird dieses Makro auch implizit definiert, wenn _POSIX_C_SOURCE mit einem Wert größer oder gleich 200809L definiert ist.

_GNU_SOURCE

Die Definition dieses Makros (mit einem beliebigen Wert) definiert implizit _ATFILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE, _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE mit dem Wert 200809L (200112L in Glibc-Versionen vor 2.10; 199506L in Glibc-Versionen vor 2.5; 199309L in Glibc-Versionen vor 2.1) und _XOPEN_SOURCE mit dem Wert 700 (600 in Glibc-Versionen vor 2.10; 500 in Glibc-Versionen vor 2.2). Darüber hinaus werden verschiedene GNU-spezifische Erweiterungen aktiviert.

Seit Glibc 2.19 hat die Definition von _GNU_SOURCE auch den Effekt, _DEFAULT_SOURCE implizit zu definieren. In Glibc-Versionen vor 2.20 hatte die Definition von _GNU_SOURCE auch den Effekt, _BSD_SOURCE und _SVID_SOURCE implizit zu definieren.

_REENTRANT

Historisch war es bei verschiedenen C-Bibliotheken notwendig, dieses Makro in allem Code, der multithreaded ist, zu definieren. (Einige C-Bibliotheken könnten dies noch immer benötigen). Unter Glibc legte dieses Makro auch Definitionen von bestimmten, wiedereintrittsfähigen Funktionen offen.

Allerdings ist Glibc standardmäßig seit vielen Jahren Thread-sicher (seit Glibc 2.3). Der einzige Effekt der Definition von _REENTRANT war, dass sie auch eine oder zwei der gleichen Deklarationen aktivierte, die auch durch die Definition von _POSIX_C_SOURCE mit einem Wert von 199606L oder höher aktiviert werden.

_REENTRANT ist jetzt veraltet. Seit Glibc 2.25 ist die Definition von _REENTRANT äquivalent zur Definition von _POSIX_C_SOURCE mit dem Wert 199606L. Falls durch eine andere Methode eine höhere Konformitätsstufe (wie _POSIX_C_SOURCE selbst, _XOPEN_SOURCE, _DEFAULT_SOURCE oder _GNU_SOURCE) ausgewählt wird, hat die Definition von _REENTRANT keinen Effekt.

Dieses Makro wird automatisch definiert, falls mit cc -pthread kompiliert wird.

_THREAD_SAFE

Synonym für das (veraltete) _REENTRANT; wird für die Kompatibilität mit einigen anderen Implementierungen bereitgestellt.

_FORTIFY_SOURCE (seit Glibc 2.3.4)

Die Definition dieses Makros führt dazu, dass ein paar leichtgewichtige Prüfungen durchgeführt werden, um einige Pufferüberlauffehler beim Einsatz verschiedener Zeichenketten- und Speicherveränderungsfunktionen (beispielsweise bei memcpy(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3), strncat(3), sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3), gets(3) und deren Weitzeichenvarianten) zu erkennen. Bei einigen Funktionen wird die Konsistenz der Argumente geprüft, beispielsweise dass bei open(2) ein Argument mode übergeben wurde, wenn die angegebenen Schalter O_CREAT enthalten. Es werden nicht alle Probleme sondern lediglich einige häufige Fälle erkannt.

Ist der Wert von _FORTIFY_SOURCE gleich 1 und die Compiler-Optimierungsstufe 1 (gcc -O1) oder höher, erfolgt eine Beschränkung auf Kontrollen, die das Verhalten standardkonformer Programme nicht ändern sollten. Wird _FORTIFY_SOURCE auf 2 gesetzt, werden ein paar Kontrollen hinzugefügt, die aber Fehler in einigen standardkonformen Programmen bewirken könnten.

Einige der Prüfungen können bei der Kompilierung ausgeführt werden (mittels in Header-Dateien implementierter Makrologik) und führen zu Compiler-Warnungen, andere Kontrollen finden zur Laufzeit statt und führen zu einem Laufzeitfehler, wenn die Überprüfung fehlschlägt.

Die Verwendung dieses Makros benötigt die Unterstützung durch den Compiler. Diese ist in gcc(1) seit Version 4.0 verfügbar.

Standarddefinitionen, implizite Definitionen und Kombinationsdefinitionen

Ohne explizit definierte Feature-Test-Makros werden standardmäßig die folgenden Feature-Test-Makros definiert: _BSD_SOURCE (bis Glibc 2.19), _SVID_SOURCE (bis Glibc 2.19), _DEFAULT_SOURCE (seit Glibc 2.19), _POSIX_SOURCE und _POSIX_C_SOURCE=200809L (200112L in Glibc-Versionen vor 2.10; 199506L in Glibc-Versionen vor 2.4; 199309L in Glibc-Versionen vor 2.1).

Wenn eines von __STRICT_ANSI__, _ISOC99_SOURCE, _ISOC11_SOURCE (seit Glibc 2.18), _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED (bis Glibc 2.11), _BSD_SOURCE (bis Glibc 2.19) oder _SVID_SOURCE (bis Glibc 2.19) explizit definiert ist, dann werden standardmäßig _BSD_SOURCE, _SVID_SOURCE und _DEFAULT_SOURCE nicht definiert.

Sind _POSIX_SOURCE und _POSIX_C_SOURCE nicht explizit definiert und entweder __STRICT_ANSI__ ist nicht definiert oder _XOPEN_SOURCE hat einen Wert von 500 oder mehr, dann

• wird _POSIX_SOURCE auf den Wert 1 gesetzt und
• _POSIX_C_SOURCE erhält einen der folgenden Werte:

Es können mehrere Makros definiert werden, die Effekte akkumulieren sich.

Programmquelltext

/* ftm.c */
#include <stdint.h>
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
#ifdef _POSIX_SOURCE


    printf("_POSIX_SOURCE definiert\n");
#endif
#ifdef _POSIX_C_SOURCE


    printf("_POSIX_C_SOURCE definiert: %jdL\n",


            (intmax_t) _POSIX_C_SOURCE);
#endif
#ifdef _ISOC99_SOURCE


    printf("_ISOC99_SOURCE definiert\n");
#endif
#ifdef _ISOC11_SOURCE


    printf("_ISOC11_SOURCE definiert\n");
#endif
#ifdef _XOPEN_SOURCE


    printf("_XOPEN_SOURCE definiert: %d\n", _XOPEN_SOURCE);
#endif
#ifdef _XOPEN_SOURCE_EXTENDED


    printf("_XOPEN_SOURCE_EXTENDED definiert\n");
#endif
#ifdef _LARGEFILE64_SOURCE


    printf("_LARGEFILE64_SOURCE definiert\n");
#endif
#ifdef _FILE_OFFSET_BITS


    printf("_FILE_OFFSET_BITS definiert: %d\n", _FILE_OFFSET_BITS);
#endif
#ifdef _BSD_SOURCE


    printf("_BSD_SOURCE definiert\n");
#endif
#ifdef _SVID_SOURCE


    printf("_SVID_SOURCE definiert\n");
#endif
#ifdef _DEFAULT_SOURCE


    printf("_DEFAULT_SOURCE definiert\n");
#endif
#ifdef _ATFILE_SOURCE


    printf("_ATFILE_SOURCE definiert\n");
#endif
#ifdef _GNU_SOURCE


    printf("_GNU_SOURCE definiert\n");
#endif
#ifdef _REENTRANT


    printf("_REENTRANT definiert\n");
#endif
#ifdef _THREAD_SAFE


    printf("_THREAD_SAFE definiert\n");
#endif
#ifdef _FORTIFY_SOURCE


    printf("_FORTIFY_SOURCE definiert\n");
#endif


    exit(EXIT_SUCCESS);
}