← TRS-80 Tool

disk

The disk command works on one floppy or hard disk image: give the image, then one or more commands to run on it, separated by a lone :. A hard disk image (HDV) works on one partition at a time; see Hard disks below.

% trs80-tool disk in.dmk dir
% trs80-tool disk in.dmk extract "*.bas" --out-dir out : free
% trs80-tool disk in.dmk check

The image doesn’t have to exist: create makes a new, blank disk, and the other commands can then work on it in the same run.

% trs80-tool disk games.dmk create ldos-5.3 : add *.bas

Most commands only read the disk; add, kill, rename, attrib, label, create and format change it. Commands that change the disk do so in memory, and the image is written once, after the last command: if any command in the chain or any line of a script fails, nothing is saved.

Only some disks can be changed: floppies of the TRSDOS family whose DOS is TRSDOS 2.x, TRSDOS 1.3, LDOS 5, TRSDOS 6 / LS-DOS 6, or DOSPLUS 3, and LDOS 5 and LS-DOS 6 partitions of hard disks, as long as check finds no problem with the file system. --dos and --force below can relax the requirements on the disk when the tool is unsure.

Table of contents

Options

-o FILE, --output FILE Save the changes to FILE instead of replacing the image. Put it before the first command.
--dry-run Write nothing, and say whether the disk would have changed. This overrides --output. Put it before the first command.
--partition N|NAME For a hard disk, work on this partition: its number, from 1, or its disk name (in any case). The partition command lists them. Put it before the first command.
--dos NAME Write by the rules of this DOS, for a disk that doesn’t say which DOS wrote it or to override what it says. The names are trsdos-2, trsdos-1.3, ldos-5, trsdos-6 (also ldos-6 and ls-dos-6), and dosplus; help dos lists them. It doesn’t change how the disk is read, and it only applies to TRSDOS-family disks. It also changes what info and check say about whether the disk is writable. Put it before the first command.
--force Write even where the disk looks doubtful (a layout that had to be guessed, a damaged file system), after printing a warning. It can’t override a problem with no safe way around, such as a disk whose DOS can’t be identified, which --dos settles. Put it before the first command.

Commands

Each command can be given after the image or typed at the prompt. In the summaries, brackets mark what can be left out, and ... means one or more.

dir

dir [NAME...]

List the files, as the dir command does, or only those matching the names, which may have wildcards as in extract.

--system List system files too. A name without wildcards finds a system file either way.

extract

extract NAME...

Copy files to your computer, as the top-level extract command does, with the same names and wildcards. A wildcard never matches a system file; to copy one, give its name. extract "*" copies them all. Also called get.

--out-dir DIR Write the files to this directory, which is created if needed. The default is the current directory.
--as PATH Write the one file that the name matches to this path.
--lowercase Write the files with lowercase names.
--mark-damaged Add [DAMAGED] to the names of damaged files, as in HELLO.BAS [DAMAGED].

list

list NAME

Show a file’s contents: a BASIC program as a listing, a text file as text (with your computer’s line endings), and anything else, such as a program, as an annotated hex dump. A file counts as text if it has no NUL bytes and nearly all of its bytes are printable characters or line endings; trailing Ctrl-Z and NUL padding is ignored. If the name has wildcards and matches several files, each is shown under a ==> NAME <== line. A wildcard never matches a system file, but its name does. Output goes through the pager when it’s a terminal (see --no-pager). A tokenized BASIC program is shown as Model 4 BASIC on a TRSDOS 6 or LS-DOS 6 disk and as Model I and III BASIC elsewhere, unless its bytes clearly belong to the other one. It works on any disk we can read, including a read-only one. Also called type and cat.

--hex Show a hex dump whatever the file is.
--raw Write the file’s bytes unchanged to standard output, with no pager, for piping.
--basic 3|4 Show a tokenized BASIC program as Model III or Model 4 BASIC, instead of choosing by the disk’s DOS.

add

add HOSTFILE...

Copy files from your computer onto the disk, converting them as needed. A .bas file of BASIC text is tokenized (Tokenized hello.bas.), unless you give --ascii; text that isn’t BASIC is an error that names the line. TRSDOS 6 and LS-DOS 6 have their own BASIC (Model 4 BASIC), whose tokens differ from the Model I and III BASIC of every other DOS, so text is tokenized for the disk’s DOS (Tokenized hello.bas for Model 4 BASIC.). A host file that’s already tokenized is copied as it is if it fits the disk’s BASIC; if its bytes show it’s for the other BASIC, it’s converted by way of its text (Converted old.bas from Model III to Model 4 BASIC tokens.). A .3bn system program, or a .cas that holds one, becomes a CMD program that the DOS can run, named with the extension CMD (game.3bn becomes GAME/CMD); a .cas that holds a BASIC program becomes tokenized BASIC, and one with several programs is refused (use extract on it first). The LF and CRLF line endings of .txt, .asm, .jcl, .doc, .hlp, .lst, .fix, and .src files become CR (Converted line endings of notes.txt.). Every other file is copied byte for byte. The host names may have wildcards. Each file’s TRSDOS name is made from its host name, upper-cased, with other characters dropped and the name cut to 8 letters and a 3-letter extension, and the command says when that changed it (hello-world.bas will be HELLOWOR/BAS.). Nothing is added unless every file can be: a name that is already on the disk (unless you give --overwrite), two files with the same TRSDOS name, or too little room is an error. A file that would need more than four fragments of free space can’t be added yet. It prints Added HELLO/BAS (1,234 bytes). for each file. Also called import and put.

--ascii Keep a BASIC program as text with CR line endings (Disk BASIC loads those too), instead of tokenizing it. A host file that’s already tokenized is turned back into text, reading its tokens as the disk’s BASIC when the bytes don’t say. This can’t be used with --binary.
--binary Copy every file byte for byte, with no conversion at all.
--basic 3|4 Tokenize BASIC text for Model III or Model 4 BASIC, instead of for the disk’s DOS.
--as NAME Give the TRSDOS name of the one host file, instead of making it from the host name.
--system Make the files system files.
--invisible Hide the files from directory listings.
--date YYYY-MM-DD Give the files this date. Files get no date unless you give one, and only LDOS and TRSDOS 6 / LS-DOS 6 disks keep one: TRSDOS 2.x and DOSPLUS 3 disks ignore it, with a warning. Those disks hold the years 1980 to 1987, or 1980 to 2011 on an LDOS 5.3 or LS-DOS 6.3 disk (which also stores the time of day), and a year outside that is an error. With no date, the entry is marked as having none.
--overwrite Replace the files that are already on the disk, in the same directory slot, and print Replaced HELLO/BAS (1,234 bytes). for them. The new copy keeps the old file’s attributes, passwords, record length, and date, except that --system, --invisible, and --date change those they name (on the LDOS line the file is also marked as changed since the last backup). BOOT/SYS and DIR/SYS can’t be replaced. The new copy is written to free space first and the old copy freed afterward, so the new copy never lands on the old one’s sectors; only if it wouldn’t fit that way does it take over the old copy’s space, and the command warns when that happens. As with every change, nothing is saved unless every file can be added or replaced.

kill

kill NAME...

Remove files from the disk, freeing the space they used. The names may have wildcards, as in dir; every name must match a file, or nothing is removed. A wildcard never matches a system file; to remove one, give its name. BOOT/SYS and DIR/SYS can’t be removed at all. It prints Removed HELLO/BAS. for each file. Also called rm, del, delete, and remove.

rename

rename OLDNAME NEWNAME

Rename a file on the disk. Both names are single TRSDOS names, with no wildcards, and either / or . may come before the extension. The new name must not belong to another file. System files can be renamed, but BOOT/SYS and DIR/SYS can’t be. Only the name changes, not the file’s contents, dates or attributes. It prints Renamed HELLO/BAS to GREET/BAS. Also called mv, ren, and move.

attrib

attrib PATTERN...

Change the attributes of files, or with no attribute options show them. The patterns may have wildcards, as in dir; every pattern must match a file, or nothing is changed. A wildcard never matches a system file; to change one, give its name. It prints Changed HELLO/BAS: invisible, protection READ. for each file. Also called attr.

--invisible, --visible Hide the files from directory listings, or show them.
--system, --no-system Make the files system files, or user files. BOOT/SYS and DIR/SYS can’t change.
--protect LEVEL Set the protection level, described below.
--password PW Set the update, or owner, password, which allows full access. An empty password removes the password. A password is up to 8 letters and digits, starting with a letter.
--access-password PW Set the access password, which allows access up to the protection level. An empty password removes the password, and the rules for a password are as for --password. LDOS 5.3 and LS-DOS 6.3 disks keep a time stamp where the access password would go, so they have no access password to set.
--date YYYY-MM-DD, --no-date Set or remove the date, on the DOSes that store one (see add) and as an error elsewhere. System files on LDOS 5.3 and LS-DOS 6.3 disks have no dates.

The protection level is a name or a number from 0 to 7, in any case. The names are the disk’s DOS’s: FULL (0), KILL (1), RENAME (2), WRITE (4), READ (5), EXEC (6), and NO_ACCESS (7) on TRSDOS 2.x, LDOS 5, and the other DOSes of that family, but REMOVE (1), WRITE (3), and UPDATE (4) on TRSDOS 6 and LS-DOS 6. An unknown name lists the ones that fit the disk.

label

Show or change the disk’s name, date, master password and AUTO command. With no options it shows them, and needs no write access: the name, the date as the disk stores it, whether the master password is PASSWORD (the usual one), blank, or something else (shown as its hash, since the password itself isn’t stored), and the AUTO command, which is the command the DOS runs when it boots. The options each change one field and leave the others alone. It prints what changed, such as Name is now GAMES. AUTO command is now BASIC RUN"MENU".

--name NAME Set the disk’s name, up to 8 characters (uppercased except on DOSPLUS).
--date YYYY-MM-DD Set the disk’s date. The DOS keeps only two digits of the year, so the year must be one it can enter: 1980 to 1999, or to 2011 on LDOS 5.3 and LS-DOS 6.3 disks.
--password PW Set the master password, up to 8 letters and digits, starting with a letter. An empty one makes it blank.
--auto COMMAND, --no-auto Set the AUTO command, or remove it.

The AUTO command is up to 31 characters on TRSDOS 2.x, LDOS 5 and DOSPLUS 3, which keep it in the same sector as the name, and up to 79 on TRSDOS 6 and LS-DOS 6, which keep it in the system information sector of the boot track. A TRSDOS 6 disk that has no such sector (one that another program formatted) can’t be given an AUTO command. Changing the name or date doesn’t change the DOS release banner that TRSDOS 6 keeps in that sector.

protect

protect [on|off]

Show the image’s write-protect flag, or turn it on or off. The flag is in the image file, and emulators honor it the way a drive honors the tab on a real floppy; the commands that change files refuse a write-protected disk unless you give --force. DMK, JV3 and HFE floppies and HDV hard disks have the flag. JV1 and IMD images have nowhere to keep one, so protect explains that instead.

info

Describe the image and its file system, as info --verbose does, with the free space and whether the disk can be written. For a hard disk it lists the partitions, or describes the selected one.

partition

partition [N|NAME]

For a hard disk, list the partitions (number, where they are, disk name, DOS, number of files, and whether they can be written), or with a number or a disk name choose the partition that the following commands work on. Also called part. It changes nothing on the disk. See Hard disks.

free

Show the space left for new files on a TRSDOS-family disk: granules that the GAT says are free and that no file uses.

map

map [PATTERN...]

Draw the disk sector by sector, so you can see where everything is: a line for each cylinder and a cell for each sector on it, numbered by a ruler on top. On a double-sided disk each cylinder has a line for side 0 and one for side 1, so reading left to right and top to bottom follows the order the DOS allocates sectors in. A │ ends each granule. A file is a run of ─ that starts with its name, in a color of its own; the name repeats at the start of each cylinder (but not when a file runs from side 0 to side 1). The directory and the boot granule are drawn the same way. · is a free sector and x a locked-out one. Damage shows in red: ! for a granule that two or more files claim, ? for one that a file claims but the GAT says is free, and u for one the GAT says is used that no file claims. With patterns, only the matching files get names and colors, and the rest show as a plain ─; the matching files are listed below the map. A wildcard never matches a system file; to show one, name it. It changes nothing, so it works on a read-only disk, and only on TRSDOS-family disks.

cyl   0  1  2  3  4  5  6  7  8  9
  0  BOOT/SYS ─────│·  ·  ·  ·  · │
  1  ·  ·  ·  ·  · │·  ·  ·  ·  · │
  2  HELLO/BAS ────│──────────────│
  3  HELLO/BAS ────│·  ·  ·  ·  · │
  4  ·  ·  ·  ·  · │·  ·  ·  ·  · │
  5  ·  ·  ·  ·  · │WORLD/BAS ────│
  6  ·  ·  ·  ·  · │·  ·  ·  ·  · │
  7  ·  ·  ·  ·  · │·  ·  ·  ·  · │
  8  KERNEL/SYS ───│──────────────│
  9  ·  ·  ·  ·  · │·  ·  ·  ·  · │
 ...
 17  DIR/SYS ──────│──────────────│

· free
9 of 36 granules used, 27 free (33.8 KB). A granule is 1,280 bytes.

check

Check a TRSDOS-family file system for problems, changing nothing: files that share granules, files in granules the GAT says are free, extents past the end of the disk, HIT bytes that don’t match names, and damaged files. It notes programs whose directory size ends before the end of the program, which the DOS loads fine but which copy broken. It also says whether the disk would be safe to write, and if not, why not.

repair

Fix the damage that check finds, where it can be fixed without guessing, in the GAT, the HIT and the directory only: granules that a file uses and the GAT says are free are marked used, HIT bytes that aren’t the hash of the file’s name are set to it, and extended directory entries that no file reaches are deleted. It prints what it changed, then the damage it can’t fix (files that share granules, extents past the end of the disk, damaged files), and says whether the disk is now safe to write. It works on a disk that is damaged but otherwise sound, which is the only kind of write that such a disk allows, so repair : add FILE works. It refuses a disk that can’t be written for another reason, such as an uncertain layout, even with --force. Under TRSDOS 2.x’s rules the HIT bytes of extended directory entries are left alone, since we don’t know what the DOS puts there. Granules that the GAT marks used but no file claims are left alone, since some programs keep data there. So are programs whose directory size ends before their transfer record, further into their last sector, since the DOS loads them fine and many DOSes shipped files that way. Like any other change, a repair can be taken back with undo.

--free-unclaimed Also free the granules that the GAT marks used but no file claims. Granules on the boot cylinder and locked-out ones are never freed.
--fix-program-sizes Also set the size of each program whose directory size ends before its transfer record, so that it reaches it, and the program copies whole.

create

create DOS

Make a new, blank, formatted data disk, with no files, the way the DOS’s own FORMAT leaves one (or, with --system, a bootable system disk). It works when the image doesn’t exist yet (the disk is saved under that name at the end), or with --force to replace in memory the disk that the image has. The image is always a DMK one, so a name ending in .jv1, .jv3, .dsk, .hfe or .imd is refused. The disk can be used by later commands in the same run, and a quit or the end of the run saves it.

The DOS to make the disk for is required, and comes first. It is one of trsdos-2.3, trsdos-1.3, ldos-5.3, trsdos-6.2 and lsdos-6.3; help create, and the error for a missing or unknown DOS, list them with what each makes. (This is not the --dos option that goes before the first command.)

--cylinders N The number of cylinders. The default is 40, or 35 for TRSDOS 2.3; the DOS sets the limits. With --system, it is refused if it differs from the system disk’s.
--sides 1|2 The number of sides. The default is 1; TRSDOS 2.3 and 1.3 have only one. With --system, it is refused if it differs from the system disk’s.
--density single|double The recording density. The default is single for TRSDOS 2.3 and double for the others. With --system, it is refused if it differs from the system disk’s.
--model 1|3|4 The TRS-80 the disk is for. Without --system it only chooses LDOS 5.3’s default density: single for the Model I, double otherwise. With --system, --model 1 chooses LDOS 5.3’s Model I system disk, and otherwise its Model III disk is used.
--name NAME The disk’s name. The default is DATADISK. With --system, it changes the copy’s name.
--date YYYY-MM-DD The disk’s date. The default is today, as FORMAT does. With --system, it changes the copy’s date.
--force Replace in memory the disk that the image has, instead of failing.
--system Make a bootable system disk instead of a blank data disk: a copy of the DOS’s own system disk, with all its files.
--minimal With --system, remove every file that isn’t a system file, keeping what the DOS needs to boot (and saying what it removed), to leave room on the disk.

The disk gets the DOS’s own data-disk boot sectors, copied from disks that the DOS formatted, so apart from the name and date it is the same as what FORMAT makes. It is still a data disk, not a system disk. (Where we haven’t measured the DOS’s own, which is single-density TRSDOS 6 and LS-DOS 6 disks, the disk gets a boot sector of our own that only prints a message and halts; the DOS and this tool still recognize the disk by its other sectors.)

With --system, create instead makes a bootable system disk. Each DOS has one disk (LDOS 5.3 has one for the Model I and one for the Model III), which fixes the shape of the disk. The result can be changed by later commands in the same run, such as add, like any other disk.

The bundled system disks, which help create also lists, are:

These disks and the DOSes’ boot sectors are the DOS publishers’ software, shipped inside the tool as the trs80gp emulator ships them. They will be taken out of the tool if the rights holders ask.

format

format [DOS]

Erase the disk and format it as an empty data disk. It takes the same options as create, except --system and --minimal, with an optional DOS that defaults to the disk’s own (it is required if that isn’t one of the five), the cylinders and sides default to the disk’s, and an LDOS-family disk keeps its density. The result is a DMK image, so for an image of another kind give -o NEW.dmk to save it under a new name. Like everything else it changes the disk in memory, and nothing is saved until the end.

--force Erase a disk that has files. Without it, format says how many files would be lost and does nothing.

trim

Drop tracks that the disk doesn’t use from the image, which wastes space and confuses other tools: an 80-cylinder image of a 40-cylinder disk, or a blank second side. It works on DMK, JV1 and JV3 images, rebuilding the image without those tracks, and checks that the result decodes as the same file system with every file reading the same; if not, nothing changes. With no options it drops the cylinders past the ones the file system uses (the ones that the GAT marks as beyond the disk’s end), and any cylinders at the end with no readable sectors, and says what it dropped. Some DOSes, such as TRSDOS 1.3, don’t mark their end, so only the unreadable cylinders go. If there’s nothing to drop it says so and changes nothing.

--cylinders N Keep cylinders 0 to N-1. It refuses if a file or the directory has data on a dropped cylinder (naming them and the cylinders the file system covers), or if the dropped cylinders are free space that the file system expects to have, unless you give --force. On a disk with no file system, it refuses if a dropped track holds data that isn’t filler (each sector the same byte, or the same two bytes alternating), unless --force.
--side 0 Drop side 1. It refuses if the file system allocates on both sides, or, with no file system, if side 1 holds data that isn’t filler (unless --force). A single-sided image has nothing to drop.
--force Drop tracks that hold data we can’t prove is unused, as described above. It also lets trim work on an image marked write-protected.

Like everything else, trim changes the disk in memory and nothing is saved until the end, so --dry-run and -o work.

boot

Boot the disk, as it is in memory, in the emulator, drawn in the terminal the way run draws it. Ctrl-C stops the emulator and returns to the prompt (or to the next command in a chain). It says which model it chose and why: a Model I for TRSDOS 2.x and for other DOSes on single-density disks, a Model III for TRSDOS 1.3 and for other DOSes on double-density disks, and a Model 4 for TRSDOS 6 and LS-DOS 6; a disk with no DOS we recognize gets a Model III. Also called run.

The DOS can write to the disk, but only in memory: the whole session is one change that undo takes back, and save or quit saves, so the image file is not touched until then. Afterward the file system is read again, since the DOS may have changed anything. It needs a terminal, and refuses to run in a script.

--model 1|3|4 Boot on this model, instead of the one chosen as above.
--write-protected Mount the disk write-protected, so that the DOS can’t write to it. A disk whose image is marked write-protected stays so.

undo

Take back the most recent change to the disk (an add, kill, label, create, format, trim and so on), restoring the disk exactly as it was, including its image format, and say which command it undid. It can be repeated to go further back, up to the last 100 changes (fewer on a large image, since each step holds a copy of the whole image; a hard disk keeps up to 256 MB of them, and says so the first time it drops the oldest). If undoing takes the disk back to what was last saved then there are no changes to save. It says so if there’s nothing to undo. It works in a chain too: kill HELLO.BAS : undo.

redo

Do again the change that undo took back. Making a new change after an undo forgets what could have been redone.

revert

Go back to the disk as it was when last saved (or as it was opened, if it hasn’t been saved), in one step. It counts as a change, so undo takes the revert back.

save

Save the changes now and carry on. Useful in the prompt; it says so if there’s nothing to save.

quit

Save the changes, if any, and leave the prompt. Also called exit; Ctrl-D does the same.

abort

Leave the prompt, discarding any changes. Ctrl-C at an empty prompt does the same; with text on the line, Ctrl-C only clears the line and shows a new prompt.

help

help [COMMAND]

List the commands, or describe one with its options and other names (ls for dir, for example).

The prompt and scripts

With no commands after the image, disk opens a prompt where you type the same commands, one line at a time, with tab completion of command and file names. quit saves any changes to the disk and leaves it. If the input isn’t a terminal, the commands are read from it instead, so trs80-tool disk in.dmk < script.txt runs a script, stopping at the first error. Lines starting with # are comments.

% trs80-tool disk in.dmk
in.dmk: Floppy disk (DMK), LDOS 5.1, 26 files, 157 KB free
Type "help" for a list of commands, and "quit" to leave.
>free
157 KB free (105 granules of 1,536 bytes each)
>quit

Flags such as --color go before disk; after the image, everything belongs to the disk commands.

Hard disks

disk opens HDV hard disk images (the format of xtrs, sdltrs, and FreHD) and works on their LDOS 5 and LS-DOS 6 (TRSDOS 6) partitions, with the same commands, checks, and safeguards as a floppy: dir, extract, list, add, kill, rename, attrib, label, info, free, check, repair, undo, redo, revert, and save. Changes are made in memory, checked by decoding the partition again, and written once at the end (or to --output, or not at all with --dry-run), and only the sectors of the partition that the change needs are altered.

% trs80-tool disk hard.hdv partition
  1  cylinders 0-139, heads 0-5  HARDA  LS-DOS 6.3  80 files  writable
  2  cylinders 140-279, heads 0-5  HARDB  LS-DOS 6.3  18 files  writable
% trs80-tool disk hard.hdv --partition HARDB add hello.bas : dir
% trs80-tool disk hard.hdv partition 2 : add game.cmd

A hard disk holds one or more partitions, each with a file system of its own. A partition is chosen with --partition or the partition command, and its name (the disk name, or partition N if it has none) shows in the prompt of the interactive shell. If the disk has only one partition then it is used without being chosen. If it has several, every command that needs files fails with a list of the partitions until one is chosen, since writing to the wrong partition is easy to do and hard to notice. Choosing a partition is not a change to the disk, and undo never changes it.

What isn’t supported: creating, formatting, or partitioning a hard disk image (create, format, trim, boot, and map work on floppy images and say so); DOSPLUS 3 partitions, which are read but never written, because their GAT doesn’t record how many granules each cylinder has; NEWDOS/80 and CP/M hard disks, which aren’t read at all yet; and the HDV version 2 format. A write-protected HDV (its header’s flag) can be written only with --force, and the saved image keeps its flag.