DOS Packets¶

AmigaDOS filesystems communicate with their callers via DOS packets (struct DosPacket). Packets are the internal IPC mechanism between the DOS API layer (Open, Read, Seek, etc.) and filesystem handler processes (FFS, CrossDOS, custom handlers in L:).

How packets work¶

The application calls a dos.library function (e.g., Read()).
DOS translates the call into a packet and sends it to the filesystem handler's message port via SendPkt() / DoPkt().
The handler processes the packet and replies via ReplyPkt().
The calling process receives the reply and the dos.library function returns.

For most application code, packets are invisible — dos.library wraps them. Packets matter when you write a custom filesystem/handler or when you need a packet that has no dos.library wrapper.

Key packet types¶

Packet	Corresponding API	Notes
`ACTION_FINDINPUT`	`Open(... MODE_OLDFILE)`	Open for read
`ACTION_FINDOUTPUT`	`Open(... MODE_NEWFILE)`	Open for write
`ACTION_READ`	`Read()`
`ACTION_WRITE`	`Write()`
`ACTION_SEEK`	`Seek()`
`ACTION_EXAMINE_OBJECT`	`Examine()`
`ACTION_EXAMINE_NEXT`	`ExNext()`
`ACTION_DELETE_OBJECT`	`DeleteFile()`
`ACTION_RENAME_OBJECT`	`Rename()`
`ACTION_CREATE_DIR`	`CreateDir()`
`ACTION_SET_PROTECT`	`SetProtection()`
`ACTION_EXAMINE_ALL`	`ExAll()`	V36+ bulk directory read
`ACTION_PARENT`	`ParentDir()`
`ACTION_CURRENT_VOLUME`	(no direct API)	See clarification below

V39 additions (from Randell Jesup's NewDosPackets notes)¶

Three new packets were added in V39:

ACTION_EXAMINE_ALL_END — Same arguments as ACTION_EXAMINE_ALL. Signals the handler that the caller is done with an ExAll scan early (before all entries were consumed). The handler can release any internal state it was maintaining for the scan.

ACTION_SET_OWNER — Same structure as ACTION_SET_PROTECT, but the data is a longword of owner info: high 16 bits are GID (group), low 16 bits are UID (user id). Corresponds to the SetOwner() dos.library function.

ACTION_SERIALIZE_DISK — Takes no parameters. Makes the filesystem change the disk to make it unique (normally by modifying the creation date). Used by diskcopy with non-Amiga filesystems. Returns standard error codes.

ACTION_CURRENT_VOLUME clarification¶

There was confusion about this packet. The correct behavior: if arg1 is NULL, the packet returns the current volume and unit number. If arg1 is fh->fh_Arg1 of a file handle, the packet returns the volume and unit number for that specific filehandle. Both interpretations are correct depending on the argument.

Async packet serialization — critical gotcha¶

If a process asynchronously sends two packets to the FS that refer to the same file (e.g., two CMD_READ requests), they MUST be serialized. A multithreaded FS might try to execute them in parallel.

This is from Randell Jesup (Amiga filesystem engineer):

The Amiga FS IS multithreaded (BCPL coroutine threading). Each filehandle has a separate coroutine to handle IOs for that FH, with a 1K stack.
Serialize access per-filehandle, not just per-process. Two processes sharing one filehandle is rare but possible, and they're probably cooperating and depending on ordering.
Martin's (vertex's) async IO code does this serialization and was widely distributed to developers.

Practical rule: Don't send two packets for the same file handle simultaneously unless you handle serialization yourself. For application-level async IO, use a single outstanding request per file handle, or use an async-IO library that serializes for you.

DoPkt vs SendPkt¶

LONG DoPkt(struct MsgPort *port, LONG action, LONG arg1, ...);  /* synchronous */
void SendPkt(struct DosPacket *packet, struct MsgPort *port);   /* asynchronous */
struct DosPacket *WaitPkt(void);                                 /* wait for reply */
void ReplyPkt(struct DosPacket *packet, LONG res1, LONG res2);   /* handler replies */
LONG AbortPkt(struct MsgPort *port, struct DosPacket *pkt);      /* try to abort */

DoPkt blocks until the handler replies. SendPkt returns immediately; caller waits via WaitPkt.

Bug note: As of V37, AbortPkt() does nothing. Do not rely on it to cancel asynchronous packets.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search