Host Directory Filesystem Metadata

Host Directory Filesystem Metadata

When Amiberry mounts a host directory as an Amiga volume (via Add Directory in the HDD Panel), it needs to handle the differences between Amiga and host filesystem naming conventions and metadata.

UAE Filename Escaping

Amiga filenames can contain characters that are illegal or problematic on host filesystems (Windows, macOS, Linux). The UAE filesystem layer automatically translates these using %xx hex encoding:

Amiga Filename	Host Filename	Reason
*BLUE3	%2aBLUE3	* is a wildcard on host
IFT?	IFT%3f	? is a wildcard on host
Booster???.iff	Booster%3f%3f%3f.iff	Multiple ? characters
noisy pillars 99%.ahx	noisy pillars 99%25.ahx	% itself must be escaped
USE A DATA DISK	USE A DATA DISK%20	Trailing space
hund.	hund%2e	Trailing period

Escaped Characters

The following characters are encoded as %xx when saving Amiga filenames to the host filesystem:

Character	Hex Code	Reason
%	%25	Escape character itself
\	%5c	Path separator (Windows)
*	%2a	Wildcard
?	%3f	Wildcard
"	%22	Quoting character
/	%2f	Path separator
|	%7c	Pipe character
<	%3c	Redirection
>	%3e	Redirection
Control chars (0-31)	%xx	Non-printable

Compatibility

This escaping scheme is compatible with FS-UAE. Host directories prepared for FS-UAE (including %xx-escaped filenames) will work correctly when mounted in Amiberry.

Note: Amiberry improves on FS-UAE's decoder by validating that both characters after % are valid hexadecimal digits before decoding. A literal % followed by non-hex characters (e.g., 99%.ahx) is passed through unchanged rather than being silently corrupted.

.uaem Sidecar Metadata

Amiga files have metadata that host filesystems cannot natively represent:

• Protection bits: HSPARWED (Hidden, Script, Pure, Archive, Read, Write, Execute, Delete)
• File comments: Free-form text notes attached to files
• Timestamps: Amiga uses a different time format with 1/50-second (tick) precision

Amiberry stores this metadata in .uaem sidecar files — small text files placed alongside each file that needs non-default metadata.

.uaem File Format

For a file named myfile.txt, the sidecar is myfile.txt.uaem:

----rwed 2024-03-15 14:30:22.50 optional file comment

Field	Position	Format	Description
Protection	Chars 1-8	hsparwed or -	Each char: flag letter if set, - if not
Timestamp	After space	YYYY-MM-DD HH:MM:SS.CC	UTC time, CC = centiseconds
Comment	After timestamp + space	Free text	Optional, up to end of line

Protection Bits

Position	Letter	Amiga Bit	Meaning
1	h	HIDDEN	File is hidden
2	s	SCRIPT	File is a script
3	p	PURE	File can be made resident
4	a	ARCHIVE	File has been archived
5	r	READ	Read permission
6	w	WRITE	Write permission
7	e	EXECUTE	Execute permission
8	d	DELETE	Delete permission

Default protection for new files is ----rwed (read, write, execute, delete allowed).

Smart Writing

Amiberry only creates .uaem sidecar files when metadata differs from defaults:

• Protection bits are not ----rwed
• A file comment is set
• Timestamp precision would be lost by the host filesystem

This means no .uaem files are created for normal usage — they only appear when Amiga programs explicitly change file attributes, add comments, or when preserving FS-UAE-compatible trees.

Compatibility

Format	Read	Write	Notes
.uaem sidecars (FS-UAE)	Yes	Yes	Full read/write support
_UAEFSDB.___ (WinUAE)	Yes	Yes	Binary format, takes priority over .uaem when both exist

Configuration

filesys_no_fsdb

filesys_no_fsdb=false

• false (default): Enable filesystem metadata support (.uaem sidecars and _UAEFSDB.___)
• true: Disable all metadata — files use host permissions only, no comments or Amiga-specific protection bits

filesys_custom_uaefsdb

filesys_custom_uaefsdb=true

• true (default): Enable .uaem sidecar support for name translation and metadata
• false: Only use _UAEFSDB.___ binary format

Troubleshooting

Files with special characters not appearing

If files with names like %2aBLUE3 are not visible from the Amiga side, check:

1. The host directory is mounted as a virtual filesystem directory (not a hardfile)
2. filesys_no_fsdb is set to false in your configuration
3. The Amiberry log does not show illegal filename or illegal directory name errors

.uaem files appearing in my host directory

This is normal behavior when Amiga programs change file attributes or add comments. The .uaem files are automatically hidden from the Amiga side. They are small text files that can be safely deleted if you don't need to preserve Amiga metadata.

Migrating from FS-UAE

Host directory trees prepared for FS-UAE (with %xx-encoded filenames and .uaem sidecars) should work directly when mounted in Amiberry. No conversion is needed.