.TH MCPU-OBJCOPY 1 "October 2026" "LibMCPU" "User Commands"

.SH NAME
mcpu-objcopy \- safely copy and edit MCPU MELF metadata
.SH SYNOPSIS
.B mcpu-objcopy
.RI [ options ] " INPUT OUTPUT"
.SH DESCRIPTION
.B mcpu-objcopy
is a MELF-to-MELF structural copier and metadata editor.  It is intentionally
not a ROM-image conversion tool: there are no flat binary, Intel HEX, S-record,
VMA/LMA, start-address or section-flag conversion modes.
.PP
The editor protects the frozen MELF ABI-v3 execution contract.  Runtime-visible
allocated sections, dynamic-linking metadata, runtime relocations and MCPU
target/lifecycle data cannot be removed, renamed or updated through the safe
metadata interface.
.SH OPTIONS
.TP
.BI -j " NAME"
.TQ
.BI --only-section= NAME
Copy only named sections.  Repeatable.  The operation is rejected if filtering
would discard runtime-visible, dynamic-linking or ET_REL link-critical data.
.TP
.BI -R " NAME"
.TQ
.BI --remove-section= NAME
Remove a safe non-runtime section.
.TP
.BI --dump-section= NAME=FILE
Write section contents to FILE.  For archive input this operation is rejected
as ambiguous because one destination does not identify an archive member.
.TP
.BI --add-section= NAME=FILE
Add a new non-allocated SHT_PROGBITS metadata section whose contents are read
from FILE.  Reserved runtime section names are rejected.
.TP
.BI --update-section= NAME=FILE
Replace contents of a safe non-allocated SHT_PROGBITS section.
.TP
.BI --rename-section= OLD=NEW
Rename a safe non-allocated section.  Reserved runtime names are protected.
.TP
.B --help
Display help and exit.
.TP
.B --version
Display the program name, MCPU toolchain identity and version, then exit.
.TP
.B --dump-version
Display only the MCPU package version number and exit.
.SH STRUCTURAL INVARIANTS
Metadata-only edits rebuild .shstrtab and remap affected section references,
including retained symbol st_shndx values, while preserving the allocated
image and program headers.  The non-allocated metadata tail may be repacked.
.SH ARCHIVES
Deterministic MCPU archives are transformed member-by-member and keep their
archive symbol-index semantics.  Unknown non-MELF archive members are preserved
according to the archive editor policy.
.SH EXIT STATUS
Zero on success; nonzero on invalid operations, safety-policy violations,
malformed input or I/O error.
.SH EXAMPLES
.nf
mcpu-objcopy input.o output.o
mcpu-objcopy --add-section=.note.build=build.txt input.o output.o
mcpu-objcopy --update-section=.note.build=new.txt input.o output.o
mcpu-objcopy --rename-section=.note.build=.note.release input.o output.o
mcpu-objcopy -R .note.release input.o output.o
mcpu-objcopy --dump-section=.data=data.bin input.o output.o
.fi
.SH SEE ALSO
.BR mcpu-strip (1),
.BR mcpu-objdump (1),
.BR mcpu-readelf (1),
.BR libmcpu (7)