NAME

       r_egg — radare2 egg shellcode generation library

SYNOPSIS

       #include <r_egg.h>

DESCRIPTION

       The  r_egg  library  provides  shellcode  generation  capabilities  for  radare2, allowing users to write
       shellcode in a high-level language and compile it to machine code. It supports multiple architectures and
       provides a framework for creating, compiling, and executing shellcode.

       The core structure is REgg, which manages source code, compiled binary, assembler,  syscall  information,
       and language parsing.

INITIALIZATION

       This  section  describes functions to create, initialize and free an REgg context and contains helpers to
       (re)configure the embedded language parser and state used during compilation.  REgg * r_egg_new(void)

       Creates a new egg context with default settings.

       void r_egg_free(REgg *egg)

       Frees all resources associated with the egg context.  Pp void r_egg_reset(REgg *egg)

       Resets the egg context state so it can be reused for a new compilation.

       char * r_egg_tostring(REgg *egg)

       Returns a textual representation of the egg internal state (for debugging).

       void r_egg_lang_init(REgg *egg)

       Initializes the embedded language parser state (`egg->lang`).

       void r_egg_lang_free(REgg *egg)

       Frees resources allocated by the embedded language parser.

       bool r_egg_setup(REgg *egg, const char *arch, int bits, int endian, const char *os)

       Configures the egg context for the specified architecture, bitness, endianness, and operating system.

LOADING CODE

       Functions to load egg source from strings or files,  append  fragments,  and  manage  include  paths  and
       ancillary source used during compilation.  void r_egg_load(REgg *egg, const char *code, int format)

       Loads source code into the egg context. `format` indicates input style (egg/c).

       void r_egg_append(REgg *egg, const char *src)

       Appends additional source code to the egg context.

COMPILATION

       Compilation  is  generally  a  two-step  process:  parse/compile  the  egg  language into an intermediate
       representation, then assemble that IR into machine code.  This section lists helpers for both stages  and
       utilities to obtain assembly listings for inspection.  bool r_egg_compile(REgg *egg)

       Compiles the loaded source code into intermediate representation.

       bool r_egg_assemble(REgg *egg)

       Assembles the compiled code into machine code.

       bool r_egg_assemble_asm(REgg *egg, char **asm_list)

       Assembles the code and returns the assembly listing in `asm_list`.

EXECUTION

       Functions  that  run the generated shellcode either directly or via a ROP execution helper; frontends use
       these to invoke or emulate the generated payload.  int r_egg_run(REgg *egg)

       Executes the compiled shellcode.

       int r_egg_run_rop(REgg *egg)

       Executes the shellcode using ROP (Return-Oriented Programming) techniques.

OUTPUT

       Functions to access compilation results: the raw binary buffer, the original source text, and the emitted
       assembly listing. These are commonly used by frontends to print, save or  further  process  the  produced
       artifacts.  RBuffer * r_egg_get_bin(REgg *egg)

       Returns the compiled binary code as a buffer.

       char * r_egg_get_source(REgg *egg)

       Returns the source code.

       char * r_egg_get_assembly(REgg *egg)

       Returns the assembly representation of the compiled code.

SYSCALLS

       Helpers  to insert syscall invocations and to manage syscall-related language state (argument marshaling,
       syscall table entries and emitted code).  void r_egg_syscall(REgg *egg, const char *arg, ...)

       Adds a syscall instruction to the shellcode.

MEMORY MANAGEMENT

       Functions to reserve and manipulate data used by generated code: allocate space, place strings and manage
       small data patches emitted into the output buffer.  void r_egg_alloc(REgg *egg, int n)

       Allocates memory in the shellcode.

CONTROL FLOW

       Labeling, branching and conditional helpers used by the egg language to implement control flow constructs
       such as labels, if/while blocks and simple arithmetic operations.  void r_egg_label(REgg *egg, const char
       *name)

       Defines a label in the shellcode.

       void r_egg_if(REgg *egg, const char *reg, char cmp, int v)

       Adds a conditional statement.

RAW CODE

       Low-level helpers to insert raw bytes or preassembled snippets directly into the output buffer for  cases
       where  the  high-level  language  cannot express a pattern or when hand-crafted machine code is required.
       bool r_egg_raw(REgg *egg, const ut8 *b, int len)

       Inserts raw binary code into the shellcode.

ENCODING

       Encoder and shellcode-template helpers. Encoders  transform  the  produced  binary  (for  obfuscation  or
       packing)  while  shellcode  templates  provide parameterizable payloads and generators that frontends may
       select.  bool r_egg_encode(REgg *egg, const char *name)

       Applies an encoder to the shellcode.

       bool r_egg_shellcode(REgg *egg, const char *name)

       Generates shellcode using a specific shellcode template.

PATCHING

       Binary patching helpers to apply small modifications to the compiled output (bytes, words,  qwords).  The
       CLI uses these to apply user-specified patches before finalizing output.  bool r_egg_patch(REgg *egg, int
       off, const ut8 *b, int l)

       Patches the compiled binary at the specified offset. Use `-1` for append.

PLUGINS

       The  plugin  framework  used  to  extend r_egg with shellcode generators and encoders. Hosts discover and
       register plugin implementations which are then invoked  during  compilation  or  encoding  phases.   bool
       r_egg_plugin_add(REgg *a, REggPlugin *plugin)

       Adds an egg plugin (encoder or shellcode generator).

       bool r_egg_plugin_remove(REgg *a, REggPlugin *plugin)

       Removes an egg plugin.

OPTIONS

       Key/value  configuration  used  to  control compilation and encoding behavior (selected encoder, padding,
       chosen shellcode template and auxiliary keys used by plugins).  void  r_egg_option_set(REgg  *egg,  const
       char *k, const char *v)

       Sets an option for the egg context.

       char * r_egg_option_get(REgg *egg, const char *k)

       Gets an option value from the egg context.

INCLUDES

       Include helpers to load files or strings (for example C headers or inline code) referenced by egg source.
       Also  contains  helpers to manage include search paths used by the preprocessor.  bool r_egg_include(REgg
       *egg, const char *file, int format)

       Includes a file in the egg compilation.

       bool r_egg_include_str(REgg *egg, const char *arg)

       Includes a string in the egg compilation.

       void r_egg_lang_include_path(REgg *egg, const char *path)

       Adds an include path used by the egg preprocessor.

       void r_egg_lang_include_init(REgg *egg)

       Initializes include-related state (called at setup time by hosts).

FINALIZATION

       Finalizers  and  convenience  helpers  called  after  compilation  to   finish   transformations,   apply
       padding/encoders and release temporary resources.  void r_egg_finalize(REgg *egg)

       Finalizes the egg compilation process.

       void r_egg_printf(REgg *egg, const char *fmt, ...)

       Printf-style  helper  to append formatted text to the current egg output (used by emitters/plugins during
       code generation).

       void r_egg_option_set(REgg *egg, const char *k, const char *v)

       Helper noted above; kept here to emphasize lifecycle usage by frontends.

EXAMPLES

       Basic shellcode generation:

             REgg *egg = r_egg_new();
             r_egg_setup(egg, "x86", 32, 0, "linux");
             r_egg_load(egg, "write(1,
             r_egg_compile(egg);
             r_egg_assemble(egg);
             RBuffer *bin = r_egg_get_bin(egg);

       Using syscalls:

             r_egg_syscall(egg, "exit", 0);

       Adding raw code:

             ut8 code[] = {0x90, 0x90}; // NOP NOP
             r_egg_raw(egg, code, 2);

SEE ALSO

       r_asm(3), r_syscall(3)

Debian                                         September 20, 2025                                       R_EGG(3)