← Manual LibraryVCC Plus 3.7.1 · Reading on the web

Try the exercises in VCC Plus. Example links download files here; open them in the app to work beside the emulator.

The complete book · PDF editionBook 11: Working with OS-9 — A Comprehensive Manual

51 pages · VCC Plus 3.7.1 · Keep a copy to read or print.

Download PDF
Contents

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.

Original VCC Plus manuals © 2026 Brian K. Holman. Third-party references retain their authors’ copyrights and licenses. Artwork notices. Edition 3.7.1; source and export identity. Printable edition: PDF source and export identity.

A closer look

Open original