.he 'POPMESS''Page %'
.fo 'Steven Hardy''April 1978'
.ce2
THE POPMESS FUNCTION
====================
.sp
This handout explains the popmess function. Popmess is used by POP11
programmers to communicate with the underlying systems, that is the POP11 systemitself and UNIX.
.sp
Communication with UNIX is done by giving popmess a list as argument,
this list being analogous to a SYS call as described in Section 2 of the
Unix Programmer`s Manual. Communication with the POP11 system is
by altering the values of a set of global variables which control the POP11
system`s behaviour; in this case the argument of popmess is an integer
and the result of popmess is the value of the appropriate global
variable (popmess has an appropriate updater for setting these variables).
.sp
.ce2
Communication with Unix
-----------------------
.sp
Typically, a call to UNIX is done by giving popmess a list, the elements
of which are as specified in the UNIX programmers manual. Where an initial
assignment to r0 is called for, add an element to the right hand end
of the list (see, for example Read).
.sp
POP11 represents files by 'device records'. When such a record is garbage collected,
the corresponding file is 'closed'. Therefore, it is usually unnecessary to close
files explicitly. Where a call of popmess expects a device record it will accept an integer.
.sp
Chdir (12)
.br
----------
.sp
 	: popmess([%Chdir, <string>%]
.br
The current working directory of the POP11 system is changed to <string>.
There is no result to this call of popmess.
.sp
Chmod (15)
.br
----------
.sp
 	: popmess([%Chmod, <name>, <mode>%])
.br
The file, whose name is given (as a string) has its mode changed to the integer
<mode>. There is no result to this call of popmess.
.sp
Chown (16)
.br
----------
.sp
 	: popmess([%Chown, <name>, <owner>%])
.br
The file whose name is given (as a string) has its owner and group
changed to the person specified by the integer <owner>. This call
of popmess has no result.
.sp
Close (6)
.br
---------
 	: popmess([%CLose, <fildes>%])
.br
Given a file descriptor such as returned from an Open, Creat or Pipe
call, Close closes the associated file. This call of popmess has no result.
(The file descriptor may be an integer, this is useful for manipulating
standard input and output).
.tp8
.sp
Creat (8)
.br
---------
.sp
 	: popmess([%Creat, <name>, <mode>%])
.br
This call of popmess creates a new file, or prepares to rewrite an existing file
called <name> (a string). If the file does not exist it is given
mode <mode>. The result of this call of popmess is a device record.
.sp
Csw (38)
.br
--------
.sp
 	: popmess([%Csw%])
.br
This call of popmess returns the setting of the console switches, as a 15
bit integer. (ie. bit 15 of the console switches is ignored).
.sp
Dup (41)
.br
--------
.sp
 	: popmess([%Dup, <fildes>%])
.br
Given a file descriptor, this call of popmess allocates a new
file descriptor synonymous with the original. The new file descriptor
is the result of the call of popmess.
.sp
Exec (11)
.br
---------
.sp
 	: popmess([%Exec, <name>, <arg-0>, ..., <arg-n>%])
.br
This call of popmess changes the current process to be the program described
by <names>, the arguments of this new process are as given. Obviously,
this call of popmess should never return, though it may give an error.
.sp
Exit (1)
.br
--------
.sp
 	: popmess([%Exit, <status>%])
.br
The current POP11 process is terminated with status as indicated by the supplied
integer. This call of popmess is always successful and never returns.
See popmess ([%Wait%].
.sp
Fork (2)
.br
--------
.sp
 	: popmess([%Fork%])
.br
Fork is the only way new processes are created. The new process`s core
image is a copy of the POP11 system issuing the Fork request. the new
process gets result FALSE from popmess and the parent process gets the
process identification number of the child as its result., The new
(child) process has the value of 'interrupt` set to
 	: popmess(%[%Exit%]%)
.br
so an error or interrupt will terminate its execution. This may,
of course, be overridden by the user.
.sp
.tp8
Getpid (20)
.br
-----------
.sp
 	: popmess([%Getpid%])
.br
This call of popmess returns (as an integer) the process identification of the current
process.
.sp
Getuid (24)
.br
-----------
.sp
 	: popmess([%Getuid%])
.br
This call of popmess returns an integer, the low byte of which is the
current user`s identification number. (The high byte is the
.ul
effective
user identification number of the current process).
.sp
Gtty (32)
.br
---------
.sp
 	: popmess([%Gtty, <arg>, <fildes>%])
.br
The six element character strip <arg> is filled with the status of the
typewriter whose file description is given. There is no result to this
call of popmess.
.sp
Kill (37)
.br
---------
.sp
 	: popmess ([%Kill, <pid>, <sig>%])
.br
The signal <sig> is sent to the process <pid>. There is no result
to this call of popmess.
.sp
Link (9)
.br
--------
.sp
 	: popmess([%Link, <name1>, <name2>%])
.br
A link to <name1> is created, the new link has the name <name2>.
.sp
Unlink (10)
.br
------------
.sp
 	: popmess([%Unlink, <name>%])
.sp
a Wait (?)
.br
----------
.sp
 	: popmess([%Wait%])
.br
This call of popmess waits for a childprocess to die
and then returns its exit status.
.sp
.ce2
Communication with POP11
------------------------
.sp
As indicated in the introduction, there are a set of global variables
which can be altered by the user to affect the POP11 system's behaviour in
various ways.
.sp
.tp4
Arglist (15)
.br
------------
.sp
The value of this variable is a list of the arguments by which the
POP11 system was invoked.
.sp
Closeket (4)
.br
------------
.sp
The value of this variable is the current compiler
closing bracket, for example at execute level this will be
Termin, inside a function it might be "end". This is useful if you
want to have macros that behave differently
depending on where they are invoked.
.sp
Cucharin (10)
.br
-------------
.sp
The value of this variable is the argument of the current call of 'compile`,
it will be a character repeater. this is useful for reading characters
from the input stream and for finding which file is currently being
compiled.
.sp
Funcnames (7)
.br
-------------
.sp
The value of this variable is a list, being the names of functions
currently being compiled (Lambda expressions are denoted by FALSE).
.sp
Garbage (14)
.br
------------
.sp
The value of this variable is a pointer to the garbage collector so that
you can force a garbage collection by executing:
 	: popmess(Garbage)();
.sp
Gcfree
.br
-----
.sp
The value of this variable is the number of words of memory not in use
at the last garbage collection.
.sp
Gcfun (1)
.br
---------
.sp
The value of this variable is a function (initially identfn). This function
is invoked after each garbage collection.
.sp
Gcstatus (24)
.br
-------------
.sp
The value of this variable is the number of stack overflows during
the most recent garbage collection.
.sp
Gcused
.br
------
.sp
The value of this variable is the number of words of memory
in use at the last garbage collection.
.sp
Gensym (23)
.br
-----------
.sp
The value of this variable is a function which, when invoked
with no arguments
produces a unique words as its result. This word is not entered in
the dictionary and will be garbage if appropriate.
.sp
.tp8
Lastchar (9)
.br
------------
.sp
The value of this variable is the last character read by the POP11 system
from the keyboard.
.sp
Lastitem (6)
.br
-------------
.sp
The value of this variable is the last item read by the POP11 compiler.
.sp
Liblist (19)
.br
------------
.sp
The value of this variable is a list of device records representing
library files in use by the current POP11 system. this list is initialised
to contain only one element representing /lib/pop.1 (see the LIBRARY demo).
.sp
Linemax (16)
.br
------------
.sp
The POP11 system will insert a newline character if the number of characters
printed to the output teletype exceeds Linemax on any one line.
(See Linewidth).
.sp
Linewidth (17)
.br
--------------
.sp
If the number of characters printed on the curent output teletype
line exceeds Line width but does not exceed Linemax, then
spaces and tabs will be mapped to a newline
character.
.sp
Dictionary (11)
.br
---------------
.sp
The value of this variable is the system dictionary. The dictionary is a
strip whose elements are either false, a word or a list of words. You
would be extremely ill-advised to add words to this data structure
although removing words is usually safe.
.sp
Prompt (8)
.br
----------
.sp
The value of this variable is a string. (initially ':`) to
be printed as an invitation to type on the input teletype.
.sp
.tp4
Stack (25)
.br
----------
.sp
The value of this variable is a strip holding the contents of the stack
on entry to the current call of COMPILE.
.sp
Stacklength (12)
.br
----------------
.sp
The value of this variable is a function which,
if invoked with no arguments, returns the number of items on the user
stack.
.sp
Child (20)
.br
----------
.sp
The value of this variable is the 'pid` of the last child of the
POP11 process to be waited for with popmess ([%Wait%]).
.sp
Thisitem (5)
.br
------------
.sp
The value of this variable is the item the compiler is currently considering.
.sp
Tickfun (13)
.br
------------
.sp
The value of this variable is a function of one argument (initially
erase). This function is invoked periodically, the argument
being the processor time (in hundredths of a second) since it was last invoked.
This will usually be two unless there has been a garbage collection when it
will be much more.
.sp
Tracepr (21)
.br
------------
.sp
The value of this variable is a function (initially pr) used to print arguments of TRACEd functions.
.sp
Uppercase (22)
.br
--------------
.sp
The value of this variable will be true if the POP11 system
has been invoked from an upper-case only terminal.
