path: root/xexcat.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 "XEXCAT" 1 "2024-07-21" "0.2.1" "Urchlay's Atari 8-bit Tools"
.SH NAME
xexcat \- Concatenate Atari 8-bit executables (XEX) into a single XEX file.
.\" RST source for xexcat(1) man page. Convert with:
.
.\" rst2man.py xexcat.rst > xexcat.1
.
.\" rst2man.py comes from the SBo development/docutils package.
.
.SH SYNOPSIS
.sp
\fBxexcat\fP [\fB\-hvc\fP] [\fB\-f\fP \fI1\fP | \fI2\fP] [\fB\-l\fP \fIaddress\fP [\fB\-r\fP \fIaddress\fP]  [\fB\-i\fP  \fIaddress\fP] [\fB\-o\fP  \fIoutfile.xex\fP] [\fIinfile.xex\fP] [\fIinfile.xex ...\fP]
.SH DESCRIPTION
.sp
\fBxexcat\fP reads one or more Atari executables (XEX/BIN/COM/etc),
or \fBdasm\fP(1) \fB\-f1\fP, \fB\-f2\fP files; it writes a single Atari
executable containing all the segments from all the input files to
\fIoutfile\fP\&.
.sp
To read from standard input, \fIinfile\fP may be omitted, or given as
\fB\-\fP\&. To write to standard output, \fB\-o\fP \fIoutfile\fP may be omitted,
or given as \fB\-o\-\fP\&.
.sp
The  output  file  is  a valid Atari executable, including the
required \fI$FFFF\fP header for the first segment. If there are multiple
segments, the second and subsequent segments will not have the
optional \fI$FFFF\fP header.
.SH OPTIONS
.INDENT 0.0
.TP
.B  \-c
Check only; no output file  is  written.  Equivalent  to \fB\-v \-o /dev/null\fP\&.
.TP
.BI \-o \ outfile
Write  output  xex file to outfile. Default is to write to standard output.
.TP
.BI \-l \ address
Force the output file\(aqs load address to address. This  only
affects the first segment of the output file.
.TP
.BI \-i \ address
Force  the  output file\(aqs first init address (if present) to
\fIaddress\fP\&.  This \fIonly\fP affects the \fBfirst\fP init address segment of  the
output  file. Further init address segments in the input will be
left unmodified.  If \fIaddress\fP is 0, the first init  segment  will
be  removed (0 means "none", not "init at address 0").  This option
does nothing if none of the input files  contain  init  address
segments.
.TP
.BI \-r \ address
Force  the  output  file\(aqs run address to \fIaddress\fP\&. If \fIaddress\fP
is not 0, all run address segments from all input files will be
ignored,  and  a  new run address segment will be constructed
with the given \fIaddress\fP and appended to the output.  If \fIaddress\fP
is  0, all run addresses from all input files are ignored,
and the output file will not contain a run address segment
at all.  Such  a file can still be loaded from DOS, but it will
not execute (user will be returned to the DOS menu).
.TP
.B  \-a
"Automatic" run address: Force the output file\(aqs run address to the
load address of the first segment.
.UNINDENT
.INDENT 0.0
.TP
.B \fB\-f\fP \fI1\fP | \fI2\fP
Input file(s) are \fBdasm\fP(1) object files created by \fB\-f1\fP or
\fB\-f2\fP options, rather than .xex files. \fB\-f1\fP files can\(aqt contain
run or init addresses, so you\(aqll probably want to use \fB\-r\fP,
\fB\-a\fP, and/or \fB\-i\fP with these. \fB\-f2\fP files can contain run or
init addresses. The output file is still a .xex file. Note that this
flag affects all input files: if you\(aqre trying to join a \fBdasm\fP
file with a .xex file, it must be done in two steps: convert the
\fBdasm\fP file to a .xex, then combine the two .xex files with a
second run of \fBxexcat\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B  \-1
Output file will be an Atari DOS 1.0 executable. If there are any init
addresses in the input, you will be warned about them, since DOS 1.0
doesn\(aqt support the init mechanism.
.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
It is possible to join multiple Atari  executables  together  with
the standard \fBcat\fP(1) command. However, \fBxexcat\fP is always guaranteed to
produce a valid Atari binary load file (or an empty file, if all input
files  are invalid), which is not the case for \fBcat\fP\&.
.sp
When  writing  to  standard  output, \fBxexcat\fP will refuse to write
binary data to the user\(aqs terminal.
.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. \fBxexcat\fP\(aqs output file
will  always  have  the \fI$FFFF\fP header for the first segment, and no
\fI$FFFF\fP header for further segments, regardless of whether the segments
in  the  input files  had  it  or  not (in fact, \fBxexcat\fP can handle
an invalid XEX file which is missing the initial $FFFF header for the
first segment).
.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 \fBxexcat\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 \fBxexcat\fP,
a raw data block is usually the reason why.
.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
The \fBdasm\fP \fB\-f1\fP file format is also the native binary format for
the Commodore 8\-bit machines (PET, 64, etc), so you can use \fBxexcat\fP
to load Commodore code & data into an Atari... though of course the
code won\(aqt run correctly on the Atari.
.SH EXIT STATUS
.sp
Exit status is zero for success, non\-zero for failure.
.\" 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
\fBa8cat\fP(1),
\fBa8eol\fP(1),
\fBa8xd\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBbas2aplus\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBcxrefbas\fP(1),
\fBdasm2atasm\fP(1),
\fBdiffbas\fP(1),
\fBdumpbas\fP(1),
\fBf2toxex\fP(1),
\fBfenders\fP(1),
\fBlistbas\fP(1),
\fBprotbas\fP(1),
\fBrenumbas\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBunprotbas\fP(1),
\fBvxrefbas\fP(1),
\fBwhichbas\fP(1),
\fBxex1to2\fP(1),
\fBxexamine\fP(1),
\fBxexcat\fP(1),
\fBxexsplit\fP(1),
\fBxfd2atr\fP(1),
\fBxex\fP(5),
\fBatascii\fP(7).
.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.
.