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).