I1O User System Calls / 8
Delete A File
OS9 I$DeletX 103E 90
Deletes a file from the
current data or current
execution directory
Entry Conditions:
A = access mode
X = address of the pathlist
Exit Conditions:
X = address
of
the last byte
of
the pathlist + 1;
any trailing
Error Output:
CC = carry set on error
B = error code (if
any)
Additional Information:
· The Delete A File call removes the disk file specified by the
selected pathlist. This function is similar to I$Delete except
that it accepts an access mode byte.
If
the access mode is
execute, the call selects the current execution directory.
Otherwise, it selects the current data directory.
· If
a complete pathlist is provided (the pathlist begins with
a slash (/), the access mode the call ignores the access
mode.
Only use this call to delete a file.
If you
attempt to use
I$DeletX to delete a device, the system returns an error.
8-51
OS-9 Technical Reference
Detach Device
OS9 I$Detach 103E 81
Removes a device
from the system
device table
Entry Conditions:
U = address of the
device table entry
Exit Conditions:
CC = carry set on error
B
= error code
(if any)
Additional Information:
0
The Detach Device call removes a device from both the sys
tem and the system device table, assuming the device is not
being used by another process. You must use this call to
detach devices attached using the Attach system call.
Attach and Detach are both used mainly by the IO man
ager. SCF also uses Attach and Detach to set up its second
device (echo device).
0
This is the sequence of the operation of Detach Device:
1. Detach Device calls the device driver's termination rou
tine. Then, OS-9 deallocates any memory assigned to
OS-9 unlinks the associated device driver and file man
ager modules.
3. OS-9 then removes the driver, as long as no other mod
ule is using that driver.
2.
8-52
IlO User System Calls l 8
Duplicate Path
Returns a synonymous
OS9 I$Dup 103E 82 path number
Entry Conditions:
A = old path number
(number of path to duplicate)
Eat Conditions:
A = new path number (if
no error)
Error Output:
B = error code (if
error encountered)
CC = carry set on error
Additional Information:
- The Duplicate Path returns another, synonymous path
number for the file or device specified by the old path
number.
· The shell uses the Duplicate Path call when it redirects
I/O.
- System calls can use either path number (old or new) to
operate on the same file or device.
· Make sure that no more than one process is performing I/O
on any one path at the same time. Concurrent I/O on the
same path can cause unpredictable results with RBF files.
- The I$Dup call always uses the lowest available path num
ber. This lets you manipulate standard I/O paths to contain
any desired paths.
8-53
OS-9 Technical Reference
Get Status
Returns the status of a
OS9 I$GetStt 103E 8D
ale
or device
Entry Conditions:
A = path number
B = function
code
Error Output:
CC = carry set on error
B
= error code (if any)
Additional Information:
The Status is a waldcard call. Use it to handle device
parameters that:
· Are not the same for all devices
· Are highly hardware-dependent
· Must be user-changeable
The exact operation of the Get Status system call depends
on the device driver and file manager associated with the
path. A typical use is to determine a terminal's parameters
for such functions as backspace character and echo on/off.
The Get Status call is commonly used with the Set Status
call.
The Get Status function codes that are currently defined
are listed in the "Get Status System Calls" section.
8-54
I1O User System Calls / 8
Make Directory
Creates and initializes
OS9 I$MakDir 103E 85 a directory
Entry Conditions:
B
= directory attributes
X = address
of
the pathlist
Exit Conditions:
X = address
of
the last byte of the pathlist + 1
; Make Direc
tory skips trailing blanks.
Error Output:
B
= error code
(if any)
CC = carry set on error
Additional Information:
· The Make Directory call creates and initializes a directory
as specified by the pathlist. The directory contains only two
entries, one for itself (.) and one for its parent directory (..)
· OS-9 makes the calling process the owner of the directory.
Because the Make Directory call does not open the direc
tory, it does not return a path number.
- The new directory automatically has its directory bit set in
the access permission attributes. The remaining attributes
are specified by the byte passed in Register B. The bits are
defined as follows:
Bit Definition
0 Read
1 Write
2 Execute
3 Public read
~-4 Public write
5 Public execute
6 Single-user
7 Don't care
8-55
OS-9 Technical Reference
0
Before the Make Directory call:
/ D 0 / N
E
r
W
I
D ~ I ~ R ~ $OD
X
After the Make Directory call:
I I I
X
8-56
I1O User System Calls / 8
Open Path
OS9 I$Open 103E 84
Entry Conditions:
Opens a path to an
existing file or device
as specified by the
pathlist
A = access mode (D S PE PW
PR E W R)
X = address of the pathlist
(See the following example.)
Exit Conditions:
A = path number
X = address
of
the last byte
of
the pathlist + 1
Error Output:
B = error
code (if any)
CC = carry set on error
Additional Information:
0
OS-9 searches for the file in one of the following:
The directory specified by the pathlist if the pathlist
begins with a slash.
· The working data directory, if the pathlist does not
begin with a slash.
The working execution directory, if the pathlist does not
begin with a slash and if the execution bit is set in the
access mode.
OS-9 returns a path number for later system calls to use to
identify the file.
The access mode parameter lets you specify which read
and/or write operations are to be permitted. When set, each
access mode bit enables one of the following: Write, Read,
Read and Write, Update, Directory 1/O.
· The access mode must conform to the access permission
attributes associated with the file or device. (See the Cre
ate system call.) Only the owner can access a file unless
the appropriate public permission bits are set.
8-57
OS-9 Technical Reference
The update mode might be slightly slower than the others
because it might require pre-reading of sectors for random
access of bytes within sectors.
- Several processes (users) can open files at the same time.
Each device has an attribute that specifies whether or not
it is shareable.
Before the Open Path call:
10
/ A C C T S P A Y $OD
X
After the Open Path call:
C C T S P A Y $OD
X
· If the single-user bit is set, the file is opened for single-user
access regardless of the settings of the file's permission
bits.
· You must open directory files for read or write if the direc
tory bit (Bit 7) is set in the access mode.
Open Path always uses the lowest path number available
for the process.
8-58
I1O User System Calls / 8
Read
OS9 I$Read 103E 89
Entry Conditions:
A
Y
X
= path number
= number
of
bytes to read
= address in which to store the data
Exit Conditions:
Y = number
of
bytes read
Error Output:
B = error code (if
any)
CC = carry set on error
Additional Information:
Reads n bytes from a
specified path
The Read call reads the specified number of bytes from the
specified path. It returns the data exactly as read from the
file/device, without additional processing or editing. The
path must be opened in the read or update mode.
If there is not enough data in the specified file to satisfy
the read request, the call reads fewer bytes than requested
but an end-of-file error is not returned. After all data in a
file is read, the next I$Read call returns an end-of-file
error.
If the specified file is open for update, the record read is
locked out on RBF-type devices.
The keyboard terminate, keyboard interrupt, and end-of-file
characters are filtered out of the Entry Conditions data on
SCF-type devices unless the corresponding entries in the
path descriptor have been set to zero. You might want to
modify the device descriptor so that these values are ini
tialized to zero when the path is opened.
8-59
OS-9 Technical Reference
0
The call reads the number of bytes requested unless Read
encounters any of the following:
· An end-of-file character
· An end-of-record character (SCF only)
· An error
8-GO
IlO User System Calls l 8
Read Line With
Reads a text line with
Editing
editing
OS9 I$ReadLn 103E 8B
Entry Conditions:
A = path number
X = address at
which to
store data
Y = maximum number of bytes to
read
Exit Conditions:
Y = number of bytes
read
Error Output:
B = error
code (if any)
CC = carry set on error
Additional Information:
· Read Line is similar to Read. The difference is that Read
Line reads the input file or device until it encounters a car
riage return character or until it reaches the maximum
byte count specified, whichever comes first. The Read Line
also automatically activates line editing on character ori
ented devices, such as terminals and printers. The line
editing refers to auto line feed, null padding at the end of
the line, backspacing, line deleting, and so on.
· SCF requires that the last byte entered be an end-of-record
character (usually a carriage return). If more data is
entered than the maximum specified, Read Line does not
accept it and a PD.OVF character (usually a bell) is
· After one Read Line call reads all data in a file, the next
Read Line call generates an end-of-file error.
· (For more information about line editing, see "SCF Line
Editing Functions" in Chapter 6.)
8-61
OS-9 Technical Reference
Seek
OS9 I$Seek 103E 88
Entry Conditions:
Repositions a file
pointer
A = path number
X = MS 16 bats of the desired file position
U = LS 16 bits of the desired file position
Error Output:
CC = carry set on error
B = error
code
(if any)
Additional Information:
The Seek Call repositions the path's logical file pointer, the
32-bit address of the next byte in the file to be read from or
written to.
You can perform a seek to any value, regardless of the file's
size. Later writes automatically expand the file to the
required size (if possible). Later reads,, however, return an
end-of-file condition. Note that a seek to Address 0 is the
same as a rewind operation.
OS-9 usually ignores seeks to non-random access devices,
and returns without error.
On RBF devices, seeking to a new disk sector causes the
internal disk buffer to be rewritten to disk if it has been
modified. Seek does not change the state of record locking.
8-62
I1O User System Calls / 8
Set Status
Sets the status of a file
OS9 I SetStt 103E 8E or device
Entry Conditions:
A = path number
B
= function code
Other registers depend on the function code.
Error Output:
B = error
code (if
any)
CC = carry set on error
Other registers depend on the function code.
Additional Information:
0
Set Status is a wildcard call. Use it to handle device
parameters that:
· Are not the same for all devices
· Are highly hardware-dependent
· Must be user-changeable
_ The exact operation
of
the Set Status system call depends
on the device driver and file manager associated with the
path. A typical use is to set a terminal's parameters for
such functions as backspace character and echo on/off. The
Set Status call is commonly used with the Get Status call.
The Set Status function codes that are currently defined
are listed in the "Set Status System Calls" section.
8-63
OS-9 Technical Reference
Write
Writes to a file or
OS9 I$Write 103E 8A device
Entry Conditions:
A = path number
X = starting address of data to write
Y = number of bytes to write
Exit
Conditions:
Y = number of bytes written
Error Output:
B = error code (if
any)
CC = carry set on error
Additional Inforriiation:
· The Write system call writes to the file or device associated
with the path number specified.
· Before using Write, be sure the path is opened or created
in the Write or Update access mode. OS-9 writes data to
the file or device without processing or editing the data.
OS-9 automatically
expands
the file if you write data past
8-64
I1O User System Calls / 8
Write Line
OS9 I$WritLn 103E 8C
Writes to a file or
device until it
encounters a carriage
return
Entry Conditions:
A
X
Y
= path number
= address of the data to write
= maximum number of bytes to write
Exit Conditions:
Y = number of bytes written
Error Output:
B = error
code
(if any)
CC = carry set on error
Additional Information:
· Writes to the file or device that is associated with the path
number specified.
· Write Line is similar to Write. The difference is that Write
Line writes data until it encounters a carriage return char
acter. It also activates line editing for character-oriented
devices, such as terminals and printers. The line editing
refers to auto line feed, null padding at the end of the line,
backspacing, line deleting, and so on.
· Before using Write Line, be sure the path is opened or cre
ated in the write or update access mode.
· (For more information about line editing, see "SCF Line
Editing Functions" in Chapter 6.)
8-65
OS-9 Technical Reference
Privileged System Mode Calls
Set an alarm
OS9 F$Alarm 103E 1E
Entry Conditions:
X = relative address of time packet
Error Output:
CC = carry set on error
B = appropriate error code
Additional Information:
Sets an alarm to ring
the bell at a specified
time
When the system reaches the specified alarm time, it rings
the bell for 15 seconds.
The time packet is identical to the packet used in the
F$STime call. See F$STime for additional information on
the format of the packet.
All alarms begin at the start of a minute and any seconds
in the packet are ignored.
0
The system is limited to one alarm at a time.
8-F6
Privileged System Mode Calls / 8
Allocate 64
OS9 F$A1164 103E 30
Dynamically allocates
64-byte blocks of
memory
Entry Conditions:
X = base address of the page table;
0 = the page table has
Exit Conditions:
= block number
= base address of the page table
= address of the block
Error Output:
CC = carry set on error
B = error code (if
any)
Additional Information:
· The Allocate 64 system call allocates the 64-byte blocks of
memory by splitting pages (256-byte sections) into four
· OS-9 uses the first 64 bytes
of
the base page as a page
table. This table contains the page number (most signifi
cant byte of the address) of all pages in the memory struc
ture. If Register X passes a value of zero, the call allocates
a new base page and the first 64-byte memory block.
· Whenever a new page is needed, a Request System Memory
system call (F$SRqMem) executes automatically.
· The first byte of each block contains the block number.
Routines that use the Allocate 64 call should not alter this
8-67
OS-9 Technical Reference
0
The following diagram shows how seven blocks might be
allocated:
Base Paga -.. Any Memory Page Any Memory Page
X
Page Table Block 4
(64 bytes)
(64 bytes)
X X
Block 1 Block 5
(64 bytes) (64 bytes)
X
Block 2 Block 6
(64 bytes) (64 bytes)
X X
Block 3 Block 7
(64 bytes) (64 bytes)
8-68
Privileged System Mode Calls / 8
Allocate High
RAM
OS9 F$Al1HRam
Entry Conditions:
B = number of blocks
Error Output:
CC = carry set on error
B = appropriate error code
Additional Information:
Allocate system
memory from high
physical memory
0
This call searches for the desired number of contiguous free
RAM blocks, starting its search at the top of memory.
F$Al1HRam is similar to F$Al1RAM except F$Al1RAM
begins its search at the bottom of memory.
0
Screen allocation routines use this call to provide a better
chance of finding the necessary memory for a screen.
8-69
OS-9 Technical Reference
Allocate Image
OS9 F$Al1Img 103E 3A
Allocates RAM
blocks for process
DAT image
Entry Conditions:
A = starting
block number
B = number of blocks
X = process descriptor pointer
Exit Conditions:
CC
B
carry set on error
error code (if
any)
Additional Information:
· Use the Allocate Image system call to allocate a data area
for a process. The blocks that Allocate Image defines might
not be contiguous.
· The support module for this system call is OS9p 1.
8-70
Privileged System Mode Calls l 8
Allocate Process
Allocates and
,.--
Descriptor
initializes a 512-byte
process descriptor
OS9 F$Al1Prc 103E 4B
Entry Conditions:
None
Exit Conditions:
U = process descriptor pointer
Error Output:
CC = C bit set on error
B = appropriate error code
Additional Information:
· The process descriptor table houses the address of the
descriptor. Initialization of the process descriptor consists
of clearing the first 256 bytes of the descriptor, setting up
the state as a system state, and marking as unallocated as
much of the DAT image as the system allows typically,
· The support module for this system call is OS9p2. The call
also branches to the F$SRqMem call.
8-71
OS-9 Technical Reference
Allocate RAM
OS9 F$A11RAM 103E 39
Searches the
memory block map
for the desired
number of
contiguous free
RAM blocks
Entry Conditions:
B
= number of blocks
Exit Conditions:
CC = C bit set on error
B
= appropriate error code
Additional Information:
e The support module for this system call is OS9p 1.
8-72
Privileged System Mode Calls / 8
Allocate Process
Task Number
OS9 F$Al1Tsk 103E 3F
Determines whether
OS-9 has assigned a
task number to the
specified process
Entry Conditions:
X = process descriptor pointer
Error Output:
CC = C bit set
B = appropriate error code
Additional Information:
· If the process does not have a task number, OS-9 allocates
a task number and copies the DAT image into the DAT
hardware.
· The support module for this call is OS9p1. Allocate Process
Task number also branches to F$R,esTsk and F$SetTsk.
8-73
OS-9 Technical Reference
Insert Process
Inserts a process into
OS9 F$AProc 103E 2C the queue for execution
Entry Conditions:
X = address of the process descriptor
Error Output:
CC = carry set on error
B = error code (if any)
Additional Information:
· The Insert Process system call inserts a process into the
active process queue so that OS-9 can schedule the process
· OS-9 sorts all processes in the queue by process age (the
count of how many process switches have occurred since the
process's last time slice). When a process is moved to the
active process queue, OS-9 sets its age according to its
priority-the higher the priority, the higher the age.
An exception is a newly active process that was deactivated
while in the system state. OS-9 gives such a process higher
priority because the process usually is executing critical
routines that affect shared system resources.
8-74
Privileged System Mode Calls / 8
Bootstrap System
OS9 F$Boot 103E 35
Links either the
module named Boot
or the module
specified in the INIT
module
Entry- Conditions:
None
Error Output:
CC = C bit set on error
B = appropriate error code
Additional Information:
0
When it calls the linked module, Boot expects to receive a
pointer giving it the location and size of an area in which
to search for the new module.
The support module for this call is OS9p1. Bootstrap Sys
tem also branches to the F$Link and F$VModul system
calls.
8-75
OS-9 Technical Reference
Bootstrap
Memory Request
OS9 F$BtMem 103E 36
Allocates the
requested memory
(rounded to the
nearest block) as
contiguous memory
in the system's
address space
Entry Conditions:
D = byte count requested
Exit Conditions:
D = byte count granted
U = pointer to memory allocated
Error Output:
CC = C bit set on error
B = appropriate error code
Additional Information:
0
This call is identical to F$SRqMem.
0
The Bootstrap Memory Request support module is OS9p1.
8-76
