Version 0.4.00.4.0

1 files changed, 77 insertions, 0 deletions

diff --git a/man/mcpu-objcopy.1 b/man/mcpu-objcopy.1
new file mode 100644
index 0000000..d6efeac
--- /dev/null
+++ b/man/mcpu-objcopy.1
@@ -0,0 +1,77 @@
+.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)