ARCFS(5)

okay so hi bestie 💖 you just opened ARCFS(5) — that's section 5, the File Formats Manual one — and it is literally all about the ArcFS archive file format for the RISC OS ArcFS filesystem. we are decoding bytes together today and it's gonna be iconic, no cap. 🦋

✨ NAME ✨

ArcFS — the archive file format for the RISC OS ArcFS filesystem. that's the whole vibe. 👑

🎀 CONVENTIONS 🎀

before we get into it, house rules bestie, so we're all speaking the same language:

• Strings are given in ASCII with C-style escapes. and there's no terminating byte present if it's not explicitly included — so don't go looking for one, she's not there. 🙈
• Words are 32 bit little-endian numbers. words. thirty-two bits. little-endian. okay? okay.
• Half words are 16 bit little-endian numbers. half the word, all the endian. ✨
• This doc describes format version 0 (for ArcFS minimum versions 0.40 and 1.00) and version 0a (for ArcFS minimum versions 0.58 and 2.17). two eras, both iconic. 💅

🌈 FORMAT 🌈

the file is built like a lil sandwich, in this exact order:

1. a file header
2. a sequence of archive headers
3. a sequence of compressed files

that's it. that's the whole structure. slay. 🥪

💜 FILE HEADER 💜

the opening act. here's what's in it, field by field:

• File string signature — the string "Archive" followed by a zero byte. like a lil name tag at a party. 🎀
• Header length — length of header info in bytes, one word, multiple of 36. yes, a multiple of 36, she does not do random numbers.
• Data offset — offset, in bytes, into archive at which data starts, one word.
• Read-only version — minimum read-only version required, multiplied by 100, one word.
• Read-write version — minimum read–write version required, multiplied by 100, one word.
• Reserved — reserved for future use, 68 bytes. she's just sitting there, holding space for the future. 🫶

👑 ARCHIVE HEADER 👑

okay so the last header starts at 60+length of headers and ends at 96+length of headers. got that? write it down bestie. the format of each header goes like this:

• Info byte — the object information byte, shows the compression method used:
  • 0x00 — end of directory marker
  • 0x01 — object has been deleted
  • 0x82 — stored
  • 0x83 — packed
  • 0x88 — crunched
  • 0xFF — compressed
• File name — file name, 11 bytes.
• Full length — original file length, or 0xFFFFFFFF for a directory, one word.
• Load address — load address of the file, or 0xFFFFFFdd for a directory, one word.
• Exec address — exec address of the file, or 0xdddddddd for a directory, one word.

quick note bestie: the file load and execution address may contain a filetype and datestamp as normal. 📅

and directories can be date-stamped too! the number of centiseconds since the 1st January 1900 when the directory was created are given by &dddddddddd contained in the directory's load and execution addresses as shown above. she remembers her birthday. 🎂

also, archives converted from spark(5) format using ArcConv will have the same full length, compressed length, load address and execute address as they had in the Spark archive. no glow-up, no downgrade, same energy. ✨

• Attributes — attributes of the file, one word. contains the number of bits compression for crunch and compress format files, and the least significant bytes contains the standard RISC OS information on file access.
• Compressed length — length of compressed data, or 0xFFFFFFFF for a directory, one word.
• Information word — the top bit (definitively) indicates whether the object is a file or a directory: 0 for a file, 1 for a directory.
  • in the case of a file, the least significant 31 bits show the offset from the start of data at which the file data can be found.
  • in the case of a directory, the least significant 31 bits show the offset from the start of headers (96) at which the next object in this directory can be found, the following object being the first in the sub-directory.

that top bit is doing SO much heavy lifting honestly. 💀

🦋 FORMAT VERSION 0a 🦋

this archive format is backwards compatible with versions 0.40 and 1.00, and the only difference is that there's a block of catalogue information immediately prior to the start of each file's data, as described below. she's the same girl, she just got a lil extra. 💅

note bestie: this information is there to aid the recovery of most files in the event of archive corruption, and it is not used by ArcFS. it's like a backup bestie who's just vibing in the background. 🫶

also note: Compact and Autocompact in release versions 1.09, 2.02 and 2.11 will compact out the catalogue information blocks, so try to avoid writing to new archives with old versions of ArcFS. seriously. don't do it. that's your recovery info getting deleted. 😭

here's what's in that block, in order:

• Marker — a marker to indicate the start of a file, the string "FileData", not terminated.
• Info byte — one byte, as above.
• Leaf name — the file name, 11 bytes.
• Full length — one word, as above.
• Load address — one word, as above.
• Exec address — one word, as above.
• Attributes — one word, as above.

🌟 SEE ALSO 🌟

go read these next, they're the friends of this page:

• spark(5)
• nspark(1)

and that's the whole page bestie!! 🎀 this was ARCFS(5) from the File Formats Manual — you can find her in section 5 of your manual pages, and this is the version that lives in that manual right now. go forth and archive responsibly. mwah. 💖✨🌈🦋👑