SHELF(1)                    General Commands Manual                   SHELF(1)

NAME
       shelf - toolchain-independent ELF object generator

SYNOPSIS
       shelf PLAN [PLAN_ARGUMENTS]

DESCRIPTION
       shelf is a standalone shell script designed to generate custom ELF (Ex‐
       ecutable and Linkable Format) objects without the requirement of an ex‐
       isting  toolchain intended for the desired target.  It operates in two-
       passes: the first pass calculates offsets and sizes, while  the  second
       pass performs the final object output to stdout.

       The  generator's  structure  is  defined by plan files, which are shell
       script plug-ins that use shelf directives to describe the  ELF  layout:
       headers, sections, and segments.  While intended for bootstrapping exe‐
       cutables and relocatable objects, this level of  control  also  enables
       the  generation  of  auxiliary symbol objects for debugging and reverse
       engineering purposes.

AMD64 LINUX PLANS
       amd64/linux/exec.plan TEXT-FILE DATA-FILE BSS-SIZE
              Generates a standalone  Linux/amd64  executable  (ET_EXEC)  with
              PT_LOAD program headers.  It utilizes a fixed Virtual Memory Ad‐
              dress (VMA) base, starting at 0x40000000.  Users  should  ensure
              that  the  machine code in the TEXT-FILE is position-independent
              or specifically assembled to run at  the  defined  VMA  base  to
              avoid  segmentation  faults.  When generating an executable, the
              entry point is automatically set to the start  of  the  provided
              TEXT-FILE.

       amd64/linux/flat.plan TEXT-FILE
              Generates  a minimal standalone Linux/amd64 executable (ET_EXEC)
              containing only a single code segment.  Unlike  exec.plan,  this
              plan  generates  no  section  headers and omits data or BSS seg‐
              ments.  It utilizes a fixed Virtual Memory Address  (VMA)  base,
              starting  at 0x40000000.  The entry point is set to the start of
              the provided TEXT-FILE.

       amd64/linux/reloc.plan TEXT-FILE DATA-FILE BSS-SIZE
              Generates a relocatable object file (ET_REL) with  a  functional
              symbol table and section headers.

       amd64/linux/symbols.plan SYMBOL-FILE
              Generates  an  ET_REL object containing only symbol metadata for
              use as split debug info, for example, with gdb's add-symbol-file
              command.  SYMBOL-FILE  is  expected to be a text file where each
              line defines a symbol in the following format: OFFSET LABEL

AMD64 LINUX EXECUTABLE EXAMPLE
       $ printf "\x6a\x01\x5f\x6a\x3c\x58\x0f\x05" > /tmp/false.obj
       $ shelf /usr/local/share/shelf/amd64/linux/exec.plan \
               /tmp/false.obj /dev/null 0 > /tmp/false

       $ readelf -h /tmp/false
       ELF Header:
         Magic:   7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00
         Class:                             ELF64
         Data:                              2's complement, little endian
         Version:                           1 (current)
         OS/ABI:                            UNIX - System V
         ABI Version:                       0
         Type:                              EXEC (Executable file)
         Machine:                           Advanced Micro Devices X86-64
         Version:                           0x1
         Entry point address:               0x40001000
         Start of program headers:          64 (bytes into file)
         Start of section headers:          12320 (bytes into file)
         Flags:                             0x0
         Size of this header:               64 (bytes)
         Size of program headers:           56 (bytes)
         Number of program headers:         3
         Size of section headers:           64 (bytes)
         Number of section headers:         5
         Section header string table index: 4

       $ chmod 755 /tmp/false
       $ strace -e trace=all /tmp/false
       execve("/tmp/false", ["/tmp/false"], 0x7ffe5f998de0 /* 42 vars */) = 0
       exit(1)                                 = ?
       +++ exited with 1 +++

AMD64 LINUX SYMBOLS EXAMPLE
       $ cat > /tmp/demo.map << "EOF"
       00000000 Magic
       00000001 Start
       0000004a Exit
       EOF

       $ shelf /usr/local/share/shelf/amd64/linux/symbols.plan \
               /tmp/demo.map > /tmp/demo.sym

       $ readelf -hs /tmp/demo.sym
       ELF Header:
         Magic:   7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00
         Class:                             ELF64
         Data:                              2's complement, little endian
         Version:                           1 (current)
         OS/ABI:                            UNIX - System V
         ABI Version:                       0
         Type:                              REL (Relocatable file)
         Machine:                           Advanced Micro Devices X86-64
         Version:                           0x1
         Entry point address:               0x0
         Start of program headers:          0 (bytes into file)
         Start of section headers:          224 (bytes into file)
         Flags:                             0x0
         Size of this header:               64 (bytes)
         Size of program headers:           0 (bytes)
         Number of program headers:         0
         Size of section headers:           64 (bytes)
         Number of section headers:         5
         Section header string table index: 4

       Symbol table '.symtab' contains 4 entries:
          Num:    Value          Size Type    Bind   Vis      Ndx Name
            0: 0000000000000000     0 NOTYPE  LOCAL  DEFAULT  UND
            1: 0000000000000000     0 FUNC    GLOBAL DEFAULT    1 Magic
            2: 0000000000000001     0 FUNC    GLOBAL DEFAULT    1 Start
            3: 000000000000004a     0 FUNC    GLOBAL DEFAULT    1 Exit

X86 LINUX PLANS
       x86/linux/exec.plan TEXT-FILE DATA-FILE BSS-SIZE
              Generates  a  standalone  Linux/x86  executable  (ET_EXEC)  with
              PT_LOAD program headers.  It utilizes a fixed Virtual Memory Ad‐
              dress (VMA) base, starting at 0x08048000.  Users  should  ensure
              that  the  machine code in the TEXT-FILE is position-independent
              or specifically assembled to run at  the  defined  VMA  base  to
              avoid  segmentation  faults.  When generating an executable, the
              entry point is automatically set to the start  of  the  provided
              TEXT-FILE.

       x86/linux/flat.plan TEXT-FILE
              Generates  a  minimal  standalone Linux/x86 executable (ET_EXEC)
              containing only a single code segment.  Unlike  exec.plan,  this
              plan  generates  no  section  headers and omits data or BSS seg‐
              ments.  It utilizes a fixed Virtual Memory Address  (VMA)  base,
              starting  at 0x08048000.  The entry point is set to the start of
              the provided TEXT-FILE.

       x86/linux/reloc.plan TEXT-FILE DATA-FILE BSS-SIZE
              Generates a relocatable object file (ET_REL) with  a  functional
              symbol table and section headers.

       x86/linux/symbols.plan SYMBOL-FILE
              Generates  an  ET_REL object containing only symbol metadata for
              use as split debug info, for example, with gdb's add-symbol-file
              command.   SYMBOL-FILE  is expected to be a text file where each
              line defines a symbol in the following format: OFFSET LABEL

X86 LINUX EXECUTABLE EXAMPLE
       $ printf "\x6a\x01\x5b\x6a\x01\x58\xcd\x80" > /tmp/false.obj
       $ shelf /usr/local/share/shelf/x86/linux/exec.plan \
               /tmp/false.obj /dev/null 0 > /tmp/false

       $ readelf -hs /tmp/false
       ELF Header:
         Magic:   7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00
         Class:                             ELF32
         Data:                              2's complement, little endian
         Version:                           1 (current)
         OS/ABI:                            UNIX - System V
         ABI Version:                       0
         Type:                              EXEC (Executable file)
         Machine:                           Intel 80386
         Version:                           0x1
         Entry point address:               0x8049000
         Start of program headers:          52 (bytes into file)
         Start of section headers:          12320 (bytes into file)
         Flags:                             0x0
         Size of this header:               52 (bytes)
         Size of program headers:           32 (bytes)
         Number of program headers:         3
         Size of section headers:           40 (bytes)
         Number of section headers:         5
         Section header string table index: 4

       $ chmod 755 /tmp/false
       $ strace -e trace=all /tmp/false
       execve("/tmp/false", ["/tmp/false"], 0x7ffce686bf20 /* 39 vars */) = 0
       [ Process PID=9079 runs in 32 bit mode. ]
       exit(1)                                 = ?
       +++ exited with 1 +++

X86 LINUX SYMBOLS EXAMPLE
       $ cat > /tmp/demo.map << "EOF"
       00000000 Magic
       00000001 Start
       0000004a Exit
       EOF

       $ shelf /usr/local/share/shelf/x86/linux/symbols.plan \
               /tmp/demo.map > /tmp/demo.sym

       $ readelf -hs /tmp/demo.sym
       ELF Header:
         Magic:   7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00
         Class:                             ELF32
         Data:                              2's complement, little endian
         Version:                           1 (current)
         OS/ABI:                            UNIX - System V
         ABI Version:                       0
         Type:                              REL (Relocatable file)
         Machine:                           Intel 80386
         Version:                           0x1
         Entry point address:               0x0
         Start of program headers:          0 (bytes into file)
         Start of section headers:          176 (bytes into file)
         Flags:                             0x0
         Size of this header:               52 (bytes)
         Size of program headers:           0 (bytes)
         Number of program headers:         0
         Size of section headers:           40 (bytes)
         Number of section headers:         5
         Section header string table index: 4

       Symbol table '.symtab' contains 4 entries:
          Num:    Value  Size Type    Bind   Vis      Ndx Name
            0: 00000000     0 NOTYPE  LOCAL  DEFAULT  UND
            1: 00000000     0 FUNC    GLOBAL DEFAULT    1 Magic
            2: 00000001     0 FUNC    GLOBAL DEFAULT    1 Start
            3: 0000004a     0 FUNC    GLOBAL DEFAULT    1 Exit

STANDARDS
       shelf is a generic ELF generation engine.  The specific  standards  and
       ABI compliance are determined by the chosen plan file.

       amd64/linux  plans  target the ELF-64 format as defined in the System V
       ABI for amd64.  These plans utilize ELFDATA2LSB (little-endian)  encod‐
       ing and EM_X86_64 machine types.

       x86/linux plans target the ELF-32 format as defined in the System V ABI
       for Intel 386.  These plans utilize ELFDATA2LSB (little-endian)  encod‐
       ing and EM_386 machine types.

SEE ALSO
       gdb(1), mle(1), mli-amd64(1), mli-x86(1), readelf(1), elf(5),

AUTHOR
       Justin Swartz <justin.swartz@risingedge.co.za>

COPYRIGHT
       Copyright (c) 2024-2026 Justin Swartz.

       This software is distributed under the 2-Clause BSD License.  Redistri‐
       bution and use in source and binary forms, with  or  without  modifica‐
       tion, are permitted provided that the license conditions are met.

SHELF                              May 2026                           SHELF(1)
