Binary Resource Inclusion (The C Preprocessor)

## 8 Binary Resource Inclusion ¶

The ‘`#embed`’ directive as specified in the C23 standard allows efficient inclusion of binary data, usually in initializers of arrays. GCC supports this directive in C23 mode and as an extension in older C versions and in C++.

Similarly to the ‘`#include`’ directive (see Include Syntax) the first argument of the directive is a filename in the same forms as ‘`#include`’.

`#embed <file>`

  If file is an absolute filename, this includes the mentioned file, otherwise searches it in directories specified by the `--embed-dir=` command-line option for the file.

`#embed "file"`

  This variant searches file in the same directory as the source file which uses the `#embed` directive and only if not found there continues searching directories specified by the `--embed-dir=` command-line option.

The `#embed` directive is expanded as if it was a sequence of integer literals from 0 to `UCHAR_MAX` separated by commas, e.g. `#embed __FILE__ limit(4)` could act as if it expanded to `35,101,109,98`. No character set conversion is performed.

Optional embed parameters can be specified after the required filename argument. There are either standard attributes, specified by an identifier or identifier prefixed and suffixed by 2 underscores (both treated the same), followed by parameter argument in parentheses, like `#embed "foo.dat" limit(1) __prefix__(32, ) suffix(, 0)` with currently supported standard parameters `limit`, `prefix`, `suffix` and `if_empty`, or implementation defined parameters specified by a unique vendor prefix followed by `::` followed by name of the parameter. GCC uses the `gnu` prefix for vendor parameters and currently supports the `gnu::offset` and `gnu::base64` parameters.

The `limit` parameter argument is a constant expression which specifies the maximum number of bytes included by the directive, `prefix` and `suffix` arguments are balanced token sequences which are prepended and appended to the integer literal sequence if that sequence is not empty and `if_empty` argument is balanced token sequence which is used as expansion for `#embed` directive if the resource is empty.

The `gnu::offset` parameter argument is a constant expression which specifies how many bytes to skip from the start of the resource. `limit` is then counted from that position.

The `gnu::base64` parameter argument is a possibly concatenated character string literal with base64 encoded data. See https://datatracker.ietf.org/doc/html/rfc4648#section-4. There should be no newlines in the string literal and because this parameter is meant namely for use by the preprocessor itself, there is no support for any escape sequences in the string literal argument. If `gnu::base64` parameter is specified, the `limit` and `gnu::offset` parameters should not be specified and the filename should be always `"."`. Instead of reading a file the directive will decode the base64 encoded data and use that as the data to include.

The `#embed` directive is not supported in the Traditional Mode (see Traditional Mode).