From e2ba8458a5cfdfacfaf103e7ba97d610afa6c970 Mon Sep 17 00:00:00 2001 From: "B. Watson" Date: Mon, 29 Aug 2022 16:11:13 -0400 Subject: initial commit --- axe.rst | 114 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 axe.rst (limited to 'axe.rst') diff --git a/axe.rst b/axe.rst new file mode 100644 index 0000000..01e8a10 --- /dev/null +++ b/axe.rst @@ -0,0 +1,114 @@ +.. RST source for axe(1) man page. Convert with: +.. rst2man.py axe.rst > axe.1 +.. rst2man.py comes from the SBo development/docutils package. + +=== +axe +=== + +-------------- +ATR/XFD Editor +-------------- + +.. include:: manhdr.rst + +SYNOPSIS +======== + +**axe** [*-alvtu*] [*-b newimage*] [*-D file*] [*-x file*] [*-w file*] [*-c dirname*] [*-t*] [*-d sector*] [*imagefile*] + +DESCRIPTION +=========== + +**axe** allows the user to access files stored inside a single-density +Atari DOS 2.0S disk image (ATR or XFD). It can list the directory, +copy files into and out of the image, delete files in the image, +create a new image (either blank or containing files), and dump various +low-level information about the image's filesystem structure. + +OPTIONS +======= + +Standard Options: +----------------- + +-b *filename* + Create blank ATR image file called *filename*. If *filename* + already exists, it will be overwritten with no warning. + +-c *directory* + Create new ATR *imagefile* with contents of *directory*. If *imagefile* + already exists, it will be overwritten with no warning. Similar to **tar cf**. + +-D *file* + Delete *file* from *imagefile*. Ignores "locked" bit. + +-t *directory* + Extract all files in image to *directory*, which will be created and + must not already exist. Similar to **tar xf**. + +-u + Unix <-> Atari newline/EOL translation (use for text files only; breaks other file types). + +-w *file* + Write *file* to *imagefile*, overwrites if *file* already exists. Ignores "locked" bit. + +-x *file* + Extract (read) file from *imagefile*, write to current directory. + +Debugging Options: +------------------ + +-a + List all directory entries, even deleted/empty ones. + +-d *sector* + Dump a sector in decimal, hex, and binary. + +-l + Trace and print sector links for all files on disk. + +-v + Dump VTOC (sector 360) in decimal, hex, and binary. + +LIMITATIONS +=========== + +**axe** is ancient code, from last century. It has various design +flaws and bugs. At this point, it would be better to rewrite it from +scratch than to try & fix the existing code. + +Only Atari DOS 2.0S and 100% compatible single-density disk images are +supported. MyDOS images will work, but there's no support for MyDOS +subdirectories. There's no support for e.g. SpartaDOS or Atari DOS +3.0/4.0. Atari DOS 2.5 enhanced density images will work, the same +way they work on DOS 2.0S: files using the extra sectors will not be +readable, and **axe** won't write to the extra sectors. Atari DOS 1.0 +images (which are *very* rare) can at least have the directory listed, +but I wouldn't recommend writing to them. + +The "file locked" (aka read-only) bit is ignored when writing, and +there's no way to lock or unlock files, though locked files do appear +with \* next to the name in the directory listing. + +It's possible to create files in a disk image with invalid filenames, +e.g. beginning with a number, or containing punctuation. Atari DOS +might or might not be able to even delete such files, but **axe** will +be able to if it happens. + +One known bug: when writing a file to an image, if the file's size +is a multiple of 125 (the number of data bytes per sector), an extra +sector is allocated (with 0 data bytes in it). This doesn't actually +cause a problem for Atari DOSes (it just wastes space on the disk), +but it prevents simple-minded XEX loaders like Fenders from being able +to load the file (technically this is a bug in Fenders, too). Atari +DOSes actually can create files like this if they're opened for +append, then closed without writing new data. + +**axe** does nothing with the boot sectors (sectors 1-3) of the disk +image. When creating a new image, the boot sectors will be blank (all +zeroes), meaning the disk won't be bootable. If DOS.SYS is written to +an image with a DOS boot record, the boot record won't be updated with +the first sector of DOS.SYS, so the disk won't be bootable. + +.. include:: manftr.rst -- cgit v1.2.3