====
a8xd
====

----------------------------------
Atari 8-bit ATASCII-aware hex dump
----------------------------------

.. include:: manhdr.rst

SYNOPSIS
========

*a8xd* [**-i**] [**-l** *limit*] [**-m**] [**-o** offset] [**-s** *[-]seek*] [**-u**] [**-v**] [*infile*]

DESCRIPTION
===========

**a8xd** is a hex dump utility, similar to **xxd**\(1), but it
understands and prints ATASCII characters rather than ASCII.

The ATASCII codes are converted to UTF-8, in the same way as
**a8cat**\(1). Codes with the high bit set are displayed in inverse
video, using ANSI/VT-100 escape sequences.

By default, the output is colorized:

  - Normal characters are green. This includes alphanumerics, spaces, and
    punctuation.

  - Codes **$00** (null, or ATASCII heart) and **$9B** (EOL) are red.

  - Control characters are yellow. This includes codes **$01** to **$1F**
    (control + letters/punctuation, escape, and arrow keys), **$60**, **$7B**, **$7D**
    (clear screen), **$7E** (backspace), and **$7F** (tab).

The colors and inverse rendering apply to both the ATASCII and hex bytes.

Without *infile*, or if *infile* is **-**, **a8xd** reads from standard input.

OPTIONS
=======

-a
  ANTIC mode: treat the input as screen bytes (aka "internal codes")
  rather than ATASCII. Can usefully be combined with **-g**.

-g
  Graphics mode. Changes the colorization so it looks like *GRAPHICS 1* (or 2)
  on the Atari.

-i
  Print XL/XE International Character Set conversions instead of ATASCII.

-l *len*
  Stop after dumping *len* bytes. *len* may be given in decimal or hex (with
  leading *0x* or *$*).

-m
  Monochrome mode. Disables color, but ATASCII characters with the high bit
  set are still displayed in inverse.

-o *offset*
  Add *offset* to displayed file position. *offset* can be given in decimal
  or hex (with leading *0x* or *$*). Negative offsets are allowed, but they
  will be printed as very large positive numbers in the output (this matches
  **xxd**\'s behaviour).

-s *[-]seek*
  Start at *seek* bytes. Without *-*, this is an absolute offset. With *-*,
  it's relative to the end of the file. The *-* option won't work when
  reading from standard input. *seek* may be given in decimal or hex
  (with leading *0x* or *$*).

-u
  Use uppercase letters for hex digits; the default is lowercase.

-v
  Verbose. Shows various debug messages that are probably only useful
  if you're hacking on **a8xd**.

**--**
  End of options; the next argument is the filename. Use this if you're
  trying to work with files whose names begin with *-*.

**-h**, **--help**
  Show built-in help and exit.

**--version**
  Show version number and exit.

NOTES
=====

**a8xd** requires the terminal emulator to support UTF-8 and use a
font with the necessary glyphs. The author has tested extensively
with **urxvt**\(1) (aka **rxvt-unicode**) and **xterm**\(1), using
the *Deja Vu Sans Mono*, *JetBrains Mono*, *Liberation Mono*,
and *Symbola* fonts. Also **kitty**\(1), **xfce4-terminal**\(1),
KDE/Plasma 5's **konsole**\(1), **gnome-terminal**\(1) 3.43.90, and
**st**\(1) from suckless.org have been lightly tested and seem to work
fine. Even the Linux console works, except that you won't be able to
find a console font with all the necessary glyphs (I may create one
someday).

**a8xd** only supports terminals that use ANSI-style escape sequences
for color and inverse video. This isn't much of a limitation, since
all modern X, Wayland, Mac, etc terminal emulators have support for
this... but it might annoy you if you're trying to use an Atari ST
with a VT52 emulator as a serial terminal. Sorry.

**a8xd** supports a useful subset of **xxd**\(1) options. The main things
missing are:

- **-r** (revert).

- **-include** (output as C include) and all options related to it.

- **-g** (grouping; **a8xd** always uses a group size of 1 byte).

- **-E** (EBCDIC mode).

- **-p** (PostScript/continuous dump).

- **-cols** (**a8xd** only supports 16 column dumps).

- **-b** (bits mode).

- support for files larger than 2GB. This won't be a problem for Atari 8-bit-related files!

- replacing duplicate lines in the output with **\***.

.. include:: manftr.rst