Namespaces
Variants

Source file inclusion

From cppreference.net
C
C language
Preprocessor

Incluye otro archivo de origen en el archivo de origen actual en la línea inmediatamente posterior a la directiva.

Contenidos

Sintaxis

#include < h-char-sequence > new-line (1)
#include " q-char-sequence " new-line (2)
#include pp-tokens new-line (3)
__has_include ( " q-char-sequence " )
__has_include ( < h-char-sequence > ) 		(4) (desde C23)
__has_include ( string-literal )
__has_include ( < h-pp-tokens > ) 		(5) (desde C23)
1) Busca un encabezado identificado únicamente por h-char-sequence y reemplaza la directiva por el contenido completo del encabezado.
2) Busca un archivo fuente identificado por q-char-sequence y reemplaza la directiva por el contenido completo del archivo fuente. Puede recurrir a (1) y tratar q-char-sequence como un identificador de cabecera.
3) Si ni (1) ni (2) coinciden, pp-tokens sufrirán reemplazo de macro. La directiva después del reemplazo se intentará hacer coincidir con (1) o (2) nuevamente.
4) Verifica si un archivo de cabecera o fuente está disponible para inclusión.
5) Si (4) no coincide, h-pp-tokens sufrirá reemplazo de macro. La directiva después del reemplazo se intentará hacer coincidir con (4) nuevamente.
new-line - El carácter de nueva línea
h-char-sequence - Una secuencia de uno o más h-char s, donde la aparición de cualquiera de los siguientes causa comportamiento indefinido:
  • el carácter '
  • el carácter "
  • el carácter \
  • la secuencia de caracteres //
  • la secuencia de caracteres /*
h-char - Cualquier miembro del juego de caracteres fuente excepto nueva línea y >
q-char-sequence - Una secuencia de uno o más q-char s, donde la aparición de cualquiera de los siguientes causa comportamiento indefinido:
  • el carácter '
  • el carácter \
  • la secuencia de caracteres //
  • la secuencia de caracteres /*
q-char - Cualquier miembro del juego de caracteres fuente excepto nueva línea y "
pp-tokens - Una secuencia de uno o más tokens de preprocesamiento
string-literal - Un literal de cadena
h-pp-tokens - Una secuencia de uno o más tokens de preprocesamiento excepto >

Explicación

1) Busca el archivo identificado por h-char-sequence de manera definida por la implementación. La intención de esta sintaxis es buscar los archivos bajo control de la implementación. Las implementaciones típicas solo buscan en directorios de inclusión estándar. La biblioteca estándar de C está implícitamente incluida en estos directorios de inclusión estándar. Los directorios de inclusión estándar generalmente pueden ser controlados por el usuario mediante opciones del compilador.
2) Busca el archivo identificado por q-char-sequence de manera definida por la implementación. La intención de esta sintaxis es buscar archivos que no están controlados por la implementación. Las implementaciones típicas primero buscan en el directorio donde reside el archivo actual y, solo si no se encuentra el archivo, buscan en los directorios de inclusión estándar como con (1) .
3) Los tokens de preprocesamiento después de include en la directiva se procesan tal como en texto normal (es decir, cada identificador actualmente definido como nombre de macro se reemplaza por su lista de reemplazo de tokens de preprocesamiento). La directiva resultante después de todos los reemplazos debe coincidir con una de las dos formas anteriores. El método mediante el cual una secuencia de tokens de preprocesamiento entre < y > par de tokens de preprocesamiento o un par de caracteres " se combina en un único token de preprocesamiento de nombre de cabecera está definido por la implementación.
4) El archivo de cabecera o fuente identificado por h-char-sequence o q-char-sequence se busca como si esa secuencia de tokens de preprocesamiento fuera los pp-tokens en la sintaxis (3) , excepto que no se realiza ninguna expansión de macros adicional. Si dicha directiva no cumpliera los requisitos sintácticos de una directiva #include , el programa está mal formado. La expresión __has_include se evalúa como 1 si la búsqueda del archivo fuente tiene éxito, y como ​ 0 ​ si la búsqueda falla.
5) Esta forma se considera solo si la sintaxis (4) no coincide, en cuyo caso los tokens de preprocesamiento se procesan igual que en el texto normal.

En caso de que el archivo no se encuentre, el programa está mal formado.

__has_include puede expandirse en la expresión de #if y #elif . Es tratado como una macro definida por #ifdef , #ifndef , #elifdef , #elifndef y defined pero no puede utilizarse en ningún otro lugar.

(desde C23)

Notas

Las implementaciones típicas solo buscan en los directorios de inclusión estándar para la sintaxis (1). La biblioteca estándar de C está implícitamente incluida en estos directorios de inclusión estándar. Los directorios de inclusión estándar generalmente pueden ser controlados por el usuario mediante opciones del compilador.

La intención de la sintaxis (2) es buscar los archivos que no están controlados por la implementación. Las implementaciones típicas primero buscan en el directorio donde reside el archivo actual y luego recurren a (1) .

Cuando se incluye un archivo, es procesado por las fases de traducción 1-4, lo que puede incluir, de forma recursiva, la expansión de las directivas anidadas #include , hasta un límite de anidamiento definido por la implementación. Para evitar la inclusión repetida del mismo archivo y la recursión infinita cuando un archivo se incluye a sí mismo, quizás de forma transitiva, comúnmente se utilizan header guards : todo el encabezado se envuelve en 

#ifndef FOO_H_INCLUDED /* cualquier nombre mapeado únicamente al nombre del archivo */
#define FOO_H_INCLUDED
// el contenido del archivo está aquí
#endif

Muchos compiladores también implementan el no estándar pragma #pragma once con efectos similares: desactiva el procesamiento de un archivo si el mismo archivo (donde la identidad del archivo se determina de manera específica del sistema operativo) ya ha sido incluido.

Un resultado de __has_include de 1 solo significa que existe un archivo de cabecera o fuente con el nombre especificado. No significa que el archivo de cabecera o fuente, cuando se incluya, no causará un error o contendrá algo útil.

Ejemplo

Esta sección está incompleta
Razón: sin ejemplo

Referencias

  • Estándar C23 (ISO/IEC 9899:2024):
  • 6.4.7 Nombres de cabecera (p: 69)
  • 6.10.1 Inclusión condicional (p: 165-169)
  • 6.10.2 Inclusión de archivos fuente (p: 169-170)
  • Estándar C17 (ISO/IEC 9899:2018):
  • 6.10.2 Inclusión de archivos fuente (p: 119-120)
  • Estándar C11 (ISO/IEC 9899:2011):
  • 6.10.2 Inclusión de archivos fuente (p: 164-166)
  • Estándar C99 (ISO/IEC 9899:1999):
  • 6.10.2 Inclusión de archivos fuente (p: 149-151)
  • Estándar C89/C90 (ISO/IEC 9899:1990):
  • 3.8.2 Inclusión de archivos fuente

Véase también

Una lista de archivos de cabecera de la Biblioteca Estándar de C
Documentación de C++ para Inclusión de archivos fuente