feature_test_macros

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

Quand une fonction nécessite qu'une macro de test de fonctionnalité soit définie, la section SYNOPSIS de la page de manuel comprend généralement une note de la forme suivante (exemple pris dans la page de manuel acct(2)) :

Exigences de macros de test de fonctionnalités pour
la glibc (consultez feature_test_macros(7)) :

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, les 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é 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
#include <fcntl.h>

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

Ce format est utilisé dans les cas où seule une macro de test de fonctionnalité peut être utilisée pour exposer la déclaration de la fonction et quand cette macro n'est pas définie par défaut.

Macros de test de fonctionnalités comprises par la glibc

Les paragraphes suivants expliquent comment les macros de test de fonctionnalité sont gérées les glibc Linux 2.x, x > 0.

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

__STRICT_ANSI__

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

_POSIX_C_SOURCE

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

_POSIX_SOURCE

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

_XOPEN_SOURCE

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

_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) Cette macro est également définie implicitement si _XOPEN_SOURCE est définie avec une valeur supérieure ou égale à 500.

_ISOC95_SOURCE

Exposer les définitions du premier amendement au C ISO (1990) (aussi appelé C95). Cette macro est reconnue depuis la glibc 2.12. La première modification de C95 était la prise en charge des jeux de caractères internationaux. Les modifications de C95 ont été intégrées à la norme C99 qui a suivi (autrement dit, _ISOC99_SOURCE implique _ISOC95_SOURCE).

_ISOC99_SOURCE

Exposer les extensions C99 du C ISO (1990). Cette macro est reconnue depuis la glibc 2.1.3 ; les versions antérieures de la glibc 2.1.x reconnaissaient une macro équivalent 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.

_ISOC11_SOURCE

Exposer des déclarations cohérentes avec la norme ISO C11. Cette macro est reconnue depuis glibc 2.16.

_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 à http://opengroup.org/platform/lfs.html. L'API alternative consiste en un jeu de nouveaux objets (c'est-à-dire des fonctions et types) dont le nom en suffixé de « 64 » (par exemple off64_t pour off_t, lseek64() pour lseek(), etc.). Les nouveaux programmes ne devraient pas utiliser ces interfaces ; à la place, _FILE_OFFSET_BITS=64 devrait être utilisée.

_FILE_OFFSET_BITS

Définir cette macro à la valeur 64 convertit automatiquement les références aux fonctions et types de données 32 bits liés aux E/S sur les fichiers et aux opérations sur le système de fichiers en références à leurs équivalents 64 bits. C'est utile pour les E/S sur des gros fichiers (> 2 gigaoctets) sur les systèmes 32 bits. Cette macro permet aux programmes correctement écrits d'utiliser de gros fichiers avec seulement une recompilation. Les systèmes 64 bits permettent d'office d'utiliser des fichiers de taille supérieure à 2 gigaoctets, et sur ces système cette macro n'a aucun effet.

_BSD_SOURCE

Si cette macro est définie, les définitions héritées de BSD sont exposées par les en‐têtes. Jusqu’à la glibc 2.18 inclue, 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.

_SVID_SOURCE

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

_DEFAULT_SOURCE (depuis la glibc 2.19)

Définir cette macro fournit un effet similaire aux macros de test de fonctionnalité qui sont définies par défaut, c’est-à-dire :

cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809

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

_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 fonction 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) est équivalent à définir _BSD_SOURCE, _SVID_SOURCE, _ATFILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE, _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE avec la valeur 200809L (200112L dans les versions de la glibc antérieures à 2.10 ; 199506L dans les versions de la glibc antérieures à 2.5 ; 199309L dans les versions de la glibc antérieures à 2.1), et _XOPEN_SOURCE avec la valeur 700 (600 dans les versions de la glibc antérieures à 2.10 ; 500 dans les versions de la glibc antérieures à 2.2). De plus, de nombreuses extensions spécifiques GNU sont exposées. Quand les normes se contredisent, les définitions BSD sont les moins prioritaires.

_REENTRANT

Définir cette macro rend accessibles les définitions de certaines fonctions réentrantes. Pour les programmes multithreadés, utilisez cc -pthread à la place.

_THREAD_SAFE

Synonyme de _REENTRANT, fourni pour la compatibilité avec d'autres implémentations.

_FORTIFY_SOURCE (depuis la glibc 2.3.4)

Définir cette macro active certains tests peu coûteux pour détecter certains dépassements de tampons dans diverses fonctions de manipulation de chaînes ou de mémoire. Tous les dépassements de tampons ne sont pas détectés, mais uniquement certains cas fréquents. Actuellement, des vérifications sont ajoutées pour les appels à memcpy(3), mempcpy(3), memmove(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3), strncat(3), sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3), et gets(3). Si _FORTIFY_SOURCE est défini à 1, avec un niveau d'optimisation de 1 ou plus (gcc -O1), des vérifications sans influence sur le comportement des programmes corrects 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 à la compilation et génèrent des avertissements du compilateur ; d'autres ont lieu à l'exécution et causent une erreur si le test échoue. L'utilisation de cette macro nécessite une gestion par le compilateur, qui est disponible dans gcc(1) depuis la version 4.0.

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

Si aucune macro de test de fonctionnalité n'est définie explicitement, alors les macros de test suivantes sont définies par défaut : _BSD_SOURCE, _SVID_SOURCE, _POSIX_SOURCE et _POSIX_C_SOURCE=200809L (200112L dans les versions de la glibc antérieures à 2.10 ; 199506L dans les versions de la glibc antérieures à 2.4 ; 199309L dans les versions de la glibc antérieures à ).

Si une des macros __STRICT_ANSI__, _ISOC99_SOURCE, _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED, _BSD_SOURCE ou _SVID_SOURCE est définie explicitement, alors _BSD_SOURCE et _SVID_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

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

Source du programme

/* ftm.c */
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
#ifdef _POSIX_SOURCE
    printf("_POSIX_SOURCE définie\n");
#endif
#ifdef _POSIX_C_SOURCE
    printf("_POSIX_C_SOURCE définie : %ldL\n", (long) _POSIX_C_SOURCE);
#endif
#ifdef _ISOC99_SOURCE
    printf("_ISOC99_SOURCE définie\n");
#endif
#ifdef _ISOC11_SOURCE
    printf("_ISOC11_SOURCE définie\n");
#endif
#ifdef _XOPEN_SOURCE
    printf("_XOPEN_SOURCE définie : %d\n", _XOPEN_SOURCE);
#endif
#ifdef _XOPEN_SOURCE_EXTENDED
    printf("_XOPEN_SOURCE_EXTENDED définie\n");
#endif
#ifdef _LARGEFILE64_SOURCE
    printf("_LARGEFILE64_SOURCE définie\n");
#endif
#ifdef _FILE_OFFSET_BITS
    printf("_FILE_OFFSET_BITS définie : %d\n", _FILE_OFFSET_BITS);
#endif
#ifdef _BSD_SOURCE
    printf("_BSD_SOURCE définie\n");
#endif
#ifdef _SVID_SOURCE
    printf("_SVID_SOURCE définie\n");
#endif
#ifdef _ATFILE_SOURCE
    printf("_ATFILE_SOURCE définie\n");
#endif
#ifdef _GNU_SOURCE
    printf("_GNU_SOURCE définie\n");
#endif
#ifdef _REENTRANT
    printf("_REENTRANT définie\n");
#endif
#ifdef _THREAD_SAFE
    printf("_THREAD_SAFE définie\n");
#endif
#ifdef _FORTIFY_SOURCE
    printf("_FORTIFY_SOURCE définie\n");
#endif
    exit(EXIT_SUCCESS);
}