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.
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.
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.
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
#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 charis the natural fit for binary data;charmay be signed and show negative values for bytes above 127. Withint, 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
#embedentirely. Guard portable code with__has_embedand 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(orgnu23) is required.
Related
- #include, __has_include and feature tests, fopen()
- Tutorial: Modern C