Go to the first, previous, next, last section, table of contents.

# 13 c1541

VICE is provided with a complete stand-alone disk image maintenance utility, called `c1541`.

You can either invoke it from the command line or from within one of the VICE emulators, using the "Run c1541" menu item which will open a new terminal window with a running `c1541` in it.

The syntax is:

    c1541 [IMAGE1 [IMAGE2]] [COMMAND1 COMMAND2 ... COMMANDN]

`IMAGE1` and `IMAGE2` are disk image names that can be attached before `c1541` starts. `c1541` can handle up to two disk images at the same time by using two virtual built-in drives, numbered `8` and `9`; `IMAGE1` (if present) is always attached to drive `8`, while `IMAGE2` is attached to drive `9`.

`COMMAND`s specified on the command-line all begin with the minus sign (`-`); if present, `c1541` executes them in the same order as they are on the command line and returns a zero error code if they were successful. If any of the `COMMAND`s fails, `c1541` stops and returns a nonzero error code.

If no `COMMAND`s are specified at all, `c1541` enters interactive mode, where you can type commands manually. Commands in interactive mode are the same as commands in batch mode, but do not require a leading `-`. As with the monitor, file name completion and command line editing with history are provided via GNU `readline`. Use the command ``quit'` or press `C-d` to exit.

## 13.1 Specifying files in c1541

When accessing CBM DOS files (i.e. files that reside on disk images), c1541 uses a special syntax that lets you access files on both drive 8 and 9. If you prepend the file name with `@8:` or `@9:`, you will specified that file is to be found or created on drive 8 and 9, respectively.

For instance,

    @8:somefile

will name file named `somefile` on unit 8, while

    @9:somefile

will name file named `somefile` on unit 9.

## 13.2 Using quotes and backslashes

You can use quotes (`"`) in a command to embed spaces into file names. For instance,

    read some file

will read file `some` from the disk image and write it into the file system as `file`, while

    read "some file"

will copy `some file` into the file system, with the name `some file`.

The backslash character (`\`) has a special meaning too: it lets you literally insert the following character no matter what it is. For example,

    read some\ file

will copy file `some file` into the file system, while

    read some\ file this\"file

will copy `some file` into the file system with name `this"file` (with an embedded quote).

## 13.3 c1541 commands and options

This is a list of the `c1541` commands. They are shown in their interactive form, without the leading `-`. Square brackets [] indicate an optional part, and "<COMMAND>" translates to a disk command according to CBM DOS, like "i0" for example.

`@ [<command>]`
  Execute specified CBM DOS command and print the current status of the drive. If no `command` is specified, just print the status.
`? [<command>]`
  Explain specified command. If no command is specified, list available ones.
`attach <diskimage> [<unit>]`
  Attach `diskimage` to `unit` (default unit is 8).
`bam [<unit>] | <track-min> <track-max> [<unit>]`
  Show the BAM of `unit`, optionally displaying only the entries for `track-min` to `track-max`
`bcopy <src-trk> <src-sec> <dst-trk> <dst-sec> [<src-unit> [<dst-unit>]]`
  Copy a block to another block, optionally specifying different source and destination units. The block is copied using all 256 bytes.
`bfill <track> <sector> <value> [<unit>]`
  Fill a block with a single value.
`block <track> <sector> [<offset> [<unit>]]`
  Show specified disk block in hex form.
`bpoke [@unit:<unit>] <track> <sector> <offset> <data ...>`
  Store one or more bytes of `data` into a block. The `data` can be specified using prefixes:
  `0b or %`
    binary value (`%11111111`)
  `&`
    octal value (`&377`)
  `0x or $`
    hexadecimal value (`$ff`)
  The <unit> is optional, and when used must use the CBM DOS notation for the unit number, for example `@9:`.
`bread <filename> <track> <sector> [<unit>]`
  Read a block from a disk image and write it to the host filesystem as `filename`.
`bwrite <filename> <track> <sector> [<unit>]`
  Write data from the host filesystem using `filename` as input. At most 256 bytes are written to the disk image.
`chain <track> <sector> [<unit>]`
  Show block chain starting at (`track`,`sector`). The last number shown is the number of bytes used in the final block.
`copy <source1> [<source2> ... <sourceN>] <destination>`
  Copy `source1` ... `sourceN` into destination. If N > 1, `destination` must be a simple drive specifier (`@n:`).
`delete <file1> [<file2> ... <fileN>]`
  Delete the specified files.
`exit`
  Exit (same as `quit`).
`extract`
  Extract all the files to the file system.
`format <diskname,id> [<type> <imagename>] [<unit>]`
  If `unit` is specified, format the disk in unit `unit`. If `type` and `imagename` are specified, create a new image named `imagename`, attach it to unit 8 and format it. `type` is a disk image type, and must be either `x64`, `d64` (both VC1541/2031), `g64` (VC1541/2031 but in GCR coding), `d71` (VC1571), `g71` (VC1571 but in GCR coding), `d81` (VC1581), `d80` (CBM8050) or `d82` (CBM8250/1001). Otherwise, format the disk in the current unit, if any.
`geosread <source> [<destination>]`
  Read GEOS <source> from the disk image and copy it as a Convert file into <destination> in the file system. If <destination> is not specified, copy it into a file with the same name as <source>.
`geoswrite <source>`
  Write GOES Convert file <source> from the file system on a disk image.
`geosextract <source>`
  Extract all the files to the file system and GEOS Convert them.
`help [<command>]`
  Explain specified command. If no command is specified, list available ones.
`info [<unit>]`
  Display information about unit `unit` (if unspecified, use the current one).
`list [<pattern>]`
`dir [<pattern>]`
  List files matching `pattern` (default is all files).
`name <diskname>[,<id>] <unit>`
  Change image name.
`p00save <enable> [<unit>]`
  Save P00 files to the file system.
`quit`
  Exit (same as `exit`).
`read <source> [<destination>]`
  Read `source` from the disk image and copy it into `destination` in the file system. If `destination` is not specified, copy it into a file with the same name as `source`.",
`rename <oldname> <newname>`
  Rename `oldname` into `newname`. The files must be on the same drive.
`show [copying | warranty]`
  Show conditions for redistributing copies of C1541 (`copying') or the various kinds of warranty you do not have with C1541 (`warranty').
`tape <t64name> [<file1> ... <fileN>]`
  Extract files from a T64 image.
`unit <number>`
  Make unit `number` the current unit.
`unlynx <lynxname> [<unit>]`
  Extract the specified Lynx image file into the specified unit (default is the current unit).
`validate [<unit>]`
  Validate the disk in unit `unit`. If `unit` is not specified, validate the disk in the current unit.
`verbose ["off"]`
  Enable or disable verbose output.
`version`
  Show C1541 version string
`write <source> [<destination>]`
  Write `source` from the file system into `destination` on a disk image.
`zcreate <x64name> <zipname> [<label,id>]`
  Create an X64 disk image out of a set of four Zipcoded files named `1!zipname`, `2!zipname`, `3!zipname` and `4!zipname`.

## 13.4 Executing shell commands

If you want to execute a shell command from within `c1541`, just prepend it with an exclamation mark (`!`). For example,

    !ls -la

will execute the command `ls -la`, which will show you all the files in the current directory.

## 13.5 c1541 examples

`c1541 -attach test.d64 -list`
  Attach `test.d64` and show directory.
`c1541 -attach test.d64 -write test.prg testfile`
  Write `test.prg` to `test.d64` as `testfile`.
`c1541 -format "name,id" d64 disk.d64`
  Create a disk image in `d64` format, format it with the `name` and `id` and save it to `disk.d64`.

Go to the first, previous, next, last section, table of contents.