diff options
Diffstat (limited to 'xexcat.rst')
| -rw-r--r-- | xexcat.rst | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/xexcat.rst b/xexcat.rst new file mode 100644 index 0000000..a7ce20b --- /dev/null +++ b/xexcat.rst @@ -0,0 +1,132 @@ +.. RST source for xexcat(1) man page. Convert with: +.. rst2man.py xexcat.rst > xexcat.1 +.. rst2man.py comes from the SBo development/docutils package. + +====== +xexcat +====== + +----------------------------------------------------------------- +Concatenate Atari 8-bit executables (XEX) into a single XEX file. +----------------------------------------------------------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +*xexcat* [*-hvc*] [-l *address* [-r *address*] [-i *address*] [-o *outfile.xex*] [*infile.xex*] [*infile.xex ...*] + +DESCRIPTION +=========== + +**xexcat** 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 *outfile*. + +To read from standard input, *infile* may be omitted, or given as +**-**. To write to standard output, **-o** *outfile* may be omitted, +or given as **-o-**. + +The output file is a valid Atari executable, including the +required *$FFFF* header for the first segment. If there are multiple +segments, the second and subsequent segments will not have the +optional *$FFFF* header. + +OPTIONS +======= + +-h + Print a short help message and exit. + +-v + Verbose operation. Each segment's information is printed to + standard error, including start/end address and length. + +-c + Check only; no output file is written. Equivalent to **-v -o /dev/null**. + +-o outfile + Write output xex file to outfile. Default is to write to standard output. + +-l address + Force the output file's load address to address. This only + affects the first segment of the output file. + +-i address + Force the output file's first init address (if present) to + *address*. This *only* affects the **first** init address segment of the + output file. Further init address segments in the input will be + left unmodified. If *address* 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. + +-r address + Force the output file's run address to *address*. If *address* + 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 *address* and appended to the output. If *address* + 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). + +NOTES +===== + +It is possible to join multiple Atari executables together with +the standard **cat**\(1) command. However, **xexcat** 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 **cat**. + +When writing to standard output, **xexcat** will refuse to write +binary data to the user's terminal. + +The Atari binary load format requires the *$FFFF* header only for +the first segment in a file. The second and subsequent segments +may also have a *$FFFF* header, but it's optional. **xexcat**'s output file +will always have the *$FFFF* header for the first segment, and no +*$FFFF* header for further segments, regardless of whether the segments +in the input files had it or not (in fact, **xexcat** can handle +an invalid XEX file which is missing the initial $FFFF header for the +first segment). + +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 **xexcat** 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 **xexcat**, +a raw data block is usually the reason why. + +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't care about the names, only the contents. + +EXIT STATUS +=========== + +Exit status is zero for success, non-zero for failure. + +.. other sections we might want, uncomment as needed. + +.. FILES +.. ===== + +.. ENVIRONMENT +.. =========== + +.. EXIT STATUS +.. =========== + +.. BUGS +.. ==== + +.. EXAMPLES +.. ======== + +.. include:: manftr.rst |