C64 OS USER'S GUIDE

Chapter 8: File System

On the legacy devices, 1541, 1571 and even 1581, disk capacities are relatively small and options for organization are limited. Typically a single disk, or disk side, holds so little data that the lack of subdirectories is not that important. Each disk contains a single root directory, but because files are spread across different disks, there are at least 2 levels of organization: Find the disk in the storage case, find the file in that disk's directory.

The era of modern storage devices began in the late 80s and early 90s with the CMD FD Series and CMD Hard Drives. Later came the RAMLink, and then IDE64 which is still commercially available today. Now we have SD2IEC drives that are available in a wide variety of form factors and are remarkably inexpensive.

With all of these modern storage devices, mass storage capacity ranges from megabytes to gigabytes in a single partition, (i.e., in a single file system.) All of these devices support multiple partitions as well. Most traditional Commodore 64 software does not provide robust support for partitions or subdirectories, even that software released during an era when these newer devices already existed.

That all changes with C64 OS. Not only does C64 OS provide robust support for devices with partitions and subdirectories, but it capitalizes on those features. A C64 OS installation is contained within a single system directory, and that system directory is further divided into a standardized layout of subdirectories that is easy to understand but usefully organized.

---

Drives and Devices

On the C64, devices that are recognized by the KERNAL include: the keyboard, the screen, a datasette, RS-232 over the user port, printers and storage devices. When this chapter talks about devices it is referring to storage devices. The word drive is sometimes used interchangeably to mean storage device. A 1541, for example, is both a single floppy disk drive, and it also a storage device with a device number that the operating system uses to communicate with it.

C64 OS supports the following storage devices:

Legacy Devices	Modern Devices
Commodore 1541 170KB Commodore 1571 340KB Commodore 1581 800KB VICE FS Single Directory	CMD FD Series 1.6MB → 3.2MB CMD Hard Drive 20MB → 4.4GB CMD RAMLink / RamDrive 512KB → 16MB IDE64 100MB → 128GB SD2IEC 16MB → 32GB

System Drive

A C64 OS installation is contained within a single subdirectory. This is called the system directory and it is organized into a number of subdirectories, which are outlined below. Legacy devices do not support subdirectories, and for this reason they cannot store a C64 OS system directory. Everything required to boot and run C64 OS is in the system directory, and therefore the drive on which the system directory is stored is called the system drive, or alternatively, the boot drive.

Any of the modern devices can serve as the system drive:

• CMD HD
• RAMLink
• IDE64
• SD2IEC

CMD FD Series drives work much like miniature CMD Hard Drives. C64 OS should be able to boot from a CMD FD, however, due to the small storage capacity of the media (1.6 MB) it is necessary to omit some non-essential files. Instructions for how to create an installation of C64 OS on a CMD FD disk are not included, but in essence, it is a copy of the standard C64 OS system directory but with unused drivers omitted, programming headers and constants omitted, unnecessary Utilities and Applications omitted, etc. Some experimentation may be required to find the right balance of components for your particular needs.

All other non-C64-OS-specific files, such as documents, pictures, music, and other data files can be stored and accessed from anywhere—including on legacy devices—not just from the system directory. Games and other software can be launched with PRG Runner, and these can also be installed anywhere, including on legacy devices.

Partitions and Subdirectories

All of the modern devices not only support subdirectories, but they also support multiple partitions and the partition directory.

Partitions have names, which are listed in the partition directory, but they are accessed by number. CMD devices support 255 partitions partitions, numbered from 1 to 255. Partition 0 is a special system partition that cannot be accessed directly. SD cards support multiple partitions, but how many of these partitions can be accessed depends on the SD2IEC device. Most SD2IEC devices support access only to the first 2 partitions on the card. The uIEC/SD from Retro Innovations is a bit exceptional; it supports up to 16 partitions.

Each partition maintains a separate file system. The size of a partition is set when it is created, although special tools can sometimes be used to resize a partition without damaging the data that is already stored in it.

C64 OS version 1.0 does not provide tools for creating or managing partitions.

• Use the CMD tools that came with your CMD HD, CMD FD or RAMLink to create and manage partitions on those devices.
• Use the IDE64's built-in tools and tools that come with its Utilities disk to create and manage partitions on the IDE64.
• SD2IEC devices read SD Cards that have been partitioned and formatted with MS-DOS FAT file systems. The SD2IEC cannot be used to create and manage partitions. Use a PC or Mac to partition and format and SD card.

Partitions create certain hard boundaries between the file systems. Each file system maintains a separate root directory, separate blocks free count, block availability map (or the equivalent), and so on. However, if a partition gets corrupted somehow, you can format one partition and that has no impact on the data stored in a different partition.

See the relevant user manual for your storage device for further information about partitions.

The SD Card, that your commercial copy of C64 OS is installed on, comes with two partitions. The first partition is the C64 OS system partition. And the second is called "images."

It is recommended that you store disk images (.D64, .D71, .D81, .DNP) in the images partition. SD2IEC can mount a disk image directly. However, an image can only be mounted overtop of the partition in which the image is stored. When a disk image is mounted, the partition directory lists that partition as the type of image mounted in it. While the image is mounted, that partition becomes, temporarily, completely transformed into a partition that matches the type of the disk image. All the other data in that partition becomes, temporarily, inaccessible.

Having two partitions allows C64 OS to run from its system partition at the same time that an image is mounted in the second partition. Using File Manager, you can copy files between the partitions. This effectively allows you to copy files into and out of images, and thus between images, even if you only have a single drive (an SD2IEC) connected to your C64.

Speed and Compatibility

C64 OS uses the C64's KERNAL for its communications with storage devices. This provides the maximum compatibility with the widest array of storage devices, including non-standard devices that are not on the physical IEC serial bus, such as the IDE64, CMD RAMLink, or CMD HD connected via the parallel port on the RAMLink. Although standard KERNAL calls provide a high degree of compatibility, the stock C64 KERNAL is notoriously slow.

JiffyDOS or an equivalent alternative KERNAL ROM is highly recommended to improve access times to devices on the IEC serial bus. Using the KERNAL ROM provides maximum compatibility with the widest array of storage devices and their concurrent use.

JiffyDOS is a commercial product, and is available for purchase from Retro Innovations and from several other licensed vendors. Upgrading the stock C64 KERNAL ROM with a JiffyDOS KERNAL ROM is roughly analogous to updating the KickStart ROM in your Amiga; it is highly recommended. If you are not already a JiffyDOS user, you're missing out.

Device Limits and Open File Limits

On a C64, every device must be manually assigned a unique device number. Device numbers from 0 to 3 are built in. Device numbers from 4 to 7 are dedicated for printers and plotters. Device numbers from 8 to 30 are dedicated for storage devices.

C64 OS supports up to 5 storage devices, enabled and configured at the same time. Each device must have a unique device number. Each supported device (its type and device number) is detected when C64 OS boots and stored in a detected devices table. When a device is detected, a connection to that device's command channel is opened and automatically managed.

The set of devices can be reconfigured without rebooting C64 OS. You use the Drives Utility to reconfigure your drives; turn some on, turn some off, or exchange one for another. The Drives Utility can be accessed from the hardware section of the Settings Utility.

C64 OS uses the C64's KERNAL for its communications with storage devices. The C64 KERNAL allows for up to 10 logical files open at the same time. A logical file is an established connection between the C64 and a device. The connection to a device's command channel occupies one of the 10 logical files. Therefore, with just one configured device, C64 OS has 9 available logical files to use. With 2 configured devices, C64 OS has 8 available logical files, and so on. This is why C64 OS has a limit of 5 devices in concurrent use.

If for some reason you need more files open than there are logical files available, you can regain some of them by using the Drives Utility to turn off devices you don't need.

---

File References

If you're not familiar with how a regular C64 works, we recommend reading An Afterlife User's Guide to the C64, particularly the section on Devices and Channels from Part I, and also Reading and Writing Data Files in Part II.

From the READY prompt, on a regular C64, a file can be opened using the BASIC command open.

The open command takes several arguments, including the device number to connect to and the command string to send to that device. The command string has a syntax pioneered by CBM DOS but later extended by CMD's FD and HD DOS, which has subsequently become a standard used by IDE64 and SD2IEC as well. The command string specifies a filename, and may include a path, a partition number, and some additional flags. However, there has always been a fundamental division between how the device number is specified to the computer and how the partition, path and filename are specified to the device.

BASIC Syntax to open a file:

open LogicalFile#, Device#, Channel#, "CommandString"

Example usage:

open2,8,2,"5//path part 1/path part 2/path part3/:filename"

The 8 between the commas, above, is the device number. The string between the quotation marks is the command string sent to the device and interpreted by the device's DOS. In the command string, the 5 is a partition number, followed by a path that ends at the full colon and then the filename. The device itself has the concept a current partition as well as maintaining a current path within each partition. The command string may omit the partition number, and the current partition will be used. The path component may also be omitted and the current path of the partition will be used. Furthermore, a relative path may be used, which is appended to the current path of the partition.

Within the context of an operating system, it is not sufficient to rely on the device's internal concept of current partition and path, because different processes need to access files from different places at unpredictable times. The current partition or path cannot be relied upon by multiple processes.

To solve this problem, C64 OS provides a unified standard file reference format that is used throughout the operating system and its Utilities and Applications, that combines all the information about how to locate a file into a single string.

C64 OS File Reference format:

Device#:Partition#:Filename:Path

Example usage:

8:5:filename://path part 1/path part2/path part3/

Below, each component of the file reference format is explained:

Device Component

From the READY prompt, the device number was a BASIC constant or variable provided to the computer as an argument of a BASIC command. In a C64 OS file reference, the device number is part of the unified file reference format, and comes first.

Partition Component

On legacy devices there are no partitions and no subdirectories. The partition component is the CBM DOS drive number, this should always be 0 for 1541, 1571 and 1581 drives. The path component can be left blank, i.e., the file reference may be left with a trailing colon.

Example valid file reference to a 1541 drive, on device 8:

8:0:filename:

All modern devices support multiple partitions. On modern devices, the partition directory itself may be specified by using a zero for the partition #.

Example file reference to the partition directory of a modern device, on device 8:

8:0::

Any number greater than zero, on a modern device, specifies the partition number on that device.

Example valid file reference to a CMD HD, on device 8, partition 2, root directory:

8:2:filename://

Filename Component

The filename component may be left blank to refer to a place without specifying a file.

It may seem a strange decision to put the filename component before the directory path component. The natural hierarchical order would be:

Device Number → Partition Number → Directory Path → Filename

The filename and directory path were reversed to solve some practical problems on the Commodore 64. The screen has very limited resolution. The system's status bar has a built-in mode to automatically show the file reference of the currently opened or selected file. If the directory path came before the filename and it were longer than just a few characters the filename would be clipped away, and/or inconvenient to see. It is more important to see the open filename, with the full directory path clipped, than to see the start of a directory path and see no filename at all.

Additionally, there are underlying technical reasons that make it more efficient to find the filename if it preceeds the directory path. A filename has a maximum fixed length of 16 characters, but a directory path is more flexible. It has an arbitrary length which can be much longer than 16 characters.

Directory Path Component

The directory path component of a C64 OS file reference is structured identically to the path component of a command string sent to the DOS of a storage device.

The root directory is specified by two leading front slashes. Each subdirectory is added to the path by specifying the subdirectory name followed by a single trailing slash. The trailing slash is always required. See the example below, which shows the division of path segments as different colors.

The subdirectory depth of C64 OS file reference has some limitations. The limit is based on the total length of the path, not on the absolute number of nested subdirectories. The total length of the directory path, including all the slashes is 232 characters.

Each subdirectory may have a name from 1 to 16 characters in length. If all subdirectories are named to their maximum length, a file reference can specify a depth of approximately 13 subdirectories. If, on the other hand, subdirectories are named with their minimum possible length of one character, a file reference can specify a depth of approximately 115. Using an average of 8 characters per subdirectory a file reference can specify a depth of approximately 25.

In practice this limitation is unlikely to be reached.

Path Library

The Path Library is a standard library included with C64 OS that Applications and Utilities rely on to seamlessly manipulate file references.

The Path Library can be used to redirect a file reference to one of a set of standard customizable places. Those places: documents, games, music and pictures are customized using the Places Utility.

As seen in the image above, the places are customized by entering (or copying and pasting) standard C64 OS file references into the provided fields.

---

System Directory

By design, the various parts of C64 OS (components, drivers, libraries, Applications, Utilities, etc.) are contained within a single directory. That directory is called the system directory and the device it's found on is called the system drive or the boot drive.

It is possible to have more than one instance of C64 OS installed in the same partition. Each instance is contained in its own system directory. This could be useful for maintaining more than one version, or for having an installation for programming projects and another for general use. See below for instructions on setting up Multiple C64 OS Installations.

A system directory must be in the root directory of the partition. It cannot be nested within some other subdirectory. If you're concerned about putting junk in the root directory of your main (or only) partition, the good news is that C64 OS was designed to minimize the number of items required to be in the root directory.

A standard Unix or Linux installation requires around 15 items in the root directory. But in C64 OS, after installation, only two items must remain in the root directory:

• The booter, and
• The system directory

Documents and media files such as pictures, movies, music and more may be stored anywhere, including in other directories on the same partition, in other partitions, and on other disks and devices.

File Manager can move and copy files between any two places on your C64's storage devices, and Applications and Utilities can open and work with content and media files stored anywhere, inside or outside of the system directory.

The only files that need to be stored inside the system directory are C64-OS-specific resources.

System Directory Layout

Below is an outline of the main structure of the C64 OS system directory. Some of these system subdirectories are broken down into further detail in the sections that follow.

Directory/File	—	Description
c64os		The main C64 OS booter.
//os/		The C64 OS system directory.
applications/		Installed Applications.
Hello World		Bundle for Application "Hello World".
booter		KERNAL booter.
c64tools/		Useful non-C64-OS-native programs
calendar/		System wide calendar events.
2019-07/		Calendar events for July 2019.
4		Calendar events data file for July 4th 2019.
charsets/		Character sets.
boot.charset		Boot screen's logo character set
main.charset		Main character set; letters, numbers, symbols.
ui.charset		User interface character set
clipboard/		Current clipboard and additional clippings.
0.t		Current clipboard data type and size.
0.d		Current clipboard data content.
desktop/		App Launcher's multiple desktops.
1/		Aliases on desktop 1.
Hello World		Alias to application "Hello World".
1.p		Background PETSCII art desktop 1.
2/		Aliases on desktop 2.
2.p		Background PETSCII art desktop 2.
docs/		Documentation
drivers/		Hardware drivers
h/		Programming headers
icons/		Library of standard icons.
kernal/		C64 OS KERNAL modules.
library/		Components and libraries.
pointers/		Mouse pointers
prg aliases/		Aliases to traditional C64 software.
s/		Programming macros and constants.
screengrabs/		Screengrab saves screenshots to here.
services/		Special service applications.
App Launcher		An application launching, desktop-like environment.
File Manager		A file management application.
settings/		System settings. Globally saved Utility state files.
temporary/		Temporary files are scratched during boot up.
tk/		Toolkit class files and headers.
utilities/		Installed Utilities.
Calculator		Executable file for Utility "Calculator".
Today		Executable file for Utility "Today".

---

Useful directories to know about

Some of these directories, although necessary to make the system work, are not intended for the casual user to go into, unless you are a programmer or a hacker looking for ways to customize the system at a low level.

Some subdirectories, though, are useful to know about for regular users. Here are a few examples:

Installing Applications and Utilities

//os/applications/
//os/utilities/

Applications and Utilities must be installed in their respective subdirectories in order for the system to be able to find them and run them properly. If you download an Application or Utility from the internet, or write your own, to install it you simply place an Application bundle in the applications/ directory, or a Utility in the utilities/ directory.

An Application bundle is a subdirectory that contains the Application's many resource files. The easiest way to move an Application bundle is with the File Manager, which is designed to make recursively moving a subdirectory easy. See Application bundles below for more information about these.

C64 Tools

//os/c64tools/

The c64tools/ directory contains programs that are meant to be loaded and run from the C64's READY prompt. Many of these tools are useful for programmers, however, this directory also holds clean, original copies of the files required for installation:

• c64os
• c64os setup
• c64restore

See Appendix I. C64 Tools for information about several important C64 Tools and how to use them.

Calendar, the Today Utility.

//os/calendar/

The Today Utility can be opened by double-clicking the menu bar clock. Notes that are written on calendar dates are organized under the calendar/ directory.

Each month results in a subdirectory in the format:

//os/calendar/yyyy-mm/

A "toc" file is generated for the month, which is a table of contents for the dates with notes. The notes are stored in a file for each date. You can quickly remove all of the notes for a given month or a whole year by scratching the corresponding subdirectories using File Manager. You can also use File Manager to see an overview of the notes and open them with TextView.

Documentation

//os/docs/

The docs/ directory is used for documentation. The documentation is mostly useful for programmers, but the directory can also be used for your own personal document storage.

PRG Aliases

//os/prg aliases/

PRG aliases are metadata files that describe the installation location and critical metadata of traditional C64 software: games, demos, utilities, and other programs. PRG-type aliases on the App Launcher's desktop correspond to the PRG aliases configured in this directory.

From File Manager, opening a PRG alias runs the Opener Utility first. From there, PRG Runner can be selected as the opener from the list of Utilities. PRG aliases are also plain text files that can be viewed with TextView.

For more information about how PRG Runner works and how PRG aliases are structured, see the blog post series, Load and Run from 6502 ASM, Part 1 and Part 2.

Screengrabs

//os/screengrabs/

Screengrabs are taken using a system-wide keyboard shortcut that can be configured using the Configure Tool under the Global System section. The default keyboard shortcut is CONTROL+COMMODORE+P.

A screengrab is a PETSCII image that consists of 1000 screencodes, 1000 colorcodes, with a header that identifies the file's datatype, author and date of capture.

Screengrabs are written into the screengrabs/ directory, and are named automatically using the system's current time, in the format:

//os/screengrabs/:hh.mm.ssa.pet

Examples include:

//os/screengrabs/:02.40.46p.pet
//os/screengrabs/:12.38.05a.pet

A timestamp is used to name the file so that you can take multiple screengrabs one after the next, with at least one second between them, and each gets a unique filename. These files can be moved and renamed at a later time if you want to keep them. PETSCII image files can be viewed from the READY prompt using the program "petsciiview" found in the C64 Tools directory.

---

Below are listed some additional important subdirectories of the C64 OS system directory with some detail about how these are structured and what they contain.

Application bundles

C64 OS Applications are structured as bundles. A bundle is an ordinary subdirectory, but which contains a set of files with expected filenames and formats. An Application bundle, when viewed from File Manager, is shown with the App Launcher's rocket icon. Double-clicking an Application bundle launches the Application rather than opening its bundle directory within File Manager.

Normal users should conceptualize an Application bundle as a single thing. But if you really want to explore the contents of an Application bundle in File Manager, select the Application and choose Copy Place from the Options menu, or press COMMODORE+C. Then, in any tab, paste by choosing Paste Place from the Options menu, or press COMMODORE+V. This procedure is outline in Chapter 8: File Manager → Navigation.

//os/		The root file system directory.
applications/		Installed Applications.
Hello World/		Bundle for Application "Hello World".
about.t		Application metadata file.
icon.charset		Application 3x3 icon.
main.o		Application main executable file.
menus.m		Application menus definition file.
open.fref.t		File reference of the last file opened.
open.i		App-Specific binary state save for utility "Open".
recents/		File references of recently opened files.

Within an Application bundle there are several standard files, listed above. Other resources specific to that Application are also found in the bundle.

Some Utilities, those that save custom state on a per Application basis, write their state file into the Application bundle of the App they are run over top of. The file open.i is written by the Open Utility. Utilities can write other files to the Application bundle in order to customize their content per Application.

The open.fref.t file allows the Open Utility to return to the place of the most recently opened file in an Application. This place will be different for every Application. Additionally, the list of recently opened files is maintained on a per Application basis, in the recents subdirectory.

Drivers

//os/drivers/

C64 OS version 1.0 ships with 3 driver types. With other types in the planning stages for future release. Drivers abstract different physical hardware devices that share a single purpose. Such as setting the date and time, controlling the mouse pointer, printing, or accessing a network.

The driver types in version 1.0 are: Joystick, Pointer Input, and Realtime Clock.

Joystick (joy.*)

C64 OS provides a game controller interface for up to 4 controllers with 8 buttons each. Joystick drivers map physical hardware to the abstract C64 OS game controller interface. Games for C64 OS can read from the game controller interface and gain automatic support for every type of joystick and every type of 4 player adapter for which there has been a driver written.

The NES game controller drivers support the standard NES controller modification, documented and discussed in the weblog posts, NES to C64 Controller Mod and NES to C64 Controller Mod Part 2.

The 4 player version of this driver supports 4 modified NES controllers, two of which are connected via the original "Bombmania" 4 player adapter.

The modified NES Controllers are fully backwards compatible with regular (5-button) C64 joysticks. Therefore, for two regular joysticks, use joy.nes 2 player, and for four regular joysticks via the 4 player adapter, use joy.nes 4 player.

Modified NES Controller for C64 (left). An original 5 button joystick from Commodore (right).

Pointer Input (ptr.*)

The pointer input drivers control the so-called mouse pointer. Use of an actual mouse to control the pointer depends on choosing a mouse pointer driver. There is a driver for the 1351 mouse, which can be used with 1351-compatible adapters for USB and PS/2 mice. A driver is planned with support for the extra buttons and mouse wheel supported by the MicroMys protocol.

Although a true proportional mouse provides the best experience, drivers exist to provide several alternatives to a mouse. Standard 5-button joysticks in port 1 or 2 can be used, as well as a light pen in port 1. The Koala Pad in port 1 has a proportional driver that makes it behave like a modern trackpad.

A driver for the C128 numeric keypad exists too. If running C64 OS on a C128 in 64 mode, the buttons on the C128's numeric keypad can be used the same way as a standard 5-button joystick.

MicroMys v5, PS/2 Mouse Adapter (left). MouSTer, USB Mouse Adapter (right).

Realtime Clock (rtc.*)

C64 OS maintains a realtime clock in software. This is used to show the time in the menu bar clock, and to show the correct date in the Today Utility, among other things. Because the C64 does not have an RTC chip built-in, it requires reading the system time from external hardware that does. A driver must be selected to specify the source for this RTC, which is read during boot up.

There is a driver for IEC devices that have an RTC, this supports CMD HD, FD, RAMLink, IDE64 and SD2IEC devices, which all use compatible DOS commands.

The ultimate RTC driver can be used to access the RTC on a 1541 Ultimate or Ultimate 64 via the Ultimate Command Interface, which can be enabled in their menu systems.

In the absence of one of the above options, the DS3231 is a standard RTC chip that is available on an inexpensive Arduino module. The module communicates via an I2C bus. C64 OS has an I2C library that enables communication with I2C devices via the User Port.

DS3231 RTC Arduino Module (left). 1541 Ultimate II+ (right).

If no RTC chip is available, the manual RTC driver is used. This reads a static date/time from a settings file.

//os/settings/:time.manual.t

In the format:

yyyy/mm/dd HH:MM:ss

Drivers for pointer input and realtime clock can be selected using the Configure Tool. See Chapter 3: Configuration and Settings → Configure Tool.

Below are some example items found in the drivers/ directory:

//os/		The root file system directory.
drivers/		Relocatable drivers
joy.nes 2 player		2 player NES Game Controller Driver
joy.nes 4 player		4 player NES Game Controller Driver
ptr.1351 mouse		1351 Mouse Pointer Driver
ptr.c128 keypad		C128 Keypad Pointer Driver
ptr.joystick 1		Joystick in Port 1 Pointer Driver
ptr.joystick 2		Joystick in Port 2 Pointer Driver
ptr.koala pad		Koala Pad Pointer Driver
ptr.light pen		Light Pen Pointer Driver
rtc.ds3231 i2c		DS3231 over I2C RTC Driver
rtc.iec device		RTC Driver for CMD FD/HD/RAMLink, IDE64 or SD2IEC
rtc.manual		Set date/time manually from //os/settings/:time.manual.t
rtc.ultimate		RTC Driver for 1541 Ultimate and Ultimate 64

Installing New Drivers

New drivers can be installed by copying them into the drivers/ directory. Drivers must be in the drivers/ directory in order for the system to find them and load them.

Which drivers are selected to be used are specified in the global settings file, drivers.t.

//os/settings/:drivers.t

Since a change of drivers usually requires a change of hardware, most driver changes require a reboot to be made active.

See Appendix IV. Drivers for a complete list of drivers included in C64 OS version 1.0.

Libraries

//os/library/

C64 OS version 1.0 ships with over 15 libraries. Libraries contain common reusable code that Applications, Utilities, drivers or even other libraries can include to make development easier and to make behavior across the system more consistent.

New and updated versions of libraries are installed by copying them into the library/ directory. This allows the system to find them when an Application or Utility attempts to load them.

Components

In addition to proper shared libraries, the library/ directory also holds components necessary to the system. Such as the exception handler, the Application loader, the Utility framework, and some important files used while booting up.

Below are some example items found in the library/ directory:

//os/		The root file system directory.
library/		C64 OS components and shared libraries
crash.lib.r		Crash library for uncaught exceptions.
dir.lib.r		Directory library
exceptions.o		Exception handling component
fcopy.lib.r		File copy library
flock.lib.r		File lock/unlock library
i2c.lib.r		I2C bus over User Port library.
path.lib.r		File reference manipulation library
loader		Application loader
loaders		Data File Loaders
img.art.r		Loader for Art Studio image files.
img.hed.r		Loader for Hi-Eddi image files.
img.koa.r		Loader for Koala image files.
qsort.lib.r		Quicksort library
sidplay.lib.r		Library for loading and playing PSID files.

See Appendix VII. Libraries for a complete list of all libraries included in C64 OS version 1.0.

Loaders

//os/library/loaders/

The library directory is also home to loaders. These are found in a loaders subdirectory, and consist of small specialized libraries that know how to allocate memory and load data from a file in a certain format into that memory. Each loader can also supply metadata to an Application about the loaded data. Loaders are selected automatically by matching a file's extension against part of the loader's name.

The first part of the loader's name is its general data type, the second part is the extension of the file.

Below are some example items found in the library/loaders/ directory:

//os/		The root file system directory.
library/		C64 OS libraries
loaders/		data type loaders
img.art.r		Art Studio
img.cdu.r		CDU-Paint
img.cgx.r		Commodore Grafix
img.cwg.r		Create with Garfield
img.ddl.r		Doodle
img.hbw.r		HiRes Black & White
img.hed.r		HiEddi
img.iph.r		InterPaint
img.koa.r		Koala Paint
img.ocp.r		Advanced Art Studio
img.pbot.r		PETSCII Bots
img.pet.r		PETSCII Graphic
img.pi.r		Blazing Paddles
img.rpm.r		RUN Paint

Savers

//os/library/savers/

The library directory is also home to savers. These are found in a savers subdirectory, and consist of small specialized libraries that know how to save data to a file from structured memory in a compatible format. Savers must be selected programmatically by the file extension used by the file format that supports the data to be saved.

The first part of the saver's name is its general data type, the second part is the extension of the file.

Below are some example items found in the library/savers/ directory:

//os/		The root file system directory.
library/		C64 OS libraries
savers/		data type savers
img.art.r		Art Studio (HiRes Bitmap Graphics)
img.koa.r		Koala Paint (MultiColor Bitmap Graphics)

Settings

//os/settings/

The settings/ directory contains all of the system's settings files, as well as state files saved by Utilities that do not preserve custom state per Application.

The configure program, run from the READY prompt is also found in this directory, and used to configure the main settings required to get C64 OS running on your hardware. Once booted most settings can be customized from within C64 OS itself. Settings that can't yet be configured from within C64 OS, will be supported by Utilities in future releases.

Below are some example items found in the settings/ directory:

//os/		The root file system directory.
settings/		System settings. Globally saved utility state files.
assigns/		Holds assignments of Applications and Utilities to open files by type.
components.t		List of components loaded during boot.
docs.path.t		File reference to documents directory used by File Manager.
favorites/		Holds favorites shown in File Manager and Open and Save Utilities.
homebase.t		Specifies last accessed homebase: App Launcher or File Manager.
memory.i		State file automatically generated by Memory Utility.
modules.t		List of KERNAL modules loaded during boot.
theme.cus.t		Custom color theme defined by the Themes Utility.
time.manual.t		Manual date/time string used by rtc.manual driver.
version.t		Holds the C64 OS version number shown by About C64 OS Utility.

See Appendix VIII. Settings for a more thorough list of settings files.

---

Multiple C64 OS Installations

It is possible to have more than one instance of C64 OS installed in the same partition. Each instance is contained in its own system directory. This could be useful for maintaining more than one version, or for having one installation for programming projects and another for general use.

The main C64 OS booter, (c64os found in the root directory of the partition in which C64 OS is installed,) is a self-modifying BASIC program. When you change the name of the system directory, or if you move the system directory to a different partition, or change the device number of the boot drive, the booter has to be updated with information about where its system directory is located.

Step 1: Moving an Installation

The procedure to rename or relocate the system directory is, in essence, the first step in having multiple installations of C64 OS in the same partition. An overview about the installation location of C64 OS and how to change the installation location are given in Chapter 2: Installation → About Installation Location.

Familiarize yourself with moving an installation before going on to step 2.

Step 2: Duplicating the Booter

The booter is self-modifying. The first time the booter is run, it is a clean copy that does not hold any information about the installation location. Why is it setup like this? Because, even a commerical copy of C64 OS, run directly from the preinstalled system directory on SD Card, doesn't know what device number will be used for the SD2IEC device.

When the setup tool updates the booter, it does so by loading the booter by name, c64os, and passing to it the install location. The booter then modifies itself and saves itself back to the name, c64os.

The trick to having multiple installations in the same partition is to configure the booter for the new location, then rename the booter to match that installation, then make a clean copy of the booter from the c64tools directory back to the root directory, and configure it for the other installation location. Now you have two installation directories and two booters, each booter having explicit knowledge about its installation location.

Creating a Duplicate Installation, Step-by-Step

Below are the step-by-step instructions to duplicate a C64 OS installation, from its default path (//os/) to a new path with a version number in it (//os1.1/). And then the steps to create and configure two booters, one each to boot the two different system directories.

1. Boot into C64 OS, and switch to the File Manager.
2. In tab 1, navigate to the root directory of the installation partition.
   1. Choose System from the Go menu, then
   2. Choose Parent Directory from the Go menu.
3. Create a new directory.
   1. Choose New → Directory from the File menu.
4. Rename the new directory to the alternative system directory name, e.g., "os1.1"
   1. Choose File Info from the File menu, then
   2. Type the new name into the field and click Rename.
5. Double-click the new empty system directory to open it in tab 1.
6. Switch to tab 2, and navigate to the current system directory.
   1. Choose System from the Go menu.
7. Select all items in the system directory.
   1. Choose Select All from the Options menu.
8. Copy the selected items to the new system directory in tab 1.
   1. Choose Copy To → Tab 1 from the File menu.
9. When the copy is complete, quit to BASIC.
   1. Choose Quit to BASIC from the Options menu.
10. Load and run the setup tool from the c64tools directory of either system directory.
    1. load"//os/c64tools/:c64os setup",8
    2. run
11. Specify the install location of the new system directory, including its new name, then quit back to BASIC.
12. Rename the booter to match the new system directory.
    1. open15,8,15,"r:c64os1.1=c64os":close15
13. Make a clean copy of the booter from the c64tools directory to the root directory.
    1. open15,8,15,"c:c64os=//os/c64tools/:c64os":close15
14. Load and run the setup tool, again, from the c64tools directory of either system directory.
    1. load"//os/c64tools/:c64os setup",8
    2. run
15. Specify the install location of the original system directory, then quit back to BASIC.

You now have two copies of C64 OS in the same partition. In the root directory of that partition you now have two system directories and two booters:

• //os/
• //os1.1/
• //c64os
• //c64os1.1

Note that, the self-modifying booter only knows how to save itself to the default name "c64os". Therefore, subsequent to all the above, if you wanted to rename that system directory from "os1.1" to, say, "os 1.1", you would need to configure the booters again which requires a bit of renaming.

For example, you could rename the directory "os1.1" to "os 1.1", then scratch "c64os1.1". Load and run the setup tool, and use it to configure "c64os" to point to the new "os 1.1" path. Then rename that "c64os" booter to "c64os1.1". Copy a clean booter from the c64tools directory back to the root directory and configure it to point to the original system directory again.

Alternatively, you could set aside "c64os" by renaming it temporarily to a new name. Then rename "c64os1.1" to the default name "c64os". Use the setup tool to configure "c64os" to point to the new "os 1.1" path. Rename that booter back to "c64os1.1", and then restore the original "c64os" by renaming it from its temporary name back to "c64os".

Once you get into advanced configurations, multiple installations, multiple versions, etc., there is no one way to do this. The above instructions are all just examples to illustrate the concept to an advanced user who is comfortable working with files.

---

Open and Save

An operating system provides standard dialog boxes that Applications can invoke to pick a file to be opened, or to input a filename and pick a place to save a file. These dialogs are provided in C64 OS as standard Utilities, called Open and Save, respectively.

Both Utilities come in a few different modes, and provide a number of useful features.

Standard Features of Open and Save

Open and Save have a similar layout to one another, and also have some similarities with File Manager. The main layout is in a vertical split. The places sidebar appears on the left and the directory of files appears on the right. The split can be dragged left and right to adjust how much you can see of either side.

Places Sidebar

In the places sidebar on the left, the top shows the list of currently available devices. Each device has an icon, its device number and the name of the type of device, followed optionally by a checkmark. The checkmark indicates from which device the directory on the right is showing. Click a device to change to that device. Modern devices have multiple partitions, and so clicking on a device takes you first to that device's partition directory.

The device's section can be opened or closed, to provide more room for the list below it, by clicking on the devices section header.

Open Utility with devices list open (left), and devices list closed (right).

Below the list of devices is a section for the list of favorites and recents. You can toggle between the two lists by clicking the section header. If the section header says favorites, it's showing favorites. Click it to cycle to recents. If it says recents, click it to cycle to favorites. Each Utility, on a per Application basis, remembers the state of whether the devices section is opened or closed, and whether the list is showing recents or favorites. However you leave it when the Utility closes, it will later reopen in that mode.

Favorites

There can be up to 15 favorites in the favorites list. Favorites are shortcuts to places, a path in a partition on a device. The same set of favorites is shown in both the Open and Save Utility. Favorites can be added to the list from File Manager. See Chapter 6: File Manager → Favorites for more information about creating and managing favorites.

Open Utility showing favorites list (left), and recents list (right).

Recents

There can be up to 15 recents in the recents list. Recents are shortcuts to files that were recently opened or saved. Recents are remembered on a per Application basis. This means if you open some text files in a text editor and some pictures in an image viewer, the list of recents in the Open Utility within that text editor only show the text files, and the list of recents—in the same Open Utility but within the image viewer—only shows the recently opened pictures. Thus, although it only lists 15 recents, you in fact have access to many more recents when considered across multiple Applications.

The list of recents shown in the Save Utility is the same as the list shown in the Open Utility. A recent is added to the top of the list of recents whenever a file is selected to be opened from the Open Utility, or Saved from the Save Utility. The list of recents are bumped down one position to make room for the new item at the top. If there were already 15 recents in the list, the last item is removed from the bottom of the list.

If the item being saved to recents is already on the list, it is pulled out of its old position and moved to the top of the list. A recent is a shortcut to a file which can reside at any place in the file systems of your devices. However, recents in the list are unique by filename alone. Therefore, only one recent with a given filename may appear in the list, even if you have two files with the same name that come from different directories. When the second one is added, it removes the first one from the list.

Directory Navigation

Just like in File Manager, the list of files in the current directory can be sorted by clicking any of the column headers, and the columns can be resized. You can navigate into a subdirectory by double clicking a directory. To navigate back up the directory tree you can click on the path bar that appears above the directory listing.

To change device, or partition on the device, click on the device from the devices section at the top of the places sidebar on the left.

Keyboard Controls

As in File Manager, you can use COMMODORE+P to navigate to the parent directory, or COMMODORE+R to jump to the root directory of the current partition.

Also like in File Manager, in the Open Utility, the cursor keys can be used to move the selection, and COMMODORE+O can be used to trigger the Open button, or to navigate into a selected directory.

---

Open Utility

The Open Utility, like any other, can be manually opened, using for example the Utilities Utility. However, without the Application intentionally invoking it, it opens in file browse mode. In this mode, directory navigation works but the open button remains disabled.

An Application capable of opening a file provides an option to invoke the Open Utility and provides an open job. An open job customizes some options such as whether it should be in open or select mode. The mode it is in can be determined by whether the main button says "Open" or "Select."

Open Mode

Open is a one-shot mode. The Utility loads in, you navigate the file system, pick a file and then either click the open button, press return to trigger the open button, or double-click the file. The file gets added to the list of recents, a file open message is sent to the Application and the Utility closes automatically. This mode is used most often for opening documents.

Select Mode

Select mode is used for making continuous selections, one file after another. For example, if an Application allowed you to create, say, a playlist of SID music files, it would most likely invoke the Open Utility in select mode. You pick a file and then either click the select button, press return to trigger the select button, or double-click the file. The file gets added to the list of recents, a message is sent to the Application, but the Utility remains open. You can then immediately navigate to and select another file and repeat. When all files have been selected, the Open Utility can be closed using its close button.

The Application decides which mode is appropriate. Select mode greatly speeds up multiple file selections, because the Utility does not need to be closed and reopened between every file.

Validation

The open job supplied by the Application may also provide a validation routine. Each time a file is selected, information about the selected file is sent to the Application to be validated.

The validation routine can check for anything relevant. It could check for the CBM file type, PRG, SEQ, DIR, etc. It could check for the file's block size, filename extension, or the place where the file is located. If the validation fails, the open/select button is disabled. Only if the file passes validation is the open/select button enabled. The Application is free to be as permissive or restrictive as it needs to be.

Copy a File Reference

Beginning in C64 OS v1.04, the current place, including a filename if a file is selected, may be copied to the clipboard, as a file referencem, with the standard keyboard command, COMMODORE+C.

Typically, the Open Utility is only useful when it is explicitly opened by an Application. This is because the Application has to provide it with an open job for the open or select button to be enabled. However, with the ability to copy a file reference to the clipboard, the Open Utility becomes useful in file browse mode, as a generic file picker that can be used within any Application.

For example, from App Launcher. Open the Utilities Utility. From that list, pick the Open Utility. Because App Launcher didn't send the Open Utility a file job, the open button will remain disabled. Nonetheless, navigate the file system to find a SID music file, select it and press COMMODORE+C. A file reference to that SID file is on the clipboard. Close the Open Utility, and use the Utilities Utility to select and open SID Preview. SID Preview has the ability to load a file by pasting a file reference from the clipboard. Press COMMODORE+V to paste the file reference from the clipboard to SID Preview.

---

Save Utility

The Save Utility, like any other, can be manually opened, using for example the Utilities Utility. However, without the Application intentionally invoking it, it opens in file browse mode. In this mode, directory navigation works but the save button remains disabled.

An Application capable of saving a file provides an option to invoke the Save Utility and provides a save job. A save job customizes some options such as whether it should be in save or create mode. The mode it is in can be determined by whether the main button says "Save" or "Create." In create mode, the title of the Utility is shown as "New File."

Save vs. Create

Save and create are only conceptually different, their behavior is identical. Save is used when the Application already has some data, and the user wishes to write that data out to a new file. Create is used when the Application needs to have a new file created that will store data that has not yet been produced. It's a subtle but meaningful difference.

Extra Fields

The Save Utility is very similar to the Open Utility with two noticeable differences. Above the list of files is a text field into which you can enter the filename. And at the bottom left is a checkbox labeled "Allow Overwrite."

The Application's save job provides a limit on the length of the filename. Sometimes the field will not allow you to enter a full 16 characters. This usually happens when the Application is reserving some characters to add a required extension.

The save job may also include a validation routine. Unlike with the open job's validation routine, the file being saved or created doesn't yet exist; it has no CBM file type and it has no filesize yet. The validation is performed on the proposed name of the file, and on the place where it will be saved.

The allow overwrite checkbox is set in the save job. The Application may set this flat automatically. If this checkbox is set it allows the application to overwrite an existing file with the new one.

Navigation

In the Save Utility, clicking a file does not select it. Instead, it copies the name of the file into the name field. This can be used in conjunction with the allow overwrite checkbox to pick a file that already exists to be overwritten.

Double clicking a subdirectory navigates into that subdirectory without changing the contents of the name field.

Clicking a favorite takes you to that place, without changing the contents of the name field. Clicking a recent takes you to that place, and puts the name of the recent into the name field.

---

Next Chapter: The Philosophy of C64 OS

Table of Contents

This document is subject to revision updates.

Last modified: Sep 10, 2023