1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
.\" 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-04-26" "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
\fIxexcat\fP [\fI\-hvc\fP] [\-l \fIaddress\fP [\-r \fIaddress\fP] [\-i \fIaddress\fP] [\-o \fIoutfile.xex\fP] [\fIinfile.xex\fP] [\fIinfile.xex ...\fP]
.SH DESCRIPTION
.sp
\fBxexcat\fP reads one or more Atari executables (XEX/BIN/COM/etc)
from the given filenames, and 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 \-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.
.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).
.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.
.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
\fBa8eol\fP(1),
\fBa8utf8\fP(1),
\fBatr2xfd\fP(1),
\fBatrsize\fP(1),
\fBaxe\fP(1),
\fBblob2c\fP(1),
\fBblob2xex\fP(1),
\fBcart2xex\fP(1),
\fBdasm2atasm\fP(1),
\fBfenders\fP(1),
\fBrom2cart\fP(1),
\fBunmac65\fP(1),
\fBxexamine\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.
.
|
