Skip to content
Tutorials Center
My learning

Topics

C Reference ยท Preprocessor

The #embed directive

Reference for the C23 #embed directive: turn a binary or text file into a comma-separated list of byte values at compile time, with limit, prefix and suffix.

#embed is a C23 directive that replaces itself with the bytes of a file, written as a comma-separated list of integer constants. Put it inside an array initializer and the file's contents become a compile-time array: an icon, a font, a shader, a certificate, a default configuration. It replaces the old tricks of running xxd -i or the assembler's .incbin.

The array has exactly as many elements as the file has bytes, and the compiler reads the file once at build time. At run time there is no file access and nothing to ship alongside the program.

C
static const unsigned char logo[] = {
#embed "logo.png"
};

Try it

On our runner, GCC 15.2 in C23 mode accepts #embed. The examples embed the program's own source, main.c, so they work without any extra file. In your own project you would name a data file instead.

C Embedding the first bytes of a file

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

C suffix, if_empty and __has_embed

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Syntax

C
#embed "resource" embed-parameters
#embed <resource> embed-parameters
__has_embed ( "resource" embed-parameters )
Parameter Description
limit(n) Use at most the first n bytes. Essential for infinite resources such as /dev/urandom.
prefix(tokens) Tokens placed before the data, only if the data is non-empty.
suffix(tokens) Tokens placed after the data, only if the data is non-empty.
if_empty(tokens) Tokens used instead of the data when the resource is empty.
__has_embed Evaluates to __STDC_EMBED_FOUND__ (non-empty), __STDC_EMBED_EMPTY__ or __STDC_EMBED_NOT_FOUND__.

Result: a list of integer constant expressions, one per byte (each in 0 to UCHAR_MAX, when the element type is unsigned char). Stored in a wider element type, each byte becomes one element.

Errors: an unreadable resource is a fatal error. A missing file found through __has_embed is not an error; it just evaluates to __STDC_EMBED_NOT_FOUND__.

Usage notes

  • The name search works like #include: quotes search relative to the current source file first, angle brackets use the include path (-I).
  • Pick the element type deliberately. unsigned char is the natural fit for binary data; char may be signed and show negative values for bytes above 127. With int, every byte occupies four bytes of the array.
  • Add a NUL with suffix(, 0) when the content is text you want as a C string.
  • The embedded file is a build input. Add it to your build system's dependency list so the object is rebuilt when the file changes.
  • Large files: fast in GCC 15 and Clang 19+, but older compilers lack #embed entirely. Guard portable code with __has_embed and fall back to a generated array.
  • Only works at translation time. For data that changes after the build, read the file normally (see fopen()).
  • Not available in C17 or earlier modes; -std=c23 (or gnu23) is required.