diff options
Diffstat (limited to 'xexcat.1')
| -rw-r--r-- | xexcat.1 | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/xexcat.1 b/xexcat.1 new file mode 100644 index 0000000..5cb659c --- /dev/null +++ b/xexcat.1 @@ -0,0 +1,181 @@ +.\" 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 "2022-08-27" "0.2.0" "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), +\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. +. |