Appendix C
System calls and errors
Beacon takes the same route to the monitor and the disk. Its assembler emits a software interrupt instruction (SWI2) followed by one service byte. NitrOS-9 reads that byte, consults the process’s registers, and dispatches the request. A successful write returns to the next instruction in Beacon. An exit ends the process.
The two calls in Beacon
| Service | Before the call | After the call | Where you can see it |
|---|---|---|---|
| I$WritLn · $8C | A holds the output path number. X points to the first byte. Y holds the maximum count. The buffer contains a carriage return. | On success carry is clear and Y gives the count written. The line write honors the first carriage return within that limit. On failure carry is set and B identifies the error. | Follow the buffer through the assembler listing and change its destination. |
| F$Exit · $06 | B holds the exit status. Beacon supplies zero after success or the error number returned by the write. | Control passes to the operating system. A waiting parent can receive the child’s ID and status. | The shell accepts a new command after Beacon finishes. See the process lesson for the parent’s view. |
I$ identifies an I/O request and F$ a kernel service. Both use the OS-9 calling convention. The mnemonic after the prefix matters: I$Write takes a byte count and can transmit binary data containing carriage returns. I$WritLn has line semantics. For software that reads a line, I$ReadLn takes a path in A, buffer address in X and capacity in Y, and returns the actual count in Y on success. Keep the numeric path separate from the address of the character buffer.
I/O service finder
These are the named I/O requests in this image’s system definitions. File managers implement operations appropriate to their devices. For example, seeking to a byte position makes sense on a disk file. A terminal has different status operations. The device chapter shows how OS-9 chooses the file manager.
| Service | Request |
|---|---|
| I$Attach, I$Detach | Acquire or release an attachment to a named device. An open path can keep the device in use. |
| I$Dup | Get another path number referring to an existing open path. |
| I$Create, I$Open, I$Close | Create a new entry and open it, open an existing object in an access mode, or release an open path. |
| I$MakDir, I$ChgDir | Create a directory or change the calling process’s working directory for data or execution. |
| I$Delete, I$DeletX | Delete using the data directory, or specify the mode used to resolve the pathname. |
| I$Seek | Move the position associated with a random-access file. The next transfer starts there. |
| I$Read, I$Write | Transfer a counted buffer. Check the returned count as well as carry. |
| I$ReadLn, I$WritLn | Transfer a line using a bounded buffer. The terminator matters. |
| I$GetStt, I$SetStt | Inquire about or change a path/device setting. A second function code determines the operation, its registers and whether the manager supports it. |
Services encountered by a user program
Use this index to recognize names in source, disassembly and the guest’s /DD/DEFS/os9.d. The definition file assigns numbers across several OS editions and extensions. A name in the file does not establish permission or implementation in the running kernel.
| Look for | Services and their purpose |
|---|---|
| Start, replace or finish a process | F$Fork creates a child. F$Chain replaces the current program. F$Wait collects a child termination, and F$Exit supplies its status. |
| Process identity and scheduling | F$ID identifies the caller. F$SPrior sets an eligible process’s priority. F$Sleep waits for ticks, F$SSpd suspends, F$Send delivers a signal, and F$Icpt installs its handler. F$SSWI sets a software-interrupt vector. |
| Find and release modules | F$Link searches by module name. F$Load reads a file and links a module. F$UnLink releases a reference and F$UnLoad looks up the module to release by name. F$NMLink and F$NMLoad are non-mapping variants. |
| Measure and request memory | F$Mem adjusts the caller's data area. F$GPrDsc, F$GBlkMp and F$GModDr request copies of process, block-map and module-directory information. F$CpyMem copies across an address-space boundary subject to the kernel’s rules. |
| Process text, names and checksums | F$PErr writes a system error. F$PrsNam parses a pathname component and F$CmpNam compares names. F$CRC updates a cyclic redundancy check. F$SchBit, F$AllBit and F$DelBit search, allocate or clear bits in a map. |
| Clock and identity changes | F$Time reads the clock and F$STime sets it. F$Alarm and F$TimAlm concern alarms. F$TPS reports ticks per second. F$SUser changes a user identity subject to privilege checks. |
Services used inside the operating system
System code also uses SWI2 services. A driver running in system state can manipulate data structures an ordinary application must reach through a public service. Encountering a name here is a reason to identify the caller’s privilege and the exact kernel edition before adapting a listing.
| Facility | Names to look up and what they connect |
|---|---|
| Interrupts and scheduling | F$VIRQ, F$IRQ and F$SSvc install service entries. F$IOQu, F$AProc and F$NProc manage I/O waits and runnable processes. |
| System storage and descriptors | F$SRqMem and F$SRtMem acquire and release system storage. F$Find64, F$All64 and F$Ret64 locate, allocate and release descriptor slots. F$AllPrc, F$DelPrc and F$GProcP concern process descriptors. |
| Module directory and boot | F$VModul validates a module. F$SLink, F$ELink and F$FModul link or locate directory entries. F$GCMDir compacts the directory. F$IODel releases an I/O module. F$Boot and F$BtMem serve bootstrap code. |
| RAM and process images | F$AllRAM, F$DelRAM and F$AlHRAM allocate or return RAM. F$AllImg, F$DelImg, F$SetImg, F$MapBlk and F$ClrBlk maintain process address images. F$FreeLB and F$FreeHB find free blocks. |
| Tasks and DAT translation | F$AllTsk, F$DelTsk, F$SetTsk, F$ResTsk and F$RelTsk maintain task mappings. F$DATLog converts a block and offset into a logical address. F$DATTmp is a historical temporary-image service marked obsolete in the definitions. |
| Access across mappings | F$Move copies a block of bytes. F$LDAXY, F$LDAXYP, F$LDDDXY, F$LDABX and F$STABX load or store across task mappings. Examine the register contract of the particular entry before using it. |
| Edition- or hardware-dependent services | F$Debug and F$RegDmp concern debugging. F$ReBoot, F$CRCMod, F$XTime, F$VBlock and F$NVRAM concern reboot, CRC policy, extended time, validating a block of modules, or nonvolatile hardware storage. Treat these as names in the prepared definitions until the specific kernel and driver support is known. |
Use an error as evidence
| Guest result | What happened here | What you can do |
|---|---|---|
| 211 · End of file | A reader requested more input after the writer finished or the file ended. | A program consuming a stream can treat this as its normal end condition. Distinguish it from an unexpected read failure. |
| 214 · No permission | An open or operation requested access the target did not grant. The file lab removes read permission from a practice copy. | Check the path, owner, requested access and attributes. Restore the copy’s owner-read permission. |
| 216 · Path name not found | A path component failed to resolve. A procedure’s data directory can differ from the directory containing the command program. | Inspect the current directory and try the full known data path. |
| 218 · File already exists | Creation of a new output collided with a name already on disk. | List the existing file. Choose a fresh output name when you want to preserve both results. |
| 228 · Process aborted | The parent reported the termination of the Sleep child deliberately signaled in this lab. | Check the process list again. Absence of that child and a responsive parent shell are the two expected observations. |
Error 043 from RUNB is a language-runtime report. In the Night exercise the successful argument is the packed procedure's internal name, night, with the execution directory set to /H1. An error from a language tool need not be a kernel file error. For historical numbers and additional error families consult the bibliography in the language and edition guide.