PDP-10.its/doc/sits/docum.66

.xgp
.font 0 25fdel
.ce
SITS system calls.
.sp 2
.adjust
This file describes the SITS system calls. When a system call is executed, the 
arguments are pushed onto the stack (last argument first, next to last next . . . ).
Then the system call is executed. The system call is an emulator trap.
.sp
If a call is successful, all the arguments are popped off the stack
and the condition codes are
cleared. If it fails, the Z condition code is set, and the arguments are not popped
off.
There are two versions of every system call: the .FOO version will just return with Z set if it fails. The $FOO version will cause a .EMTTF type of fault if it fails. This is handy for system calls that shouldn't ever fail:
rather than inserting a test for failure or hoping it never fails and letting
all hell break lose if it does, use the $FOO version.
A failing system call should also set the process's error word,
which can be read with .GERRW.
.page
.spread
/.NOOP/Assembles as: EMT 0/Inputs: 0 Outputs: 0
.br
No-op system call, does nothing.

.br
.spread
/.FORK/Assembles as: EMT 1/Inputs: 1 Outputs: 0
.br
Creates a new process in the current sphere, and starts it. The
argument is the starting address.

.br
.spread
/.POOFF/Assembles as: EMT 2/Inputs: 0 Outputs: 0
.br
Makes the process executing it disappear. (unless there still is
a capability to it, in which case it is just stopped)

.br
.spread
/.SLEEP/Assembles as: EMT 3/Inputs: 2 Outputs: 0
.br
Doesn't return from the system call until the time specified has
elapsed. The two arguments form a double precision integer.
the first is the low order 16 bits, the second the high order.
if the argument is positive, it returns that many 60ths of a
second later. If the argument is negative, it is negated
(making it positive), and the system call returns when the
system time is equal to that number. This call modifies its
arguments.

.br
.spread
/.SINK/Assembles as: EMT 4/Inputs: 0 Outputs: 0
.br
Disables the use of the floating point processor for this
process. (this is the default state)

.br
.spread
/.FLOAT/Assembles as: EMT 5/Inputs: 0 Outputs: 0
.br
Enables the use of the floating point processor for this process.

.br
.spread
/.INVOK/Assembles as: EMT 6/Inputs: 3 Outputs: Var
.br
This is a series of calls that are further decoded by their
arguments. The bottom byte of the first argument is the
capability number that this .INVOK refers to. The top byte of
it specifies the function. This is further desrcibed elsewhere.

.br
.spread
/.QULK/Assembles as: EMT 7/Inputs: 1 Outputs: 0
.br
The argument specifies a queue capability to lock. The system
call returns when it succeeds in locking the queue.

.br
.spread
/.QUNLK/Assembles as: EMT 10/Inputs: 1 Outputs: 0
.br
The argument specifies a queue capability to unlock. The call
unlocks it. These two calls implement the normal P and V operations.

.br
.spread
/.TTGIV/Assembles as: EMT 11/Inputs: 2 Outputs: 0
.br
The first argument specifies a master sphere capability, which
specifies to what sphere the capability is given. The second
argument specifies a tty capability that describes the tty that
is going to be given away. If the tty belongs to the giver,
control then is passed to the inferior, otherwise, it waits
until the tty is given to it, and then gives it to the inferior.

.br
.spread
/.TTGET/Assembles as: EMT 12/Inputs: 1 Outputs: 0
.br
The argument specifies a tty capability that the system will
regain control for the sphere executing it. It will succeed if
the tty is owned by an inferior to the executing sphere.
otherwise it will hang until the tty is given to it.

.br
.spread
/.WRDI/Assembles as: EMT 13/Inputs: 1 Outputs: 1
.br
he bottom byte of the argument specifies the c-list number
of an i-o device capability. The top byte is used for device
dependent flags. The system call then returns a word input from
that device.

.br
.spread
/.WRDO/Assembles as: EMT 14/Inputs: 2 Outputs: 0
.br
The bottom byte of the first argument specifies the c-list 
number of an i-o capability. The second argument is then output
to the device specified by the i-o capability.

.br
.spread
/.BYTI/Assembles as: EMT 15/Inputs: 1 Outputs: 1
.br
The bottom byte of the argument specifies the c-list number of
an i-o capability. The top byte contains device dependent flags.
the system call then returns a byte input from that device.

.br
.spread
/.BTYO/Assembles as: EMT 16/Inputs: 2 Outputs: 0
.br
The bottom byte of the first argument specifies the c-list
number of an i-o capability. The bottom byte of the second
argument is then output to that device.

.br
.spread
/.BLKI/Assembles as: EMT 17/Inputs: 3 Outputs: 0
.br
The bottom byte of the first argument specifies the c-list
number of an i-o capability. The top byte contains device
dependent flags. The second argument is the negative number
of bytes to transfer. The system call then transfers that
number of bytes from the input device to the destination
specified by the third argument the system call may be updated,
and the arguments changed.

.br
.spread
/.BLKO/Assembles as: EMT 20/Inputs: 3 Outputs: 0
.br
The three arguments are the same as .BLKO, except the bytes are
transferred from the users core to the device.

.br
.BYTI, .WRDI, and .BLKI all return with Z and V set if an attempt is
made to read past the end of file. In the case of .BLKI, the pointers
left on the stack reflect how far you got.
.sp
.br
.spread
/.MAP/Assembles as: EMT 21/Inputs: 4 Outputs: 0
.br
Creates or deletes a page for a specified sphere. If a page
already exists in the specified place, it is deleted. The bottom
byte of the first argument is a sphere capability to the sphere
that the page is to be inserted to. The sphere capability must
have core write access. The top byte is the access to give the
sphere to that page (read only, read-write, etc.) the bits are .CRRD
for read only, .CRWRT for read-write access, .CREX for
execute only access, and .CRPRI for private page. The bottom
byte of the second argument is the source of the page. (-1 for
fresh page, -2 for absolute page, -3 for don't create a new page
(just delete the current page), -4 for expand the current page
(this works by offseting the user page in a virtual 4k page, as
specified by the start and length fields) or the c-list no. Of
the capability to a sphere, file, or display). The top byte is
number of the page to create, (0-7 i space page, 10-17 d space
page, 20-27 i=d pages). The third argument is the page no in
the source to get the page from. The third argument is also used
for the start of an absolute page. The bottom byte of the fourth
argument is the offset to the start of the page, in 512. Word
blocks. The top byte is the length minus one of the page in
512. Word blocks. (the sum of the start and length cannot be
greater than 7). If the capability is to a TK display, the MAP will result in
a page the size of the associated display buffer being mapped
in to the appropriate sphere page. If it is to a TV display
the page number in source argument may be 0, 1, 2, 3 or 4.
If it is 0, 1, 2, or 3 the page mapped in is a 4K page
of the display memory. If it is 4 the page mapped in is a 32
word page that points to the TV control registers.

.br
.spread
/.ALLOC/Assembles as: EMT 22/Inputs: 2 Outputs: 0
.br
This system call can only be executed once per reloading of the
system. It can only be executed by the system job. It then
allocates swapping space on the disks specified. The first
argument is the number of swap areas on the disks. The second
is a pointer to the data about the swap areas, which is in the
following format. The first word is the logical disk number
that this swap area resides on. The second word is the starting
block number of the swap area. The third word is the length of
the swap area.

.br
.spread
/.CRUSR/Assembles as: EMT 23/Inputs: 2 Outputs: 0
.br
This system call creates new users and sets and reads their user
names. Any process can read the name of the user it belongs to;
only the system sphere can create new users or set the name of a user.
The first argument is a flag; if the flag is positive the name of the
user the executing process belongs to is set from the ASCIZ string
pointed to by the second argument; if it is zero a new user is created
and the name is set from the second argument. If the flag is negative
the name of the user the executing process belongs to is copied as
an ASCIZ string to the place pointed to by the second argument.
.br
.spread
/.RDMAP/Assembles as: EMT 24/Inputs: 2 Outputs: 0
.br
This system call reads map info out of a given sphere. The
first argument is the capability number of a sphere or master
sphere capability to the sphere who's map is being read. The
second argument is a pointer into the users core, where the data
will be put. The data consists of 16. words, one per page, with
bits as follows:
.nofill
.indent 5
.PLENM	mask for the length field
.PACCM	mask for the access field
.PFIL	part of file bit
.PABS	absolute page
.PDEI	data = instruction page
.CRRD	can be read
.CRWRT	can be writen
.CREX	execute only
.PLENM	is the mask for the length of the page
       (in low bits of word)
.indent 0

.br
.spread
/.FONT/Assembles as: EMT 25/Inputs: 2 Outputs: 0
.fill
.br
Read or write fonts. The first arg low byte is the
number of the font, the high byte is function:
.PRWRT for write into a font item, and zero for
read into user's core. The second is a pointer into
user's core which is where to read or write the font.
When creating a new font the data should be in the following
format:
.nofill
.indent 5
byte offset	function
4 width of a char frame (char plus separator) in bits.
6 maximum height of char in tv lines.
10 length of the font data from pointer in bytes.
12 height of a char line in tv lines.
14 right adjusted mask (1's) the actual width of char
40 start of a table of 128 pointers, where each pointer
is the byte offset from the start of the font to
the data of the char corresponding to that pointer.
240 actual font data in bytes for chars <= 8 bits wide
and words for chars > than 8 bits.
.fill
.indent 0

.spread
/.SSTAT/Assembles as: EMT 26/Inputs: 1 Outputs: 0
.br
This call reads various random info into the users core
about the system. The argument is a pointer into user core;
this block of info is written into the user starting at
that point and continuing as long as there is info.
the current info returned is:
.nofill
.indent 5
the version number of the running system
the time since the system came up, in 60ths of a second
the high order part of the time
the current contents of the console switches
.fill
if non-zero, this word indicates the system is
currently paying attention to the console switches
.in 0

.br
.spread
/.VIDSW/Assembles as: EMT 27/Inputs: 2 Outputs: 0
.br
This call allows switching of tv monitors and buffers via
the video switch. The first argument specifies the the source
or buffer, the second argument specifies the destination or
montior channel. Both source and destination arguments should
be in the format of a mode number in the high byte and an
argument number in the low byte. There are four modes which
can be used with both the source and destination arguments.
.indent 5

.VIABS Just map the number directly into the appropriate
byte of the video buffer.

.VILOT The number is a logical tty number. this number is
the same number as is used in the create of the tty,
and the tty must be one of the tv tty's. For source,
this specifies the buffer associated with this tv.
for destination the appropriate channel is selected
using the logical tty number to index a table.

.VILOD Similar to vilot except that the number is a display
number and must be a tv display.

.VICAM In this case, for both source and destination, the
number specifies a capability in the caller's sphere.
the capablity may be either a tty or display which
is used to get either the logical tty number or display
number and procede as in .VILOT and .VILOD.
.indent 0

.spread
/.RUG/Assembles as: EMT 30/Inputs: 0 Outputs: 0
.br
Works only for SYSSPR. Causes the system to breakpoint to RUG.
If, upon returning from RUG, it is found that the .RUG has been
changed to something else, the PC is not incremented before
return to user mode, causing the new instruction to be executed.
This allows one to place breakpoints in the SYSSPR moderately
conviently.

.spread
/.GERRW/Assembles as: EMT 31/Inputs: 0 Ouptuts: Var
.br
This call is used to get the error code after a failing system call.
It returns the addess in the system where the error happened, and the
error code. If there has been no error in the executing process
since the last .GERRW was done, the call fails (!!), setting Z
and putting nothing on the stack. The error codes that are returned are as follows:
.indent 5
.nofill
.ENUL	=> NO ERROR AT ALL
.EAPEF	=> ACCESS PAST END OF FILE
.EBAC	=> BAD ACCESS
.EBAD	=> BAD ARGUMENTS TO CALL
.EBCN	=> BAD CAPABILITY NUMBER
.EBCT	=> BAD CAPABILITY TYPE
.EBFN	=> BAD FILE NAME
.EBFUN	=> BAD FUNCTION
.EBPN	=> BAD PAGE NUMBER
.ECDD	=> CAN'T DELETE NON-EMPTY DIRECTORY
.EDEVE	=> DEVICE ERROR
.EDFL	=> DISK FULL
.EDRF	=> DIRECTORY FULL
.EEAE	=> ENTRY ALREADY EXISTS
.EFLOK	=> FILE LOCKED
.EFNF	=> FILE NOT FOUND
.EFNTL	=> FILE NAME TOO LONG
.EFTL	=> FILE ENTRY TOO LONG
.ENIS	=> NO ITEM SPACE AVAILABLE
.ENIT	=> NO ITEM AVAILABLE
.ENSS	=> NO SWAP SPACE LEFT
.ERNA	=> RESOURCE NOT AVAILABLE
.ERPEF	=> ATTEMPT TO READ PAST END OF FILE
.ESYS	=> CALL MAY ONLY BE EXECUTED BY SYSSPR
.ECLF	=> C LIST IS FULL
.indent 0
.fill

.spread
/.SYSJB/Assembles as: EMT 32/Inputs: 0 Ouptuts: 0
.br
This magical call is executed by one and only one process in the SYSSPR.
It provides the system with a process to perform certain operations
that would be difficult to perform otherwise.

.INVOK Calls:

If the top bit is set in the
function, it is declared a system function. If it is a system
function, it is decoded as below (the symbol is byte*400)
.indent 5

.br
Byte symbol description

200 .DELCP Deletes the capability invoked.

201 .CPYCP Copies the capability invoked. The second
argument specifies the control bits to clear.
(bits that are set in the argument are cleared
in the capability). The destination of the copy
is the current sphere, and the c-list entry
specified by the third argument. (a c-list
entry number between 0 and 200, or -1, which
specifies the first free c-list entry)

.br
202 .GIVCP The capability invoked must be a sphere capability with 
c-list append access. The second argument
is the c-list number of the source entry in the
current sphere. The capability is copied
according to the destination in .CPYCP, but the
destination sphere is the one referred to by the
sphere capability. The c-list entry is then
deleted from the sphere of the giver.

.br
203 .TAKCP The capability invoked must be a sphere capability with 
c-list delete access. The capability is
taken from the sphere specified by the sphere
capability, and the c-list number of the second
argument. The destination is the same as .CPYCP.
the capability is then deleted from the source
location.
.indent 0

The left column is the capability invoked.

.CRCAP Create the capability type in the top byte of the first argument.
the second arguments usage is described below. The third argument
is where to put the created capability. (capability number or -1)
This call returns the location where the capability was created.
The following is an exact description of what happens when a given type
of capability is created.
.indent 5

.CRCAP The second argument is discarded, and a new create capability
is created.

.MSCAP A sphere is created, and made inferior to the creating sphere,
the second argument is the enter address for the inferior sphere
into the creating sphere.

.SPCAP Illegal to create, can only appear as a consequence of copying
a .MSCAP or .SPCAP.

.PRCAP A process is created, and its starting address is loaded from
the second argument. The process is not placed in any sphere,
and is initialized in a stopped state.

.TTCAP The second argument is the teletype number to create a teletype
capability for. If no capability to that teletype exists
already, one is created, otherwise an error is returned

.FACAP The second argument is a pointer to a block of data. the first
word is flags for the file or directory, which is then followed
by the name of the file ending with a zero byte. If a root
directory capability is being created then three bytes after the
zero indicate the logical disk number and the block number where
the root directory can be found. Only the system sphere can
create a root directory capability and only one per logical disk
is allowed.
if a temporary file capability is being created the user
gets total access to a file of zero length with the name he
specified. The default version number is no version number.
other capabilities to the file can be created only by copying
and the file is deleted when all capabilities to it are deleted.
If the .FARUT bit is set in the flag word, a root directory
is created for the disk specified in the low byte of the flag
word. (This is normally done only by the SYSSPR).

.QUCAP Create a queue capability. the second argument is the number of
people who can lock the queue, without hanging for someone to
unlock it.

.CLCAP Create a core link. the second argument specifies the buffer
capability of the core link. If the length of the core link
is longer than 64. Words (with system overhead, that allows
a buffer length of 60. Words), the system will allocate a page
that will be swapped for the buffer, otherwise, it will allocate
an item, which will never be swapped. Thus short core links are
faster, but the chance of it filling up is greater.

.DSCAP Create a display capability. the high byte of the second arg
is flags. The 100000 bit means that the low byte is a capability
if it is off the low byte is a display number. The 40000
bit if 0 means we are looking for a tk display capability;
if 1 we wnat a tv display. For tk displays, the 400
bit being 1 means we want a large buffer; 0 means
we don't care. Returned values are
the word offset of the buffer, its length in words,
and the capability number. (capablity number is on top
of stack, length is second)
for tv displays, if the low byte is 377 the first free
display buffer is grabbed.

.TPCAP Create a paper tape punch capability. The second argument
is not used. The call fails if the paper tape punch is already open.

.TRCAP Create a paper tape reader capability.  Same as .TPCAP

.LPCAP Create a lineprinter/plotter capability. The second argument is not used. The printer/plotter starts in print mode. Thc
call will fail if the lineprinter/plotter is already open.

.CMCAP Create a color map capability. Call will fail if a color map capability
already exists.
.indent 0

.MSCAP The top byte of the first argument is used to specify a function to be 
performed. The functions are:
.indent 5

.SPPTP put process into sphere. The second argument is the capability
number of the process to put into the invoked sphere. The
process capability must have write access to the process, and
the sphere capability must have c-list add access to the sphere.

.SPRCP return the type of capability at the c-list entry specified by
the second argument. If there is no capability there, a zero
is returned, otherwise the number of the capability type. (e.g.
.SPCAP,.MSCAP ...)

.SPSTP stop all processes in the sphere, except that if the executing process
is in the sphere don't stop it.

.SPSTR start all the processes in the sphere.

.SPKIL kill all processes in the sphere, except that if the executing process
is in the sphere don't kill it.

.SPPGT get info about the nth process in the sphere, where n is the second
arg. Note that the numbering of the processes in a sphere can change when
there is one or more processes running in the sphere. The info returned
is the PC of the process and it ID number.

.SPGPC get a capability to a process in the sphere. Returns a capability
to the process whose ID words are supplied as arguments 1 and 2. The
capability always goes to the first free capability index.

.SPGNP get the number of processes in the sphere.
.indent 0

.SPCAP Same as .MSCAP

.PRCAP The top byte of the first argument is used to specify a function to be
performed. If the .PRWRT bit is set in the function, set the processes data
from users core, else return the processes data to user. The third argument is
never used. The functions low bits are decoded as follows:
.indent 5

.PRREG Read or write the processes user mode general register specified
by the number added to this symbol. I.E. .PRREG+3 specifies
R3. If write, the second argument is what to deposite there. If read, returns
value read.

.PRPSW Read or write the processor status word for the process. all
bits are read, only the condition codes and t-bit are permitted
to be written. If read, returns the value read.

.PRFREG Read or write the processes floating point registers. the
second argument is a pointer to a four word block of data that
is either read from, or written to. Never returns a value.

.PRFPST Read or write the floating point status. The arguments are
handled the same as the user mode general registers.

.PRFPEN Read or write the floating point availability bit. A one means
floating point is enabled, a zero means it is not. If written,
the process either loses or gains availability of floating point
processor. If read, returns the value read.

.PRSTOP Read or write the stop state of the process. If read returns
stop word, if write, and the second argument is non zero, it
stops the process, if zero, starts it if stopped. If read, returns the
value read.

.PRERR Read or write the error word of the process. If read, returns the
value read.

.PRERA Read or write the address the error happened at (in th system).

.PRFAUL Read or write the fault word of the process. If write, and
the old fault word was clear, it causes the process to fault. If read,
returns the value read.
.indent 0

.TTCAP The top byte of the first argument is a function. If the .TTWRT bit is set,
the data is written into the tty item, otherwise the data is returned to the
user. The fuctions for writing are:
.indent 5

.TTMOV Move the second argument into the tty status word

.TTBIS Set the bits specified in the second argument into the
tty status word

.TTBIC Clear the bits specified in the second argument into the
tty status word

.TTRD Read the tty status word. 

.TTCNO Read or set the charno variable of the tty

.TTBRKA Process executing this invok will hang until certain
conditions are satisfied. If any condition is satisfied
the call completes. The second argument specifies two
bytes such that is either of these bytes comes in the
the input, then the call completes. The third argument
specifies a number in the low such that if any byte less
than that number is typed, then the call completes. In the
high byte are flags for other break functions, such as if
.TTMBK Is set, the process will break when more is triggered.
the invok returns one value on stack which has the byte
causing the break in low and a flag for the type of break high.
flags for call function and return value:
.indent 10

.TTIBK I/O Break caused by one of the chars described in
args being typed.

.TTMBK MORE Break.
.indent 5

.TTSPD Set the tty speed. applies only to the DH11 ttys currently.
the second argument is moved into the line parameter register
to set the speed.

.TTTYP Returns the tty type. the flags for this are the flags in
the TTYTBL entry for the tty

.TTMV2 Read or write tty status 2, similar to .TTMOV

.TTBS2 Bit set into tty status 2, similar to .TTBIS

.TTBC2 Bit clear in tty status 2, similar to .TTBIC

The following invokes only apply to tv ttys:

.TVATC Attach a display to a tv. the second argument should
be a display capability.

.TVCL Clear the screen, set cursor to home up.

.TVREV Reverse black and white on screen.

.TVFNT Set the font for this tv. second arg is the number of the
font desired.

.TVRFN Returns information about the current font. when it returns
the first word on stack contains the number of tvlines in
a char line (fntlcl in font), and second word is the width
of a char in bits (fnwide). Arguments are ignored

.TVSET Read or write tvline and tvcur. use .prwrt with function
to specify write. Tvline will be second arg, and first
value returned, tvcur next.

.TVOFF Read or write the tvoffl variable, use .prwrt for write.
this variable only has effect in wrap mode and says what
char line is the top of the screen. Writing into this
variable will clear the entire screen and then set the
cursor to the new value of tvoffl, at char position 0.

.TTPEK Returns the first character to be input from the tty, without flushing it
permanently, that is the character that is read by .TTPEK, will be the same
as the first character of the next input call on that tty. If there are no
characters to be ready at that time, a -1 is returned.

.TTBAK Causes a break condition on a tty line. .TTBAK waits until all the characters
currently in the output buffer are transmitted, and then causes a break condition
for a certain duration. The duration is given by the first argument, in the form of
number of character transmit times. That is if the first argument is 45, the break condition
persists for the amount of time it would have taken to send 45 characters at the current
speed.

.nofill
The status bits in tty status word 1:
.indent 10

.TIRST=> Reset the tty on next input break
.TIQF=> Super quote the next character
.TOTRN=> Currently transmitting
.TIMGI=> Input image mode
.TIMGO=> Output image mode
.TIRBM=> In rubout mode
.TIEDM=> In edit mode
.TIECM=> In echo mode
.TICTM=> controlify mode, control underscore
	 controlify's next char
.TICTF=> controlify next char (clear 100 bit)
.TICVM=> Convert from lower to upper case mode
.TLIPM=> Line input mode
.TORST=> Reset the tty on next output break
.TERST=> Reset the tty edit buffer
	  on the next output commmand
.indent 5

The status bits in tty status word 2:
.indent 10

.TSCRL=> 1 means scroll mode, 0 means wrap mode for tv's
.fill
.indent 0

.FACAP The top byte of the first argument is a function decoded as follows:

.indent 5
.FACF Clears the flags specified by the second argument, and ignores
the third argument. Flags are:
.nofill
.indent 10

.FAAC -> allow user to change access codes (not implemented)
.FARD -> allow read access to file/directory
.FAWT -> allow write and expand access to files or
 allow delete access to a directory
.FAAP -> allow append access to a file or
 add access to a directory
.fill
.indent 5

.FASP Sets the file page number and the byte pointer from the 
arguments. In all these calls (unless explicitly stated)
the user gives or recieves a 32 bit byte count which is
converted into or from a page number and byte offset.

.FARP Ignores the second and third arguments, returns the 32 bit
byte pointer into the users file.
 
.FARE Returns the 32 bit byte count of the file's length.

.FADL The entry represented by the capability is deleted from
it's directory. If the entry is a
directory it will be deleted only if there are no files in that
directory. If it is a file, it will be deleted always. The
second and third argument are ignored.

.FASDL Like .FADL, but the directory is deleted even if it is
non-empty. The use of this call should be avoided: note that
the blocks represented by the files and directories contained
in a non-empty directory deleted in this way will not be freed.

.FAAD Adds a file with name pointed to by the second argument to
a directory. Adding a file with version number < is
illegal. If a file that matches the supplied name already exists,
an error occurs, unless the file is FOO>, in which case the next
largest version of the file is created. If the name is FOO> and no match
occurs, FOO#1 is created. The supplied directory capability is mutated to the new
file.
 
.FAMD Makes a directory. Call with a capability to a file which is one
block long. The file is changed into a directory, the previous contents
of the file are lost.

.FAMU Mutate the capability invoked. the second argument points to
the name of a path to take. The capability is then mutated
down that path. If any of the path names is the name of a file
it will give an error if there is any more path specfied. (only
directories can be mutated). The third argument is the flags
to specify on the open of each step along the path.
If the .FALOK bit is set the file or dir is locked so no other
capability to it can be created. If there already is another capability
or a page of the file mapped in to some sphere the call will fail if this
bit is set. The user's pointer is updated after each sucessful step along
the path and the capability remains whatever it was after the
last sucessful step.

.FAMB Can only be executed by the system sphere. it makes the invoked
capability the "bits" file for the root directory it is inferior
to. The second argument is used as the base year for the disk.
The third argument is ignored.

.FARI Returns information about the file whose capability is invoked.
the third argument is a pointer to where to place the informa-
tion in the user's core. Data returned is as follows:
word of the capabilities flags
word of the mfi's flags; bits are:
.nofill
.indent 10

.FADIR -> set if it's a directory cap.
.FALOK -> set if mfi is locked by some sphere
.FARUT -> set if it's a root directory cap.
length of file in blocks (rounded up)
date of creation
time of creation
name (in bytes of ascii)
(optional version number preceded by "#")
ends with a zero byte
.fill
the second argument is the maximum number of bytes to return
to the user (rounded to even count). If it is exceeded v is
set. Greatest number of bytes returned = 410 (octal). If the
count is 0 or 1 then as many words as necessary are returned.
.indent 5

.FADI Returns information about the disk the file whose capability
was invoked is on. After returning the number of free blocks
is on top of the user's stack with the logical disk number under
it.
.indent 0

.QUCAP No invokes allowed

.CLCAP The second argument is negative, it tries to become the consumer for this core
link. (there can be many capabilities to write data into a core link, but only
one to remove it.) if no one else is a consumer on this core link, it makes
the invoked capability the consumer. If the first argument is positive, it
releases the consumer enable for this capability, if it was the consumer,
otherwise there is no action. Second and third arguments are ignored.

.DSCAP High byte of first arg is a function. if the 100 bit is set, the function
refers to tv type displays, otherwise it refers to tk type displays.
.indent 5

TK display functions:
.indent 10

0 start display. Second arg is the word offset to start at

1 stop display. Args ignored
.indent 5

TV display information:

The tv functions are used for graphics on tv displays. The general
idea is that there exists a pen or "turtle" for each display. This pen
has a position on the screen which can be read or set. The functions
which draw lines on the screen expect arguments which are a delta y and
delta x relative to the current pen position. A full tv display has 455
horizontal lines of 576 points per line. The line drawing functions
change the position of the pen to a new relative position, but any invok
which would cause the pen to be left outside the screen, ie vertical
less than 0 or greater than 454, horizontal less than zero or greater
than 575, will fail and will be completely ignored.

TV display functions:

.TVDSR Read pen position. returns pen y position on top of stack
and pen x position next on stack.

.TVDSS Set pen position. expects y position as arg 2, x as arg 3.

.TVDSN Null line. expects delta y as arg 2 and delta x as arg 3.
just sets the pen to the new relative position.

.TVDSI Ior line. inclusive or's a series of points starting at
the current pen position and ending at new position.

.TVDSX Xor line. just like ior, but xor's the screen points.

.TVDSC Clear block. for this function, the pen operates in a
slightly different mode. Delta y and delta x are expected
as before, but in this case, they serve to delimit a
rectangular area in the screen which is cleared. The pen
is left at the diagonal corner.

.TVSAV Indicates that the executing process is using the TV registers
directly and the system should preserve them for it.

.TVMAP The first arg is the data page number where the first
page of the TV memory should be mapped in temporarilly. This only
has effect for the executing process, the 4 pages replaced
"shadow" the 4 pages in the sphere. If the first arg is negative
the pages are mapped out.
.indent 0

.TPCAP No invoks allowed.

.TRCAP No invoks allowed.

.LPCAP If the first argument is 0, the printer/plotter is put
into print mode. If the argument is non zero,
the printer/plotter is put into plot mode, and the scale factor is set to the argument.
The maximum scale factor is 4.  In print mode, the bytes output by
.BYTO, .WRDO, and .BLKO, are interpreted as ascii characters,
and printed as such.
In plot mode, the bytes are considered to be in one of two formats:
.indent 5

1. The first two bytes are taken to be the byte count for the current
line. The next series of bytes are the data bytes to be plotted,
and then the data for the next line. This continues until the
data is exhausted.
.indent 0

.CMCAP The first argument specifies wether this call sets a value
into the color map or establishes a coorespondence between a TV
display and a bit in the color map. If the .CMBIT bit is set
in the first argument the low byte of that argument should
be a capability to a TV display. If it is, that TV will
be set up to be bit 1, 2, 3, 4, 5 or 6 of the color map
input depending on the value of the second argument. This
call will set the video switch and the scroll word in
the TV. If the .CMBIT is not set the low byte of the first argument
is the color number to set, and the bits .CMRED, .CMGRN and
.CMBLU may be set to control which colors are set. The second argument
is the value to set the color to.

SITS filename protocal

A file name is communicated to the system by a pointer to the ascii
string of the file's name (or a pathname if a mutate call). The string is
terminatd by an ascii null or zero byte.

A pathname consits of several filenames concatenated with space between.

A filename consists of a string of ascii characters terminated by one
of the special characters <, >, space or null.

An optional version number is signaled by the character #.

FOO< is the file with the least version number.
FOO> is the file wit the the greatest version number.
FOO#123 is the file with version number 123.
FOO is the file with no version number.

Any character after double quote " is quoted and has no special properties.

Note that FOO never matches a file with a version number, and FOO< and
FOO> never match a file without a version number.