Namespaces
Variants

Source file inclusion

From cppreference.net
C
C language
Preprocessor

Inclut un autre fichier source dans le fichier source actuel à la ligne immédiatement après la directive.

Table des matières

Syntaxe

#include < séquence-de-caractères-h > nouvelle-ligne (1)
#include " séquence-de-caractères-q " nouvelle-ligne (2)
#include jetons-pp nouvelle-ligne (3)
__has_include ( " séquence-de-caractères-q " )
__has_include ( < séquence-de-caractères-h > ) 		(4) (depuis C23)
__has_include ( littéral-de-chaîne )
__has_include ( < jetons-pp-h > ) 		(5) (depuis C23)
1) Recherche un en-tête identifié de manière unique par h-char-sequence et remplace la directive par l'intégralité du contenu de l'en-tête.
2) Recherche un fichier source identifié par q-char-sequence et remplace la directive par l'intégralité du contenu du fichier source. Il peut revenir à (1) et traiter q-char-sequence comme un identifiant d'en-tête.
3) Si ni (1) ni (2) ne correspondent, pp-tokens subiront un remplacement de macro. La directive après remplacement sera tentée d'être mise en correspondance avec (1) ou (2) à nouveau.
4) Vérifie si un fichier d'en-tête ou de source est disponible pour inclusion.
5) Si (4) n'est pas satisfait, h-pp-tokens subira un remplacement de macro. La directive après remplacement sera tentée pour correspondre à (4) à nouveau.
new-line - Le caractère de nouvelle ligne
h-char-sequence - Une séquence d'un ou plusieurs h-char s, où l'apparition de l'un des éléments suivants provoque un comportement indéfini :
  • le caractère '
  • le caractère "
  • le caractère \
  • la séquence de caractères //
  • la séquence de caractères /*
h-char - Tout membre du jeu de caractères source sauf le caractère de nouvelle ligne et >
q-char-sequence - Une séquence d'un ou plusieurs q-char s, où l'apparition de l'un des éléments suivants provoque un comportement indéfini :
  • le caractère '
  • le caractère \
  • la séquence de caractères //
  • la séquence de caractères /*
q-char - Tout membre du jeu de caractères source sauf le caractère de nouvelle ligne et "
pp-tokens - Une séquence d'un ou plusieurs jetons de prétraitement
string-literal - Un littéral de chaîne
h-pp-tokens - Une séquence d'un ou plusieurs jetons de prétraitement sauf >

Explication

1) Recherche le fichier identifié par h-char-sequence de manière définie par l'implémentation. L'intention de cette syntaxe est de rechercher les fichiers sous le contrôle de l'implémentation. Les implémentations typiques ne recherchent que dans les répertoires d'inclusion standard. La bibliothèque standard C est implicitement incluse dans ces répertoires d'inclusion standard. Les répertoires d'inclusion standard peuvent généralement être contrôlés par l'utilisateur via les options du compilateur.
2) Recherche le fichier identifié par q-char-sequence de manière définie par l'implémentation. L'intention de cette syntaxe est de rechercher les fichiers qui ne sont pas contrôlés par l'implémentation. Les implémentations typiques recherchent d'abord le répertoire où se trouve le fichier courant et, seulement si le fichier n'est pas trouvé, recherchent les répertoires d'inclusion standard comme avec (1) .
3) Les jetons de prétraitement après include dans la directive sont traités comme dans le texte normal (c'est-à-dire que chaque identifiant actuellement défini comme nom de macro est remplacé par sa liste de remplacement de jetons de prétraitement). La directive résultant après tous les remplacements doit correspondre à l'une des deux formes précédentes. La méthode par laquelle une séquence de jetons de prétraitement entre < et > ou une paire de caractères " est combinée en un seul jeton de prétraitement de nom d'en-tête est définie par l'implémentation.
4) Le fichier d'en-tête ou le fichier source identifié par h-char-sequence ou q-char-sequence est recherché comme si cette séquence de tokens de prétraitement était les pp-tokens dans la syntaxe (3) , sauf qu'aucune expansion de macro supplémentaire n'est effectuée. Si une telle directive ne satisfait pas les exigences syntaxiques d'une directive #include , le programme est mal formé. L'expression __has_include prend la valeur 1 si la recherche du fichier source réussit, et la valeur ​ 0 ​ si la recherche échoue.
5) Ce formulaire n'est considéré que si la syntaxe (4) ne correspond pas, auquel cas les jetons de prétraitement sont traités comme dans un texte normal.

Dans le cas où le fichier n'est pas trouvé, le programme est mal formé.

__has_include peut être développé dans l'expression de #if et #elif . Il est traité comme une macro définie par #ifdef , #ifndef , #elifdef , #elifndef et defined mais ne peut pas être utilisé ailleurs.

(depuis C23)

Notes

Les implémentations typiques ne recherchent que les répertoires d'inclusion standard pour la syntaxe (1). La bibliothèque standard C est implicitement incluse dans ces répertoires d'inclusion standard. Les répertoires d'inclusion standard peuvent généralement être contrôlés par l'utilisateur via les options du compilateur.

L'intention de la syntaxe (2) est de rechercher les fichiers qui ne sont pas contrôlés par l'implémentation. Les implémentations typiques recherchent d'abord le répertoire où réside le fichier courant puis reviennent à (1) .

Lorsqu'un fichier est inclus, il est traité par les phases de traduction 1-4, ce qui peut inclure, de manière récursive, l'expansion des directives #include imbriquées, jusqu'à une limite d'imbrication définie par l'implémentation. Pour éviter l'inclusion répétée du même fichier et la récursion infinie lorsqu'un fichier s'inclut lui-même, éventuellement de manière transitive, les gardes d'en-tête sont couramment utilisées : l'intégralité de l'en-tête est encapsulée dans 

#ifndef FOO_H_INCLUDED /* tout nom mappé de manière unique au nom de fichier */
#define FOO_H_INCLUDED
// le contenu du fichier se trouve ici
#endif

De nombreux compilateurs implémentent également le non-standard pragma #pragma once avec des effets similaires : il désactive le traitement d'un fichier si le même fichier (où l'identité du fichier est déterminée de manière spécifique au système d'exploitation) a déjà été inclus.

Un résultat __has_include de 1 signifie uniquement qu'un en-tête ou fichier source avec le nom spécifié existe. Cela ne signifie pas que l'en-tête ou le fichier source, lorsqu'il est inclus, ne provoquerait pas d'erreur ou contiendrait quelque chose d'utile.

Exemple

Cette section est incomplète
Raison : aucun exemple

Références

  • Norme C23 (ISO/CEI 9899:2024) :
  • 6.4.7 Noms d'en-tête (p: 69)
  • 6.10.1 Inclusion conditionnelle (p: 165-169)
  • 6.10.2 Inclusion de fichiers source (p: 169-170)
  • Norme C17 (ISO/CEI 9899:2018) :
  • 6.10.2 Inclusion de fichiers source (p: 119-120)
  • Norme C11 (ISO/IEC 9899:2011) :
  • 6.10.2 Inclusion de fichiers source (p: 164-166)
  • Norme C99 (ISO/IEC 9899:1999) :
  • 6.10.2 Inclusion de fichiers source (p: 149-151)
  • Norme C89/C90 (ISO/IEC 9899:1990) :
  • 3.8.2 Inclusion de fichier source

Voir aussi

Une liste des fichiers d'en-tête de la bibliothèque standard C
Documentation C++ pour Inclusion de fichiers source