path: root/xexsplit.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "XEXSPLIT" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools"
.SH NAME
xexsplit \- Split a multi-segment Atari 8-bit executable (XEX) into multiple single-segment files.
.\" RST source for xexsplit(1) man page. Convert with:
.
.\" rst2man.py xexsplit.rst > xexsplit.1
.
.\" rst2man.py comes from the SBo development/docutils package.
.
.\" TODO: add -n option (same as -v, but no output)?
.
.SH SYNOPSIS
.sp
\fIxexsplit\fP [\fI\-hv\fP] \fIinfile.xex\fP [\fIoutfile\-prefix\fP]
.SH DESCRIPTION
.sp
xexsplit reads an Atari executable (XEX/BIN/COM/etc)  from  \fIinfile\fP  and
writes  each  segment  to a separate file. To read from standard input,
infile may be omitted, or given as \fB\-\fP\&.
.sp
Output files are named \fBoutfile\-prefix.NNN.SSSS.EEEE\fP, where \fBNNN\fP  is
the segment  number  (decimal,  3 digits, with leading zeroes), \fBSSSS\fP
is the start address of the segment (4 digits, hex), and \fBEEEE\fP is the
end  address of the segment (4 digits, hex). If \fIoutfile\-prefix\fP is
omitted, the default prefix is \fBxexsplit.xex\fP\&.
.sp
Each output file is a valid single\-segment Atari executable,  including
the  required  \fI$FFFF\fP header. They may be joined back together (possibly
after being modified) with xexcat or plain old \fBcat\fP(1).
.SH OPTIONS
.INDENT 0.0
.TP
.B  \-h
Print a short help message and exit.
.TP
.B  \-v
Verbose operation. Each  segment\(aqs  information  is  printed  to
standard error, including start/end address and length.
.UNINDENT
.SH NOTES
.sp
The  terms  "Atari  executable", "binary load file", and "XEX file"
all refer to the same thing. Also, there is no difference between
Atari executables named with "XEX", "COM", "BIN", "EXE", etc. The
Atari and its DOS don\(aqt care about the names, only the contents.
.sp
It  is  not possible to use \fB\-\fP to write to standard output. This makes
sense, because there\(aqs no way to write multiple, separate files to stdout.
.sp
The  output  filenames  were chosen so they will sort in the order they
were created, when used with the shell\(aqs globbing. This means that  you
can join them back into a single valid XEX file with a command like:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cat prefix.* > joined.xex
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
or use \fBxexcat\fP(1) instead of \fBcat\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
xexcat \-o joined.xex prefix.*
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The Atari binary load format requires the \fI$FFFF\fP  header  only  for
the first  segment  in  a file. The second and subsequent segments may
also have a \fI$FFFF\fP header, but it\(aqs optional. \fBxexsplit\fP\(aqs output
files will always  have  the \fI$FFFF\fP header, regardless of whether
the segments in the original file had it or not (in fact, \fBxexsplit\fP
can  handle  an  invalid XEX  file  which is missing the initial $FFFF
header for the first seg‐ ment).
.sp
A segment starting at address \fB$02E2\fP contains  an  init  address.
During loading, Atari DOSes JSR to the init address immediately
after its segment has loaded. Init addresses are optinal; there\(aqs no
rule that  says that every file has to have one. It\(aqs also normal
and fairly common for there to be several init addresses in a
multi\-segment file. An init ad‐ dress segment is normally located
right after the code segment it\(aqs in‐ tended to run, but this is not
a requirement.
.sp
A segment starting at address \fB$02E0\fP contains a run  address.
After  all segments  have  been  loaded, Atari DOSes JSR to the run
address to run the program just loaded. The run address is optional;
a file containing no  run  address segment will simply be loaded into
memory and not executed (user will be returned  to  the  DOS  menu).
It\(aqs  legal  for  a multi\-segment  file  to contain multiple run
address segments, but only the last run address will actually be
used. Normally, there is only one run  address; if there are more than
one, only the last one is used.  The run address is normally the last
segment in the file, but this is not a requirement.
.sp
Attempting to run a single\-segment file consisting of a run or init
address only, will generally crash the Atari.
.sp
Some  Atari  executables contain raw blocks of data, which are meant
to be read into memory by the init  routine.  These  blocks  do  not
have start/end  address  headers, so \fBxexsplit\fP is unable to handle
them.  Raw data blocks usually occur in files created with "packer"
or  "compressor"  programs, or occasionally in other large programs
(Turbo BASIC is an example). Raw data blocks are generally found just
after an init address segment. If you have an executable that loads
just fine on a real Atari or emulator, but fails with \fBxexsplit\fP,
a raw data block is usually the reason why.
.\" other sections we might want, uncomment as needed.
.
.\" FILES
.
.\" =====
.
.\" ENVIRONMENT
.
.\" ===========
.
.\" EXIT STATUS
.
.\" ===========
.
.\" BUGS
.
.\" ====
.
.\" EXAMPLES
.
.\" ========
.
.SH COPYRIGHT
.sp
WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
.SH AUTHOR
.INDENT 0.0
.IP B. 3
Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
.UNINDENT
.SH SEE ALSO
.sp
\fBa8eol\fP(1),
\fBa8utf8\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBcart2xex\fP(1),
\fBdasm2atasm\fP(1),
\fBfenders\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1).
.sp
Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
.\" Generated by docutils manpage writer.
.