feature_test_macros

NOM

DESCRIPTION

NOTE : pour avoir un effet, une macro de test de fonctionnalités doit être définie avant d'inclure tout fichier d'en-tête. Cela peut être accompli soit dans la ligne de commande de compilation (cc -DMACRO=valeur), soit en définissant la macro dans le code source avant d'inclure tout en-tête. L’exigence que la macro soit définie avant d’inclure n’importe quel fichier d’en-tête existe parce que les fichiers d’en-tête peuvent librement s’inclure mutuellement. Donc, par exemple, dans les lignes suivantes, définir la macro _GNU_SOURCE peut n’avoir aucun effet parce que l’en-tête <abc.h> lui-même inclut <xyz.h> (POSIX le permet explicitement) :

#include <abc.h> #define _GNU_SOURCE #include <xyz.h>

Certaines macros de test de fonctionnalités sont utiles pour créer des applications portables, en empêchant des définitions non normalisées d'être exposées. D'autres macros peuvent être utilisées pour exposer des définitions non normalisées qui ne sont pas exposées par défaut.

Les effets précis de chacune des macros décrites ci-dessous peuvent être vérifiés en inspectant le fichier d'en-tête <features.h>. Remarque : les applications n’ont pas besoin d’inclure directement <features.h>. En fait, le faire est fortement déconseillé. Consultez les NOTES.  

Spécification des exigences de macro de test de fonctionnalités dans les pages de manuel

#include <unistd.h>

int acct(const char *fichier);

acct() : _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)

Les doubles barres || signifient que pour obtenir la déclaration de acct(2) depuis <unistd.h>, une des définitions de macros doit être utilisée avant d'inclure les fichiers d'en-tête :

#define _BSD_SOURCE #define _XOPEN_SOURCE /* Ou toute valeur < 500 */

Autrement, des définitions équivalentes peuvent être faites lors de l'appel au compilateur :

cc -D_BSD_SOURCE cc -D_XOPEN_SOURCE # Ou toute valeur < 500

Veuillez noter que, comme décrit ci-dessous, certaines macros de test de fonctionnalités sont définies par défaut, et il n'est donc pas toujours nécessaire de spécifier explicitement les macros indiquées dans le SYNOPSIS.

Dans certains cas, les pages de manuel utilisent des raccourcis pour exprimer la nécessité de certaines macros de test (exemple tiré de readahead(2)) :

#define _GNU_SOURCE #define _FILE_OFFSET_BITS 64 #include <fcntl.h>

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

This format is employed when the feature test macros ensure that the proper function declarations are visible, and the macros are not defined by default.  

Macros de test de fonctionnalités comprises par la glibc

Tout d’abord, un aperçu de quelques détails pour l’impatient :

-

Les macros les plus susceptibles d’être utilisées dans des codes source modernes sont _POSIX_C_SOURCE (pour des définitions de diverses versions de POSIX.1), _XOPEN_SOURCE (pour des définitions de diverses versions de SUS), _GNU_SOURCE (pour certaines choses spécifiques à GNU ou Linux) et _DEFAULT_SOURCE (pour obtenir des définitions qui normalement devrait être fournies par défaut).

-

Certaines macros sont définies avec des valeurs par défaut. Par conséquent, même si une ou plusieurs macros sont indiquées comme nécessaires dans le SYNOPSIS d’une page de manuel, il peut ne pas être nécessaire de les définir explicitement. Tous les détails sur les valeurs par défaut sont donnés ci-après dans cette page de manuel.

-

Définir _XOPEN_SOURCE avec une valeur de 600 ou plus produit le même effet que définir _POSIX_C_SOURCE avec une valeur de 200112L ou supérieure. Lorsqu’apparaît

_POSIX_C_SOURCE >= 200112L

dans les nécessités des macros de test de fonctionnalités dans le SYNOPSIS d’une page de manuel, il est implicite que ce qui suit a le même effet :

_XOPEN_SOURCE >= 600

-

Définir _XOPEN_SOURCE avec une valeur de 700 ou plus produit le même effet que définir _POSIX_C_SOURCE avec une valeur de 200809L ou supérieure. Lorsqu’apparaît

_POSIX_C_SOURCE >= 200809L

dans les nécessités des macros de test de fonctionnalités dans le SYNOPSIS d’une page de manuel, il est implicite que ce qui suit a le même effet :

_XOPEN_SOURCE >= 700

La glibc comprend les macros de test de fonctionnalités suivantes :

__STRICT_ANSI__

Norme C ISO. Cette macro est définie implicitement par gcc(1) lors des appels avec, par exemple, l'indicateur -std=c99 ou -ansi.

_POSIX_C_SOURCE

Si cette macro est définie, les en-têtes exposent les définitions suivantes :

-

La valeur 1 expose les définitions conformes à POSIX.1-1990 et C ISO (1990).

-

Les valeurs supérieures ou égales à 2 exposent en plus les définitions de POSIX.2-1992.

-

Les valeurs supérieures ou égales à 199309L exposent en plus les définitions de POSIX.1b (extensions temps-réel).

-

Les valeurs supérieures ou égales à 199506L exposent en plus les définitions de POSIX.1c (threads).

-

(Depuis la glibc 2.3.3) Les valeurs supérieures ou égales à 200112L exposent de plus les définitions correspondantes à la spécification de base POSIX.1-2001 (sans l'extension XSI) et activent également les fonctionnalités C95 (depuis la glibc 2.12) et C99 (depuis la glibc 2.10) — en d’autres mots, l’équivalent de définir _ISOC99_SOURCE.

-

(Depuis la glibc 2.10) Les valeurs supérieures ou égales à 200809L exposent de plus les définitions correspondantes à la spécification de base POSIX.1-2008 (sans l'extension XSI).

_POSIX_SOURCE

Définir cette macro obsolète (quelle que soit sa valeur) est équivalent à définir _POSIX_C_SOURCE à la valeur 1.

Puisque cette macro est obsolète, son utilisation n’est généralement pas documentée lors de l’explication des nécessités de macros de test de fonctionnalités dans les pages de manuel.

_XOPEN_SOURCE

Si cette macro est définie, les en-têtes exposent les définitions suivantes :

-

Si elle est définie, quelle que soit sa valeur, les définitions de POSIX.1, POSIX.2 et XPG4 sont exposées.

-

Les valeurs supérieures ou égales à 500 exposent les définitions de SUSv2 (UNIX 98).

-

(Depuis la glibc 2.2) Les valeurs supérieures ou égales à 600 exposent les définitions de SUSv3 (UNIX 03, c'est-à-dire la spécification de base POSIX.1-2001 plus l'extension XSI) et de C99.

-

(Depuis la glibc 2.10) Les valeurs supérieures ou égales à 700 exposent les définitions de SUSv4 (c'est-à-dire la spécification de base POSIX.1-2008 plus l'extension XSI).

Si __STRICT_ANSI__ n'est pas définie, ou si _XOPEN_SOURCE est définie avec une valeur supérieure ou égale à 500 et que ni _POSIX_SOURCE ni _POSIX_C_SOURCE ne sont explicitement définies, alors les macros suivantes sont implicitement définies :

-

_POSIX_SOURCE est définie à la valeur 1.

-

_POSIX_SOURCE est définie d'après la valeur de _XOPEN_SOURCE :

_XOPEN_SOURCE < 500

_POSIX_C_SOURCE est définie à la valeur 2.

500 <= _XOPEN_SOURCE < 600

_POSIX_C_SOURCE est définie à la valeur 199506L.

600 <= _XOPEN_SOURCE < 700

_POSIX_C_SOURCE est définie à la valeur 200112L.

700 <= _XOPEN_SOURCE (depuis la glibc 2.10)

_POSIX_C_SOURCE est définie à la valeur 200809L.

De plus, définir _XOPEN_SOURCE avec une valeur de 500 ou supérieure produit le même effet que définir _XOPEN_SOURCE_EXTENDED.

_XOPEN_SOURCE_EXTENDED

Si cette macro et _XOPEN_SOURCE sont définies, exposer les définitions correspondant aux extensions XPG4v2 (SUSv1) d'UNIX (UNIX 95). Définir _XOPEN_SOURCE avec une valeur de 500 ou supérieure produit aussi le même effet que définir _XOPEN_SOURCE_EXTENDED. L’utilisation de _XOPEN_SOURCE_EXTENDED dans un nouveau code source est à éviter.

Puisque définir _XOPEN_SOURCE avec une valeur de 500 ou supérieure produit aussi le même effet que définir _XOPEN_SOURCE_EXTENDED, cette dernière (obsolète) macro de test de fonctionnalités n’est généralement pas décrite dans le SYNOPSIS des pages de manuel.

_ISOC99_SOURCE (depuis la glibc 2.1.3)

Exposer des déclarations cohérentes avec la norme ISO C99.

Les versions antérieures de la glibc 2.1.x reconnaissaient une macro équivalente appelée _ISOC9X_SOURCE (parce que la norme C99 n'était pas finalisée). Même si l'utilisation de cette dernière macro est à proscrire, la glibc continue à la reconnaître pour des raisons de compatibilité ascendante.

Si _ISOC99_SOURCE est définie, les définitions du premier amendement au C ISO (1990) (aussi appelé C95) sont aussi exposées. La première modification de C95 était la prise en charge des jeux de caractères internationaux.

Invoquer le compilateur C avec l’option -std=c99 produit le même effet que définir cette macro.

_ISOC11_SOURCE (depuis la glibc 2.16)

Exposer des déclarations cohérentes avec la norme ISO C11. La définition de cette macro active également les fonctionnalités C99 et C95 (comme _ISOC99_SOURCE).

Invoquer le compilateur C avec l’option -std=c11 produit le même effet que définir cette macro.

_LARGEFILE64_SOURCE

Exposer les définitions pour l'API alternative définie par le LFS (« Large File Summit ») comme une extension de transition pour la « Single UNIX Specification ». Veuillez vous référer à L'API alternative consiste en un jeu de nouveaux objets (c'est-à-dire des fonctions et types) dont le nom est suffixé avec « 64 » (par exemple off64_t pour off_t, lseek64() pour lseek(), etc.). Les nouveaux programmes ne devraient pas utiliser cette macro ; à la place, _FILE_OFFSET_BITS=64 devrait être utilisée.

_LARGEFILE_SOURCE

Cette macro a historiquement été utilisée pour exposer certaines fonctions (en particulier fseeko() et ftello()) qui contournent les limites d’interfaces de programmation précédentes (feek() et ftell()) qui utilisent long pour les positions de fichier. Cette macro est implicitement définie si _XOPEN_SOURCE est définie avec une valeur supérieure ou égale à 500. Les nouveaux programmes ne devraient pas utiliser cette macro. Définir _XOPEN_SOURCE comme cela vient d’être décrit ou définir _FILE_OFFSET_BITS à la valeur 64 sont les mécanismes préférés pour obtenir le même résultat.

_FILE_OFFSET_BITS

Defining this macro with the value 64 automatically converts references to 32-bit functions and data types related to file I/O and filesystem operations into references to their 64-bit counterparts. This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. It is also useful when calling functions like copy_file_range(2) that were added more recently and that come only in 64-bit flavors. (Defining this macro permits correctly written programs to use large files with only a recompilation being required.)

Les systèmes 64 bits permettent d'office d'utiliser des fichiers de taille supérieure à 2 gigaoctets, et sur ces systèmes cette macro n'a aucun effet.

_TIME_BITS

Defining this macro with the value 64 changes the width of time_t(3type) to 64-bit which allows handling of timestamps beyond 2038. It is closely related to _FILE_OFFSET_BITS and depending on implementation, may require it set. This macro is available as of glibc 2.34.

_BSD_SOURCE (obsolète depuis la glibc 2.20)

Si cette macro est définie avec n’importe quelle valeur, les définitions héritées de BSD sont exposées par les en-têtes.

Jusqu’à la glibc 2.18 incluse, les définitions BSD sont préférées dans les situations où les normes sont en conflit, sauf si au moins une des macros _SVID_SOURCE, _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED ou _GNU_SOURCE est définie, auquel cas les définitions BSD sont défavorisées. Depuis la glibc 2.19, _BSD_SOURCE ne force plus la préférence des définitions BSD en cas de conflit.

Depuis la glibc 2.20, cette macro est obsolète. Sa définition a le même effet que la définition de _DEFAULT_SOURCE, mais génère un avertissement de compilation (à moins que _DEFAULT_SOURCE soit également définie). Utilisez _DEFAULT_SOURCE à la place. Pour permettre au code nécessitant _BSD_SOURCE dans glibc 2.19 et versions antérieures, et _DEFAULT_SOURCE dans glibc 2.20 et version suivantes, de compiler sans avertissement, définissez à la fois _BSD_SOURCE et _DEFAULT_SOURCE.

_SVID_SOURCE (obsolète depuis la glibc 2.20)

Si cette macro est définie (quelle que soit sa valeur), les en-têtes exposent les définitions héritées de System V. (SVID == System V Interface Definition ; consultez standards(7).)

Depuis la glibc 2.20, cette macro est obsolète de la même manière que _BSD_SOURCE.

_DEFAULT_SOURCE (depuis la glibc 2.19)

Cette macro peut être définie pour s’assurer que les définitions par « défaut » sont fournies même si les valeurs par défaut avaient été désactivées, comme cela arrive quand les macros individuelles sont définies explicitement ou quand le compilateur est appelé dans un de ses modes « normalisés » (par exemple cc -std=c99). Définir _DEFAULT_SOURCE n'a aucun effet sans définir d'autres macros individuelles ou invoquer le compilateur dans un de ses modes « normalisés ».

Les définitions par « défaut » incluent celles requises par POSIX.1-2008 et C99 ISO ainsi que plusieurs définitions dérivées de BSD et System V. Avec la glibc 2.19 et avant, ces définitions par défaut sont à peu près équivalentes à la définition explicite suivante :

cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809

_ATFILE_SOURCE (depuis la glibc 2.4)

Si cette macro est définie (quelle que soit sa valeur), les en-têtes exposent les définitions d'une série de fonctions avec le suffixe « at » ; consultez openat(2). Depuis glibc 2.10, cette macro est aussi définie de manière implicite si _POSIX_C_SOURCE est définie avec une valeur supérieure ou égale à 200809L.

_GNU_SOURCE

Définir cette macro (avec n'importe quelle valeur) définit implicitement _ATFILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE, _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE avec la valeur 200809L (200112L avant la glibc 2.10, 199506L avant la glibc 2.5, 199309L glibc 2.1) et _XOPEN_SOURCE avec la valeur 700 (600 la glibc 2.10, 500 avant la glibc 2.2). De plus, de nombreuses extensions spécifiques GNU sont exposées.

Depuis la glibc 2.19, définir _GNU_SOURCE provoque la définition implicite de _DEFAULT_SOURCE. Avant la glibc 2.20, définir _GNU_SOURCE provoque la définition implicite de _BSD_SOURCE et _SVID_SOURCE.

_REENTRANT

Historiquement, dans diverses bibliothèques C il était nécessaire de définir cette macro dans tous les codes multithread (cela peut être encore nécessaire dans quelques bibliothèques C). Dans la glibc, cette macro expose aussi des définitions de certaines fonctions réentrantes.

Cependant, la glibc est thread-safe par défaut depuis de nombreuses années. Depuis la glibc 2.3, le seul effet de définir _REENTRANT est d’activer une ou deux des mêmes déclarations qui sont activées en définissant _POSIX_C_SOURCE avec une valeur 199606L ou supérieure.

_REENTRANT est désormais obsolète. Dans la glibc 2.25 et les versions postérieures, définir _REENTRANT est équivalent à définir _POSIX_C_SOURCE avec comme valeur 199606L. Si un niveau de conformité POSIX supérieur est sélectionné par n’importe quel autre moyen (tel que _POSIX_C_SOURCE lui-même, _XOPEN_SOURCE, _DEFAULT_SOURCE ou _GNU_SOURCE), puis définir _REENTRANT n’a aucun effet.

Cette macro est automatiquement définie si la compilation est faite avec cc -pthread.

_THREAD_SAFE

Synonyme de _REENTRANT (obsolète), fourni pour la compatibilité avec d'autres implémentations.

_FORTIFY_SOURCE (depuis la glibc 2.3.4)

Définir cette macro cause certaines vérifications peu poussées d’être réalisées pour détecter quelques dépassements de tampon lors de l’emploi de diverses chaînes et de fonctions de manipulation de mémoire (par exemple, memcpy(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3), strncat(3), sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3), gets(3) et les variantes de caractères larges de celles-ci). Pour certaines fonctions, la pertinence de l’argument est vérifiée. Par exemple, une vérification est faite qu’un argument mode soit fourni à open(2) quand les indicateurs indiqués incluent O_CREAT. Tous les problèmes ne sont pas détectés, seulement quelques cas courants.

Si _FORTIFY_SOURCE est défini à 1, avec un niveau 1 d'optimisation de compilateur (gcc -O1) ou supérieur, des vérifications sans influence sur le comportement de programmes conformes sont faites. Avec _FORTIFY_SOURCE défini à 2, des vérifications supplémentaires sont ajoutées, mais certains programmes conformes peuvent échouer.

Certaines vérifications peuvent être effectuées lors de la compilation (à l’aide d’une logique de macros implémentés dans les en-têtes) et génèrent des avertissements du compilateur. D'autres vérifications ont lieu à l'exécution et causent une erreur si le test échoue.

With _FORTIFY_SOURCE set to 3, additional checking is added to intercept some function calls used with an argument of variable size where the compiler can deduce an upper bound for its value. For example, a program where malloc(3)'s size argument is variable can now be fortified.

Use of this macro requires compiler support, available since gcc 4.0 and clang 2.6. Use of _FORTIFY_SOURCE set to 3 requires gcc 12.0 or later, or clang 9.0 or later, in conjunction with glibc 2.33 or later.

Définitions par défaut, définitions implicites et combinaison de définitions

Si une des macros __STRICT_ANSI__, _ISOC99_SOURCE, _ISOC11_SOURCE (depuis la glibc 2.18) _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED (dans la glibc 2.11 et avant), _BSD_SOURCE (dans la glibc 2.19 et avant) ou _SVID_SOURCE (dans la glibc 2.19 et avant) est définie explicitement, alors _BSD_SOURCE, _SVID_SOURCE et _DEFAULT_SOURCE ne sont pas définies par défaut.

Si ni _POSIX_SOURCE ni _POSIX_C_SOURCE ne sont définies explicitement et que soit __STRICT_ANSI__ n'est pas définie soit _XOPEN_SOURCE est définie à une valeur supérieure ou égale à 500, alors

-

_POSIX_SOURCE est définie à la valeur 1

-

_POSIX_C_SOURCE est définie avec une des valeurs suivantes :

-

2, si _XOPEN_SOURCE est définie avec une valeur inférieure à 500 ;

-

199506L, si _XOPEN_SOURCE est définie à une valeur supérieure ou égale à 500 et inférieure à 600, ou

-

200112L (depuis la glibc 2.4), si _XOPEN_SOURCE est définie à une valeur supérieure ou égale à 600 et inférieure à 700 ;

-

200809L (depuis la glibc 2.10), si _XOPEN_SOURCE est définie à une valeur supérieure ou égale à 700.

-

Les versions plus anciennes de la glibc ne connaissent pas les valeurs 200112L et 200809L pour _POSIX_C_SOURCE et la configuration de cette macro dépendra de la version de la glibc.

-

Si _XOPEN_SOURCE n'est pas défini, alors la configuration de _POSIX_C_SOURCE dépend de la version de la glibc : 199506L avant la glibc 2.4, 200112L de la glibc 2.4 à la glibc 2.9 et 200809L depuis la glibc 2.10.

Plusieurs macros peuvent être définies, les résultats sont additifs.  

STANDARDS

_FILE_OFFSET_BITS n’est spécifiée par aucune norme, mais est employée dans quelques autres implémentations.

_BSD_SOURCE, _SVID_SOURCE, _DEFAULT_SOURCE, _ATFILE_SOURCE, _GNU_SOURCE, _FORTIFY_SOURCE, _REENTRANT et _THREAD_SAFE sont spécifiques à la glibc.  

HISTORIQUE

NOTES

Selon quelles macros de test de fonctionnalités ci-dessus sont définies, <features.h> définit diverses autres macros qui sont testées par les en-têtes de la glibc. Ces macros ont des noms préfixés par deux caractères de soulignement (par exemple __USE_MISC). Les programmes ne doivent jamais définir ces macros directement ; ils doivent utiliser les macros de test de fonctionnalités de la liste précédente.  

EXEMPLES

$ cc ftm.c $ ./a.out _POSIX_SOURCE defined _POSIX_C_SOURCE defined: 200809L _BSD_SOURCE defined _SVID_SOURCE defined _ATFILE_SOURCE defined $ cc -D_XOPEN_SOURCE=500 ftm.c $ ./a.out _POSIX_SOURCE defined _POSIX_C_SOURCE defined: 199506L _XOPEN_SOURCE defined: 500 $ cc -D_GNU_SOURCE ftm.c $ ./a.out _POSIX_SOURCE defined _POSIX_C_SOURCE defined: 200809L _ISOC99_SOURCE defined _XOPEN_SOURCE defined: 700 _XOPEN_SOURCE_EXTENDED defined _LARGEFILE64_SOURCE defined _BSD_SOURCE defined _SVID_SOURCE defined _ATFILE_SOURCE defined _GNU_SOURCE defined  

Source du programme

VOIR AUSSI

La section « Feature Test Macros » de info libc.

/usr/include/features.h

TRADUCTION

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à

Index

NOM

DESCRIPTION

Spécification des exigences de macro de test de fonctionnalités dans les pages de manuel

Macros de test de fonctionnalités comprises par la glibc

Définitions par défaut, définitions implicites et combinaison de définitions

STANDARDS

HISTORIQUE

NOTES

EXEMPLES

Source du programme

VOIR AUSSI

TRADUCTION