\section{SOTEST Structure}

SOTEST consists of three major pieces:

\begin{itemize}
\item 80186 (or 80188) engine
\item SOTL (thread language) interpreter
\item Command-line interface
\end{itemize}

The first piece, the 80186/8 engine, is capable of simulating one or
more 80186/8-based ``machines.''  Each machine is represented by an
array of memory, an array of ports, registers, flags, a clock, an
interrupt controller, a timer manager, and a DMA controller.  The chip
select unit is not simulated, but there are other ways to achieve its
effects.  The engine simulates at the instruction level rather than at
the logic level; that is, no 80186 pins are simulated and no
logic-level signals are generated.

The second piece is the SOTL interpreter.  SOTL is the name of the
debugging command language, a multi-threaded procedural language that
can be used to write test scripts, simulate external hardware, monitor
the execution of the target, or perform frequently-used combinations
of top-level commands.  SOTL supports all of the standard C operators,
has procedures and local variables (distinct from the target's
procedures and local variables), provides operators to examine and
control the simulated 80186, provides access to the target's debugging
information (target local variables and type information), and
provides access to certain UNIX system calls (in particular,
interprocess communication via System V \(msg___\) calls or Berkeley
sockets).  In addition, threads can send messages to one another.

The third piece is the command-line interpreter.  It is very simple;
it reads a SOTL statement from standard input, creates a thread for
it, and starts that thread running.  When that thread completes, the
user is prompted for another command.


\section{Threads and Scheduling}

When the user types a command, a thread is created for it.  This
thread is the ``foreground thread,'' and until it dies, the user
cannot execute any more commands.  There may only be one foreground
thread at a time, but the foreground thread can fork (create) other
threads.  The user may kill the foreground thread by pressing
control-C.

Certain commands can cause the foreground thread (or any other thread)
to block.  Blocking means the thread says it has nothing more to do,
for the time being at least.  Receiving an event is the only thing
that causes a thread to unblock.  Before a thread blocks, it specifies
which events it's interested in; a read from a certain range of memory
addresses, for example, can cause an event.  There are several other
ways events can be generated, which will be discussed later.  The user
may also subscribe to events; when the user receives an event, the
event is displayed on the screen, and the foreground thread is killed.

When the foreground thread dies, either by exiting, when the user
receives an event, or when the user presses control-C, all other
threads (background threads, which may have been forked from the
foreground thread) are then allowed to run until they block or exit.
Finally, the user is allowed to type another command, starting a new
foreground thread.  If a background thread is misbehaving, and simply
runs continuously, there is no way for the user to stop it.  However,
a thread can be put into debug mode.  When the user presses control-C,
all threads in debug mode are frozen, and the user may type commands.
The threads are unfrozen either explicitly by the user (using the
\(threadunfreeze\) command), when they are taken out of debug mode, or
when the user uses the \(go\) command.

When the foreground thread is blocked, and all other threads are
blocked or frozen, the engine starts interpreting machine instructions
until an event is generated or the user presses control-C.  When the
machine generates an event for a thread, if the thread is not frozen,
it will receive the event and unblock.  If the thread is frozen, the
event is entered onto an event queue for the thread, which will be
processed when the thread is unfrozen.  If the thread is in debug
mode, a warning message is printed informing the user about the event.

Runnable threads have highest priority in the system.  As long as any
thread has something to do ({\it i.e.,} it is neither blocked nor frozen),
it runs, and all machines are effectively halted; registers and the
clock hold their values.  Further, user input is ignored.  However,
the user can always take control by pressing control-C.  This
interrupts whatever SOTEST is doing (executing 80186 instructions or
running threads), kills the foreground thread, and marks threads in
debug mode (whether blocked or running) as frozen.  All threads have
the same priority; if several become runnable at once (through being
unfrozen or receiving events), which runs first is apparently random.

\section{SOTL Types}

\subsection{Primitive Types}

There are many primitive data types in SOTL.  The simplest is the
dword, which is an unsigned number from 0 to $2^{32} - 1$.  A dword
constant is like an integer constant in C, except that Intel
hexadecimal notation is permitted ({\it e.g.,} \(0d73h\)).  Time is a
primitive type, measured in {\it ticks} (clock cycles).  A time value
is created with the syntax {\it minutes\(:\)seconds\(.\)ticks,} where
{\it minutes, seconds,} and {\it ticks} are integer constants.  For
example, \(1:23.13000000\) represents one minute, 23 seconds, and 13
million ticks.  The string is a primitive type; like in C, a string
constant is an array of characters in double-quotes, {\it e.g.,}
\("hello"\).  Unlike in C, strings are not null-terminated; their
length is recorded, and they may contain any characters.  Strings can
also be constructed from hex by using backquotes as in \(`1A2B3C4D`\),
in which whitespace is allowed.  The string constant \(`41 42 43`\)
creates the string
\("ABC"\).  Strings can be accessed with array reference operators;
\("ABC"[1]\) returns 66 (the ASCII code for \(B\)).

There is also a primitive type that represents a block of target
memory.  This type is called a ``block,'' and is created with the
syntax {\it \([\)address\(,\)size\(]\).} If the size is 1, 2, or 4,
then the block can be used anywhere a dword can be used; when the
dword is needed, memory at the address is read (generating memory read
events.)  The \(memoryfetch\) command creates a string whose characters
are the contents of the block.  Blocks can also be displayed
conveniently with the \(print\) command.  For example, \(x=[1234h:5678h,4]\)
assigns to x a reference to 4 bytes at address \(1234h:5678\).  Then
\(x+10\) reads a dword from that address and adds 10 to it, \(print %b x\)
prints out the 4 bytes stored there, and \(y=memoryfetch x\) creates a
string of length four containing those bytes and assigns it to \(y\).

The pattern (or regular expression) is a primitive type.  Strings can
be tested to see if they can be see if they match a pattern; a pattern
matches a set of strings.  For example, you can write a pattern to
match all strings that start with \(`03 04 05`\) and end with
\(`A6`\); see the \(=~\) and \(!~\) operators.  The syntax for
constructing patterns is described below.

Other primitive types include source code modules, machines
(processors being simulated), user-defined procedures (called SOTL
functions), and references and pointers to target data objects (using
target debugging information).  UNIX file descriptors and message
queue ID's are also primitive types.  One final type is the null type;
the only null value is \(nil\), which is returned by commands that have
no meaningful return value.  It is also placed anywhere that would be
uninitialized in C (such as in otherwise uninitialized arrays).

\subsection{Aggregate Types}

The array is the only aggregate type.  The lower index of an array is
always zero.  Arrays grow on demand; accessing an element past the end
of an array causes the array to grow.  The untouched elements of the
array are all initially \(nil\).  The elements of an array may be of any
type; they need not be all the same type.  Although multidimensional
arrays are not directly supported, elements of arrays may be other
arrays.  However, if you set up a cyclical structure (for example,
with \(x[0] = 0; x[2] = x;\)) then SOTL's memory manager will never free
the array(s) involved in the cycle.

Arrays need not be declared.  If, before storing anything into a
variable, you use the array reference operator on it, the variable
becomes an array.

   Example: \(a[10] = 17;   a[13][4] = 26;   print a[3];   ==> nil\)

\subsection{Booleans}

SOTL does not have a boolean type.  Similar to C, any non-zero dword
is considered true, and 0 is considered false.  A string of positive
length is considered true, and the empty string is considered false.
All values of other types are considered true besides \(nil\), which is
considered false.

\section{SOTL Identifiers}

Identifiers are like C identifiers, except that dollar-sign (\($\)) is
allowed within identifiers.  It is recommended that you use a
dollar-sign as the first character of all SOTL variables, in order to
avoid accidental naming conflicts with target symbols.

The rules SOTL uses to find the values of identifiers are not simple.
This is because SOTL has three namespaces, all of which are in effect
simultaneously.  There are SOTL variables and objects (global and
local), debugging symbols (global and local), and public symbols and
segment names.  The procedure SOTL follows when looking up an
identifier follows.  First, locals for the current SOTL function are
checked, and SOTL globals are checked.  Then, debugging symbols for
the current frame are searched.  These are the only three
context-dependent cases.  There is a cache mapping identifiers to
their context-independent values; this cache is checked next.  If
there is nothing in the cache, then the following lists are checked;
if anything is found, it is stored in the cache.  These lists, in
order, are SOTL globals, user-supplied SOTL extension function names,
machine names, account names, register names, public symbols,
debugging globals (including module-global static variables), and
segment names.

If an identifier is not found, and it is assigned to, then a SOTL
variable is created.  If the SOTL code is executing inside a SOTL
function, the variable will be created locally to that function;
otherwise, it is created globally.  If you want to create a SOTL
variable explicitly, you can use the \(local\) or \(global\) command
operators.  It is recommended that you always use these operators when
creating variables.  Here is an example of what can go wrong if you
don't:

\code
     def $foo ($x) {
         $temp = $x;
         if ($x > 0) { foo ($x - 1); }
         print $temp;
     }
     $foo(2);     \yields(0  1  2)
     $temp = 10;
     $foo(2);     \yields(0  0  0)
\code

Notice that the assignment to \($temp\) on line 7 made \($temp\) global,
causing the recursive \($foo\) to do something very different than
intended.  The problem is fixed by inserting \(local $temp;\) after the
first line.

\section{SOTL Patterns}

Patterns are always found between pairs of forward-slashes (\(/\)).
Inside the slashes, period (\(.\)) matches any byte, and dollar-sign
(\($\)) matches the end of the string.  Other elements may be string
constants or SOTL variables that hold strings.  So, for example,

\def\regexpexample{\(\catcode`\&=4\relax\doreexample}
\def\doreexample#1\crcr{\halign{\hskip 1in ##\quad\hfil&\rm ##\hfil\cr
#1\crcr}\)}

\regexpexample
`001122` =~ /`00 11 22`/&returns true,\cr
`001122` =~ /.  `1122` \$/&returns true,\cr
`001122` =~ /`0011`/&returns true,\cr
`001122` =~ /`0011` \$/&returns false, and\cr
`001122` =~ /. . . ./&returns false.\crcr

Operators within regular expressions include question-mark (\(?\)),
which makes the preceeding term optional; star (\(*\)), which allows
the proceeding term to match 0 or more times; plus (\(+\)), which
allows the proceeding term to match 1 or more times; and vertical-bar
(\(|\)), which matches if either the term on its left or the term on
its right matches.  Parentheses (\((\) and \()\)) group terms
together.  Finally, a string in brackets (\([\) and \(]\)) matches any
single character which is in the string; if the string is prefixed
with caret (\(^\)), it matches any single character not in the string.
Thus,

\regexpexample
`00112233` =~ / (.*) `22` . `66`? \$/&returns true,\cr
"aaad"     =~ / "a"+ "b"* "c"? "d" \$/&returns true,\cr
"@q@q"     =~ / (`40` "q")+ \$/&returns true,\cr
"wxyz"     =~ / "w" ("xy" | "yx") "z" /&returns true,\cr
"abccbd"   =~ / "a" ["bc"]+ "d" /&returns true, and\cr
"abccbd"   =~ / [^"bc"] "bccb" [^"bc"]&returns true.\crcr

After a successful match, substrings of the matched string can be
extracted.  The variable \($0\) holds the portion of the string that
matched the regular expression, \($1\) holds the portion of the string
that matched the first parenthesized subexpression in the regular
expression, \($2\) holds the second, and so on.  Thus, after the first
of the above examples, \($0\) holds \(`00112233`\) and \($1\) holds
\(`0011`\).  After the match

\centerline{\("abcbcbcdddde" =~ / ("a" ("bc" *)) ("d"+) /\)}

\noindent 
returns true, \($0\) holds \("abcbcbcdddd"\), \($1\) holds \(abcbcbc\), \($2\)
holds \("bcbcbc"\), and \($3\) holds \("dddd"\).  
This behavior is useful for parsing.

\section{SOTL Expressions}

SOTL expressions contain operators, identifiers, integer constants,
string constants, and time constants.  Operators include most of the C
operators, and also a considerable set of keyword prefix operators,
called ``commands.''  Each command can be abbreviated when it is the
first thing on a line.  A description of each command appears below.

\subsection{SOTL Operators}

SOTL supports most C operators, and uses the same precedence rules.
However, some operators are overloaded and have different meanings in
different contexts, for the convenience of the SOTL programmer.  In
the following section, {\it x}, {\it y}, and {\it z} represent
expressions (which presumably contain no operators of lower precedence
than the ones being demonstrated.)  Precedence rules are the same as
in C.  The operators are presented here in order from low to high
precedence.  All standard C prefix operators actually have the same
precedence, and all postfix operators all have the same (highest)
precedence.  There are a few infix operators that are higher
precedence than the prefix operators.

\def\x{{\it x}}
\def\y{{\it y}}
\def\z{{\it z}}

\leftskip = 0.5in

\def\thingy#1{\par\noindent\hbox to 0pt{\hskip -1.0in \it #1\hss}}

\def\Command#1{\smallskip\thingy{Command}{\tt #1}}
\def\Abbreviated#1{\thingy{Abbreviated}{\tt #1}}
\def\Example{\thingy{Example}}
\def\Description{\thingy{Description}}
\def\SystemCall#1{\thingy{System Call}{\tt #1}}
\def\Type#1{\thingy{Type}{\tt #1}}
\def\Details#1{\thingy{Details}{\it #1}}
\def\Constructor{\thingy{Constructor}}
\def\Predicate#1{\thingy{Predicate}{\tt #1}}
\def\Meaning{\thingy{Meaning}}

\def\construction{\(\doconstruction{Construction}}
\def\Statement{\(\doconstruction{Statement}}
\def\doconstruction#1#2\crcr{{\singlespace\thingy{#1}%
\noindent\hbox{\vtop{\halign{\tt ##\hfil\cr
#2\crcr}}}}\par\)}

\construction \x\ = \y\cr
   \x\ += \y\cr
   \x\ -= \y\cr
   \x\ *= \y\cr
   \x\ /= \y\cr
   \x\ %= \y\cr
   \x\ >>= \y\cr
   \x\ <<= \y\crcr
\Meaning      \y\ is evaluated.  In the first case, the result is
              assigned to \x; in the second, it is added to \x; and
              so on.


\construction \x\ ?\ \y\ !\ \z\crcr
\Meaning      \x\ is evaluated.  If it is true, then \y\ is evaluated and
              returned; otherwise, \z\ is evaluated and returned.  Note
              that \(!\) is used instead of \(:\).  This is because \(:\)
              already has several other meanings, and overloading it
              further is not feasible.


\construction \x\ || \y\crcr
\Meaning      \x\ is evaluated.  If it is true, it is returned.
              Otherwise, \y\ is evaluated and returned.  Note that this
              is more like the Lisp meaning of the \(or\) operator
              than the C meaning;
              in C, the return value is always 0 or 1.

\construction \x\ && \y\crcr
\Meaning      \x\ is evaluated.  If it is false, it is returned.
              Otherwise, \y\ is evaluated and returned.


\construction \x\ | \y\crcr
\Meaning      \x\ and \y\ are evaluated and their bitwise-or is returned.


\construction \x\ ^ \y\crcr
\Meaning      \x\ and \y\ are evaluated and their bitwise-xor is returned.


\construction \x\ & \y\crcr
\Meaning      \x\ and \y\ are evaluated and their bitwise-and is returned.


\construction \x\ == \y\cr
              \x\ != \y\cr
              \x\ =~ \y\cr
              \x\ !~ \y\crcr
\Meaning      \x\ and \y\ are evaluated.  In the first two cases, \(==\) and
              \(!=\), if they are dwords or time values, they are
              compared numerically.  If they are strings, they are
              considered equal if they have the same length and each
              character is the same.  For \(==\), if they are equal,
              then 1 is returned; otherwise, 0 is returned.
              Conversely for \(!=\).


              In the second two cases, \x\ must be a string and \y\ must
              be a pattern.  For \(=~\), true is returned if the string
              matches the pattern, and false otherwise.  Conversely
              for \(!~\).

\construction \x\ <= \y\cr
              \x\ >= \y\cr
              \x\ > \y\cr
              \x\ < \y\crcr
\Meaning      \x\ and \y\ are evaluated and compared.  They must be dwords
              or time values.  If the comparison is true, then 1 is
              returned; otherwise, 0 is returned.


\construction \x\ + \y\cr
              \x\ - \y\crcr
\Meaning      \x\ and \y\ are evaluated and added (or subtracted).  They
              must be dwords or time values.  If only one is a time
              value, the result is another time value; when promoting
              a dword to a time value, the dword is taken to be a
              number of ticks.
\Example      \(100 + 1:2.3\) \yields(1:2.103)


\construction \x\ :\ \y\crcr


\Meaning      
              If \x\ is a dword and \y\ is a dword, then another dword is returned
              using the formula \((x << 16) + y\) (this is for {\it
              segment}\(:\){\it offset} notation).  If \x\ is a dword
              and \y\ is a time value (usually in the form $a\(.\)b$),
              then a time value $x\(:\)a\(.\)b$ is created (this is for time
              value constants).  If \x\ is a source code module and
              \y\ is a dword, then the address of line \y\ of module
              \x\ is returned (this is for line number references).
              If \x\ is a machine and \y\ is a symbol, then the
              address of symbol \y\ in machine \x\ is returned (making 
              it possible to override the current machine when a symbol is
              being looked up).


\construction \x\ * \y\cr
              \x\ / \y\cr
              \x\ % \y\crcr
\Meaning      \x\ and \y\ are evaluated, and their product, quotient, or
              remained of division is returned.


\construction + \x\crcr
\Meaning      An address \x\ bytes from the top of the current function
              is returned.


\construction :\ \x\crcr
\Meaning      The address of line \x\ in the current module is returned.

        
\construction ~ \x\cr
              - \x\cr
              !\ \x\crcr
\Meaning      The binary, two's complement, or boolean negation of \x\
              is returned.


\construction & \x\cr
              * \x\crcr
\Meaning      These are pointer operators as in C.  Note that \x\ must
              be a reference to a target data object in the first
              case, and a pointer to a target data object in the
              second.  You may not take the address of a SOTL object;
              SOTL itself does not have a pointer type.  These
              operators can only be used when target debugging information
              is available.


\construction ++ \x\cr
              -- \x\crcr
\Meaning      \x\ is evaluated; the result is incremented (or
              decremented), stored back in \x, and returned.


\construction \x\ -> \y\crcr
\Meaning      \x\ is evaluated, and must be a pointer to a target data
              object that is a structure.  \y\ must be a single
              indentifier, and is interpreted as a field of the
              structure.  A reference to the field is returned.


\construction \x\ .\ \y\crcr
\Meaning      \x\ is evaluated.  If \x\ is a reference to a target data
              object that is a structure, then \y\ must be a single
              indentifier, and is interpreted as a field of the
              structure; a reference to the field is returned.  If \x\
              is a string, then \y\ must be a string, and their
              concatenation is returned.  Otherwise, \x\ and \y\ must be
              dwords, in which case a time object with \x\ seconds and \y\
              ticks (0:\x.\y) is returned.


\construction \x\ [ \y\ ]\crcr
\Meaning      \x\ is evaluated, and must be either a SOTL array, a SOTL
              string, a reference to a target data object that is an
              array or a pointer, or a pointer to a target data
              object.  \y\ is evaluated, and must be a dword.  If \x\ is a
              SOTL array, a reference to the SOTL object
              stored an the array is returned.  If \x\ is a SOTL string, the
              byte stored in that position of the string (or -1 if \y\ i
              out of range) is returned.  If \x\ is a target array, a target
              pointer, or a pointer to a target object, a
              reference to the appropriate target data object is returned.


\construction \x\ ( arg1, arg2, ... )\crcr
\Meaning      \x\ is evaluated, and must be a SOTL function.  The arguments
              are all evaluated, and the values are passed to \x.  The
              result of the final evaluation in \x\ is returned.


\construction \x\ ++\cr
              \x\ --\crcr
\Meaning      \x\ is evaluated and its value is returned.  Then, that
              value is incremented (decremented) and stored back in \x.


\construction .\crcr
\Meaning      The current value of \(CS:IP\) is returned.


\construction _\crcr
\Meaning      The top of the current function is returned.  This is
              the same as \(+ 0\).


\construction [ \x\ ]\cr
              [ \x\ , \y\ ]\crcr
\Meaning      An object representing a block of target memory is created.
              The address is \x, and the size is \y\ if specified, and 4
              if not.  If the size is 1, 2, or 4, then this reference
              promotes automatically into a dword whenever a dword is
              needed.  This promotion will generate a memory read
              event.  Blocks are useful with the print command (see
              below) and can also be converted into strings.
\Example      \(enterbyte 100, 123; x = [100, 1]; print x, " = ", x + 0;\)\\
              \bigyields([0000:0064 , 1] = 123)

        
\construction ( \x\ )\crcr
\Meaning      \x\ is evaluated and returned.  This construction exists
              to override operator precedence.

                
\construction { statement; statement; ... }\crcr
\Meaning      The statements are executed and the result of the final
statement is returned.
\Example      \(x = { while (1) ..... };\)

\leftskip = 0pt

\section{SOTL Statements}

There are very few statements in SOTL.  As in C, most things that you
might think of as statements (such as printing things, setting
breakpoints, and so on) are actually expressions.  There are, in fact,
only five statements, and two are trivial.

\leftskip = 0.5pt

\def\e{{\it expression}}
\def\s{{\it statement}}
\def\n{{\it name}}
\def\a#1{$arg_{#1}$}

\Statement \e ;\crcr
\Meaning   Evaluate the expression.  If this
is the last statement of a procedure, then its value is the
return value for the procedure. Otherwise, the value is
thrown away.

\Statement ;\crcr
\Meaning   This is the empty statement, and has no effect.

\Statement if \e\ { \s; ... }\cr
if \e\ { \s; ... } else { \s; ...}\cr
if \e\ { \s; ... } elsif \e\ ...\crcr
\Meaning   The expression is evaluated.  If it is true, the first
block is evaluated and its final value returned.
Otherwise, there are three cases.  If there is an else
clause, then the else block is evaluated and its final
value returned.  If there is an elsif clause, it is treated
just like an if.  If there is no clause, then \(nil\) is
returned.  Unlike in C, the then-clause and else-clause
must be grouped in curly-braces, even if there is only one
statement.

\Statement while \e\ { \s; ... }\crcr
\Meaning   The expression is evaluated.  If it is true, the block is
evaluated and the expression is checked again.  If it is
false, its value is returned.  Note that while statements
always return false.

\Statement def \n\ ( \a1, \a2, ... ) { \s; ... }\crcr
\Meaning   This statement creates a SOTL function and assigns it to
the given name.  This statement always returns \(nil\).

\leftskip=0pt

\section{SOTL Command Operators}

SOTL commands are actually prefix operators.  Unlike the other (more
typical) prefix operators like \(++\), which operate only on the term
immediately on their right, SOTL prefix operators can grab several
whole expressions separated by commas.  They have the lowest
precedence of any operator.

Many commands operate on a machine.  While a few commands explicitly
take a machine as an argument, most commands work on the ``current
machine.''  Each thread has its own notion of what the ``current
machine'' is; the current machine is preserved through procedure calls.

Many command operators can be abbreviated.  These abbreviations are
only recognized if the command is the first non-whitespace item on a
new line.  Abbreviations are meant to be used only at top-level,
although they may be used in SOTL source files as well.

Many command operators take one or more arguments.  These arguments
may optionally be enclosed by parentheses.  But beware: some examples
should make clear the unexpected results this convenient syntax can
sometimes cause.

{\singlespace
\leftline{\hskip 0.5in\hbox{\vbox{\halign{{\tt
#}\hfil\quad &\vtop{\vtop{\hsize=4in\noindent #}\vskip 3pt}\hfil\cr
\it Expression&\it Meaning\cr
\noalign{\vskip 2pt\hrule\vskip 2pt}
foo 2,3&Apply the \(foo\) operator to 2 and 3\cr
foo (2,3)&Same as above\cr
foo (2,3) + 4&Apply the \(foo\) operator to 2 and 3, and add four
to the result\cr
(foo 2,3) + 4&Same as above\cr
foo 2,3 + 4&Apply the \(foo\) operator to 2 and 7.  This may not
be what you meant; you probably meant the above.\cr
foo 1+2*3&Apply the \(foo\) operator to 7\cr
foo (1+2*3)&Same as above\cr
foo ((1+2)*3)&Apply the \(foo\) operator to 9\cr
foo (1+2)*3&Apply the \(foo\) operator to 3, and multiply the
result by 3.  This is certainly not what you meant!\cr
}}}}}

\medskip

As you can see, this is tricky.  If you want to be safe, always
parenthesize the intended arguments of command operators.

\leftskip=0.5in

\Command{break}
\Abbreviated{b}
\Example\(break _main, 0:10.23, memorywrite(_foo, _foo+20)\)
\Description Allows the user to specify what events are of interest.
When one of these events is received, it causes a
``break.'' A message describing the event is printed, the
foreground thread is killed, all freezable threads are
frozen, and control is returned to top-level as if the
user pressed control-C.  \(break\) takes a comma-separated
list of event specifications as its argument; see the
section on event specifications for more information.

\Command{breaklist}
\Abbreviated{bl}
\Description Lists the events specifications that will cause breaks.
They are listed with numbers that can be used to refer to
them.  This command takes no arguments.

\Command{breakdelete}
\Abbreviated{bd}
\Example\(breakdelete 2, 3\)
\Description Takes a comma-separated list of numbers as its argument,
and deletes the event specifications with those numbers.

\Command{breaknow}
\Abbreviated{bn}
\Description Allows a thread to signal a break.  When any thread
executes this command, a message is printed, the
foreground thread is killed, all freezable threads are
frozen, the user is returned to top level.

\Command{backtrace}
\Abbreviated{bt}
\Description Divides the stack of the current machine into its frames,
and for each frame prints the name of the procedure and
the values of its arguments.  Frame 0 is the innermost
(deepest) frame; frame 1 is the frame of frame 0's
caller, frame 2 is frame 1's caller, and so on.  This
command is only avaiable if the target has been compiled
with debugging information.  It takes no arguments.

\Command{blockuntil}
\Abbreviated{bu}
\Example\(blockuntil messagereceive, portread(0x400)\)
\Description Has two functions.  First, it subscribes to events the
current thread is interested in receiving.  Second, it
blocks the thread.  When an event matching one of the
event specifications is received, the thread will
unblock.  Like \(break\), its arguments are event
specifications.

\Command{call}
\Abbreviated{c}
\Example\(call _printf\)
\Description Initiates a target procedure call.  The registers and
flags are saved, \(CS:IP\) is set to the given address, and
the thread blocks until the call returns.  When the
target function returns, the thread unblocks, and the
value of the call operator is the value of DX:AX.  Then
the registers and flags are restored.  This operator is a
hack.  Do not use it if you can think of any way around
it.  If the thread dies before the call returns, chaos
ensues, and SOTEST will probably crash.  I will probably
either fix this soon, or delete the call mechanism.

\Command{chdir}
\Abbreviated{cd}
\Example\(chdir "/tmp"\)
\Example\(print chdir\)
\Description With a string argument, it changes SOTEST's notion of the
current working directory.  In any case, the current
working directory is returned as a string; the second
example above prints the current working directory.

\Command{clockclear}
\Abbreviated{cc}
\Description Clears the value of the clock for each machine.  It also
sets the record of the amount of host CPU time 
used by SOTEST to 0.

\Command{clock}
\Description Returns the value of the clock for the current machine.

\Command{copy}
\Abbreviated{cp}
\Example\(copy _my_data, _your_data, 100\)
\Description Copies memory from the first address given to the second
addres given; the third argument is the number of bytes
to copy.  Overlapping copies are supported.  No memory
write events are generated for the copy.

\Command{defined}
\Abbreviated{df}
\Example\(defined $my_symbol\)
\Description Tests if the given symbol is defined.  If it is defined
in any way --- as a SOTL variable, a target local symbol,
a machine register, or the name of a code module, for
example --- the operator returns 1.  Otherwise, it
returns \(nil\).

\Command{dmarequest}
\Abbreviated{dr}
\Example\(dmarequest $channel, 1\)
\Description Sets the value of the DMA request line (DRQ0 or DRQ1) for
the given channel, which must be 0 or 1.  The second
argument must be true or false.  If a DMA channel is
synchronized, then DMA is allowed only if this value is
true.  This value is not used if the DMA channel is
unsynchronized.  See documentation about the 80186 family
of processors for more information on the DMA controller.

\Command{down}
\Abbreviated{dn}
\Description Moves down one stack frame.  This is available only if
the module was compiled with debugging information.

\Command{dump}
\Abbreviated{d}
\Example\(dump es:0x1234\)
\Description Displays 128 bytes of memory starting at the given
address.  If the address is omitted, the next 128 bytes
are displayed.  No memory read events will be generated
for the memory displayed.  If a memory location is under
examination by one or more threads, a \(?\) will be
displayed after the value, meaning that the value
displayed is not necessarily what an instruction reading
the location would see.  In this case, the value
displayed is merely the last value written to the
address.

\Command{enterbyte}
\Abbreviated{eb}
\Example\(enterbyte 0x1234:10, 1, 2, 3, 4\)
\Description Enters bytes into memory.  The first argument is the
starting address; the remaining arguments are bytes to
enter, each at the next address.  Memory write events are
generated for these writes, but will not be processed
until the thread blocks.

\Command{eval}
\Abbreviated{ev}
\Example\(eval ev = 10, pdq = 20\)
\Description Evaluates a list of expressions.  This takes the place of
the C comma operator.  Also, it works around the rare
case when you want to begin an expression whose first
term is a command abbreviation.  Note that while the
command \(eval g = 10\) does what you want (sets variable
\(g\) to 10),
typing \(g = 10\) alone does not.  You can also
work around this with parentheses, by typing \((g = 10)\).

\Command{enterword}
\Abbreviated{ew}
\Description Like enterbyte above, except it stores words in every
other address starting from the one specified.

\Command{fill}
\Abbreviated{f}
\Example\(fill cs:0, cs:0xfffe, 123\)
\Description Fills a range of memory with a single byte quickly,
without generating memory write events for memory
modified.  The three arguments are the starting address,
the ending address, and the byte to fill with.  Note that
the ending address is exclusive, {\it i.e.,} \(fill 10, 10, 123\)
is a no-op, whereas \(fill 10, 11, 123\) writes one byte.

\Command{flag}
\Abbreviated{fl}
\Example\(flag if = 1\)
\Example\($overflow = flag of\)
\Description Returns the value of an 80186 flag.  If used as an
lvalue, it changes the value of a flag.  Legal flags are:

{\singlespace\halign{\hskip 2in\tt #\quad& #\hfil\cr
cf & Carry flag\cr
pf & Parity flag\cr
af & Auxiliary flag\cr
zf & Zero flag\cr
sf & Sign flag\cr
tf & Trace (single-step) flag\cr
if & Interrupt-enable flag\cr
df & Direction flag\cr
of & Overflow flag\cr}}
\medskip

\Command{fork}
\Abbreviated{fo}
\Example\(fork my_function(1, 2, 3)\)
\Example\(fork { while (1) { ... } }\)
\Description Creates a new thread, which runs evaluating the
expression given.  The current values of SOTL local
variables are copied for the new thread, so you can use
locals variables inside the expression.  The thread
begins life runnable and unfrozen, and will start to run
immediately; the current thread effectively ``blocks'', but
will run again once the forked thread blocks or exits.
This operator returns the thread ID of the new thread.

\Command{format}
\Example\($mystr = format "X is ", %b x, " (decimal ", %d x, ")"\)
\Description Formats SOTEST objects for output.  It is exactly like
\(print\), except that instead of writing the result to
standard output, it returns the result as a string.  No
newline is added to the string.  See \(print\) below for
more information.

\Command{getthreadid}
\Description Returns the thread ID of the current thread as a dword.

\Command{go}
\Abbreviated{g}
\Example\(go cs:ip+12\)
\Description Unfreezes all frozen threads and then blocks until an
event is received.  At that point, it will print out the
state of the current machines just like the machinelist
operator.  With no arguments, it will never return a
value; the thread running it will block until it is
killed.  It is usually used from top-level, indicating
that the user is ready to proceed with execution of
background threads and the machines.  It is not usually
used from threads; blockuntil is more common, because it
doesn't have the side effects of unfreezing other threads
and printing out machine state.

\Command{global}
\Abbreviated{gl}
\Example\(global \x, \y\)
\Description Declares variables global without assigning them values.
(Actually, if the global variable doesn't already exist,
it creates it and assigns \(nil\).)  This is useful within
SOTL functions, because within a function an assignment
to an undefined variable causes the variable to be
created local.

\Command{heapalloc}
\Abbreviated{ha}
\Example\(heapalloc 12\)
\Description Allocates memory from the current machine's heap, and
returns its address.  The argument to heapalloc specifies
the size of the allocation.  There is no way to free
memory allocated in this way, other than redefining the
heap.

\Command{heapdefine}
\Abbreviated{hd}
\Example\(heapdefine 0xf000:0, 0x1000\)
\Description Defines a range of memory for use as a heap.  Typically,
this will be memory that the target never uses.

\Command{historysize}
\Abbreviated{hs}
\Example\(historysize 40\)
\Description Sets the number of history records SOTEST keeps, or, with
an argument of 0, cancels history recording.  If history
recording is on, SOTEST keeps records of when memory is
read or written, when ports are read or written, when
instructions are fetched for execution, and when control
is transferred from one point in the program to another.
These records can be displayed with the \(printhistory\)
command below.

\Command{inbyte}
\Abbreviated{ib}
\Example\(inbyte 0x60\)
\Description Reads a byte from a port.  Although this command does
generate a port read event, the thread subscribing to it
will not receive it at least until after the \(inbyte\)
operator finishes; thus, in general you will get the
value last read from that port as opposed to any value
that thread may supply.  The value read is returned;
thus, to see the value read from a port, do something
like

\(print %b inbyte 0x1234\)

\Command{interrupt}
\Abbreviated{in}
\Example\(interrupt 0x38\)
\Description Generates an interrupt.  If the vector type is not a
hardware interrupt vector type, this blocks until the
current machine's interrupt flag is set and then
generates an interrupt of the given vector type, just as
if the machine had just executed an \(INT\) instruction.  If
the vector is a hardware vector, the interrupt is
scheduled through the simulated interrupt controller, and the
operator returns immediately.

\Command{inctimer}
\Abbreviated{it}
\Example\(inctimer 1\)
\Description Advances the timer with the given number, as if it had
received a strobe on its external clock line.  This may
generate an interrupt; if so, the interrupt is scheduled
through the interrupt controller.

\Command{inword}
\Abbreviated{iw}
\Description Just like inbyte, except it reads a word from the port.

\Command{length}
\Example\(length "foo"\)
\Description Returns the length of its argument.  If the argument is a
string, this is the number of characters in the string.
If the argument is a block, this is the number of bytes
in the block.  If the argument is an array, this is the
number of elements in the array (one more than the
array's highest index.)

\Command{load}
\Abbreviated{l}
\Example\(load "test.abs"\)
\Description Loads an absolute object file into the current machine,
and processes its debugging information.

\Command{local}
\Abbreviated{lo}
\Example\(local x, y\)
\Description Declares the named variables local.  If the variables do
not already exist locally, they are created and \(nil\) is
assigned to them.  Even though variables are created
locally by default, it is still a good habit to always
use local to declare variables.  The reason is that if a
variable exists globally, the first assignment to that
variable in your function will not create the variable
locally as you might expect, but rather will assign to
the global variable.

\Command{machine}
\Abbreviated{m}
\Example\(machine Processor2\)
\Description Sets the current function's notion of the current machine
to the machine given as its argument.  Once this command
is issued, operators which operate on machines ({\it i.e.,}
most operators, {\it e.g.,} \(enterbyte\) and \(memoryfetch\)) will
operate on the given machine.  The old current machine is
restored when the function exits.

\Command{machinecreate}
\Abbreviated{mc}
\Description Takes no arguments.  It creates a new machine, allocates
memory to simulate target memory and ports, and sets the
current machine to the new machine.  Once a machine is
created, there is no way to destroy it except by quitting
SOTEST.

\Command{machineidle}
\Abbreviated{mi}
\Description Declares the current machine idle, sending events to
threads waiting for the machine to go idle.  It takes an
optional argument that identifies the machine's idle
point; the machine remains idle as long as \(CS:IP\) is equal
to this idle point.  If the idle point is omitted, then
the current value of \(CS:IP\) is used.  The typical way to
use \(machineidle\) is to create an idle-detecting thread as
follows:

\code
fork {
while (1) {
blockuntil _idle_task;
machineidle _idle_task;
}
};
\code

If you do not specify the idle point, it is possible that
the idle-detecting thread will unblock at precisely the
same time as a thread that generates an interrupt on the
machine.  In that case, you may inadvertently declare the
machine idle at the start of the interrupt handler.
Thus, it is a good habit to always explicitly specify the
idle point.

SOTEST keeps track of the amount of time that elapses
with the machine declared idle.  You can use this to
measure the loadware's percent CPU utilization.  The
\(printclock\) operator will display the utilization.

\Command{machinelist}
\Abbreviated{ml}
\Description Prints the state of each machine: its name, the values of
its registers and flags, and whether or not the machine
is idle.

\Command{machinename}
\Abbreviated{mn}
\Example\(machinename Processor1\)
\Description Changes the name of the current machine to the name
given.  The name given must not already be in use.

\Command{mapPCB}
\Abbreviated{mp}
\Example\(mapPCB 0x8000:0\)
\Description Memory-maps the 80186 peripheral control block (PCB) at
the given addres.  Normally, the PCB is port-mapped at
port \(0xff00\).

\Command{memoryfetch}
\Abbreviated{mf}
\Example\($foo = memoryfetch [0x1234h:0x5678h, 10]\)
\Description Takes a block as an argument.  It reads the bytes from
the block, generating memory read events, and assembles
them into a string, which it returns.  Note that this is
not a particularly convenient way to view the contents of
a block; you are better off using \(dump\) or \(print\).

\Command{messagesend}
\Abbreviated{ms}
\Example\(messagesend $thread, "hello there"\)
\Description Sends a message to a thread.  The first argument is a
thread ID number, usually the return value of fork.  The
second argument is the message, which may be any SOTL
object; typically, dwords, strings, or arrays are sent.
If the thread specified does not exist, or is not
subscribed to \(messagereceive\) events, the message is
dropped and a false value is returned; otherwise, a true
value is returned.

\Command{microseconds}
\Example\(microseconds 0:1.0             \yields(1000000)\)
\Description Converts a time value a dword, which is the number of
microseconds (rounded down) that the time value
represents.  If its argument is a dword, it is
interpreted as a number of ticks; {\it i.e.,}

\code
microseconds $foo
\code

is equivalent to

\code
microseconds 0:0.$foo
\code

The exact operation performed depends on how fast your
processor is.  For a 16 MHz processor, the operation is
(more or less) a simple divide by 16.

\Command{outbyte}
\Abbreviated{ob}
\Example\(outbyte 0xff3e, 0\)
\Description Sends a byte to a port, and generates a port write event.

\Command{outword}
\Abbreviated{ow}
\Description Sends a word to a port, and generates a port write event.

\Command{pack}
\Abbreviated{pk}
\Example\(pack 0x100:0, "CSL", 10, 1000, 10000000\)
\Example\($packet = pack "nN", 1000, 10000000\)
\Description Stores dwords in sophisticated ways.  Pack has two forms.
In the first form, the first argument is a dword, and it
indicates a target address.  The second argument, called
the control string, is a string indicating how to store
the remaining arguments, in the spirit of \(printf\).  The
remaining arguments are dwords to be stored.  The return
value is the address where pack stopped; that is, the
number of bytes written can be calculated as follows:

\code
$end = pack $addr, "v??V", 300, 123456789;
$numpacked = $end - $addr;
\code

Each character in the control string explains what to do
with the next dword to be packed.  For example, \(c\) means
to interpret the dword as a \(signed char\); one byte is
stored at the current address, and the address is bumped
up by one.  \(N\) means to interpret the dword as an
\(unsigned long\), and pack it as four bytes in network
(big-endian) byte order, most significant byte first.

{\singlespace\halign{\hskip 0.75in{\tt #}\quad\hfil&#\hfil\cr
c&signed character\cr
C&unsigned character\cr
s&signed short (target byte order)\cr
S&unsigned short (target byte order)\cr
i&signed int\cr
I&unsigned int\cr
l&signed long (target byte order)\cr
L&unsigned long (target byte order)\cr
v&unsigned short, Vax (little-endian) byte order\cr
V&unsigned long, Vax (little-endian) byte order\cr
n&unsigned short, network byte order\cr
N&unsigned long, network byte order\cr
x&don't take an argument; pack a null (0) byte\cr
?&don't take an argument; skip forward a byte\cr
X&don't take an argument; back up a byte\cr
p&pack the next argument according to target alignment constraints\cr
P&pack the next argument according to host alignment constraints\cr}}
\medskip

In these examples, address 0 is used with pack, and the
results shown are the bytes stored at address 0 after the
pack.

\code
pack 0, "CCC", 1, 2, 3       \smallyields(01 02 03)
pack 0, "S", 1234h           \smallyields(34 12)
pack 0, "SL", 0102h, 010203h \smallyields(02 01 03 02 01 00)
pack 0, "cxi", 100, 1000     \smallyields(64 00 E8 03)
pack 0, "cxv", 100, 1000     \smallyields(64 00 E8 03)
pack 0, "cxn", 100, 1000     \smallyields(64 00 03 E8)
pack 0, "cXc", 100, 7        \smallyields(07)
\code

In the second form of pack, the address is omitted, the
first argument is the control string, and the remaining
arguments are dwords to be stored.  In this case, a
string is created containing pack's result and target
memory is unchanged.  Typical uses for this form include
future storage with enterbyte, display with print, and
message passing.

\code
$mystring = pack "xxxx";    \yields(string of 4 nulls)
pack "CC", 104, 105         \yields("hi")
\code

You may notice a redundancy: the first form of pack can
be accomplished with the second form of pack and
enterbyte.  That is,

\code
pack $addr, "...", ...
\code

is equivalent to

\code
enterbyte $addr, pack "...", ...
\code

\Command{print}
\Abbreviated{p}
\Example\(print "N is ", %b n, "!"\)
\Description Displays SOTL and target data in a user-readable form.
The arguments are SOTL expressions, optionally preceeded
by a format specifier.  The format specifiers are:

{\singlespace\halign{\hskip 1in{\tt\%#}\quad\hfil&#\hfil\cr
d&Format as signed decimal\cr
u&Format as unsigned decimal\cr
b&Format as array of hex bytes (chars)\cr
w&Format as array of hex words (shorts)\cr
l&Format as array of hex dwords (longs)\cr
p&Format as array of pointers to target memory\cr
s&Format as source code location\cr}}

How an object displays depends on the type of the object
and the format specifier.  Dwords normally display as
signed decimal, but can be displayed in hex by using \(%b\),
\(%w\), or \(%l\), or as a pointer with \(%p\), or as a source code
location with \(%s\):

\code
print %b 100        \yields(64)
print %p 5ec2h:14   \yields(5EC2:000E _idle idle:168)
print %s 5ec2h:14   \yields(5EC2:000E _idle idle:168)
\code

The difference between the second and third example is
that in the third example, in addition to printing the
location, SOTEST sends a message to the SOTEST front end
to display the source code at the given location.

By default, blocks display as $[address , size]$, but can
be displayed much more interestingly with format
specifiers.  In general, using a format specifier causes
display of the contents of the memory to which the block
refers.  No memory read events will be generated when the
memory is displayed.  Examples should make this clear:

\code
enterbyte 1, 1, 2, 3, 4, 5, 6, 7, 8;

x=[1,8]; print x    \yields([0000:0001, 8])
print %b x          \yields(01 02 03 04 05 06 07 08)
print %w x          \yields(0201 0403 0605 0807)
print %l x          \yields(04030201 08070605)
\code

By default, references to target data object display
symbolically; for example, a printing a reference to a
structure displays its fields and their values.  You can
control the number of array elements that will be
displayed by setting the magic global variable
\($MaxArrayElems\).

If you use \(%b\), \(%w\), or \(%l\), the target object will be
displayed as an array of hex bytes, words, or dwords;
since SOTL knows the size of the target object, it knows
how many numbers to print.  No memory read events will be
generated when target data objects are displayed.

By default, strings are printed in ASCII.  However,
strings can be formatted as arrays with \(%b\), \(%w\), or \(%l\):

\code
print "foo ", %b "foo " \yields(foo 66 6F 6F 20)
\code

Other data types format very simply, and ignore their
format specifier.  For example:

\code
machinename FooMachine
print FooMachine        \yields(<Machine FooMachine>)
\code

\Command{printsegments}
\Description Dumps the segment definitions for the current machine.
Segment names, classes, addresses, and sizes are
displayed. This is basically the same information as you
find in the linker's map file.

\Command{printclock}
\Abbreviated{pc}
\Description Prints the value of the clock ({\it i.e.,} the number of 80186
clock cycles since SOTEST started), how much of that time
was spent with the processor declared idle (see the
\(machineidle\) operator), the amount of host CPU time used
by SOTEST, and a comment about SOTEST's performance.

\Command{printdma}
\Abbreviated{pd}
\Description Prints the state of the 80186 DMA controller.  For each
channel, it prints the source and destination pointer,
the synchronization type, the status of the DMA request
lines (DRQ0 and DRQ1), and other miscellany about the
channel.  Use the \(dmarequest\) operator to manipulate the
DMA request lines.

\Command{printframe}
\Abbreviated{pf}
\Description Prints the current stack frame.  This is avaiable only if
you have compiled with debugging information.  It
displays the values of all parameters and local
variables, and displays the return address and current
execution address for the frame.

\Command{printhistory}
\Abbreviated{ph}
\Example\(printhistory 15\)
\Description Prints recent history records.  If an argument is
specified, only that many are printed; otherwise, all
records are printed.  Records are printed from oldest to
most recent.  The \(historysize\) command must be issued
first, to specify how many history records to keep.

\Command{printinterrupts}
\Abbreviated{pi}
\Description Prints the state of the 80186 interrupt controller.  For
each interrupt, it shows the address of its interrupt
procedure, whether the interrupt is masked, pending, or
in service, and the interrupt's priority.

\Command{printstack}
\Abbreviated{ps}
\Description Crawls the 80186 stack, hoping that every procedure is a
far procedure.  This is available even without debugging
information.  It attempts to print the return addresses
of procedures, their locals, and their parameters, but
without type information and local variable information
the rendition is ugly at best.  However, if you're stuck
without debugging information, it's better than nothing!

\Command{printtimers}
\Abbreviated{pt}
\Description Prints the state of the 80186 timer block.  For each
timer, it prints its value, whether it is enabled, whether
it is signalled internally or externally, and value of its
thresholds.

\Command{processor}
\Abbreviated{pr}
\Description Configures the current machine's microprocessor.  The
first argument is a subcommand name; the remaining
argument depends on the subcommand.  Subcommands are:

{\singlespace \halign{\tt #\hfil\quad&#\hfil\cr
I80186 &      The current machine is an 80186.  No more arguments.\cr
I80188 &      The current machine is an 80188. No more arguments.\cr
clockspeed &  Sets the current machine's clock speed to the given \cr
& value, in ticks per second.\cr
waitstates &  Sets the number of wait states required for memory\cr
& access.  Each wait state is one clock tick.\cr
info &        Displays the configuration of the current machine's
processor.\cr
}}
\medskip

Examples:

\code
processor I80186;
processor I80188;
processor clockspeed, 16000000;    # 16 megaherz
processor waitstates, 4;           # 4 wait states
processor info;
\code

\Command{random}
\Example\(random 10\)
\Description Returns a random number.  If an argument is given, the
number returned will be between 0 and its argument minus
one; e.g, random 10 returns a number from 0 to 9.  If
not, the random number will be between 0 and $2^{32} - 1$.

\Command{readline}
\Example\($line = readline $filedesc;\)
\Example\($userinput = readline;\)
\Description Returns a string read from a file.  If a file descriptor
is specified, the line is read from that file
inefficiently, using lots of \(read\)(2) system calls, one
character at a time.  If a newline is hit, it terminates
the line but is not included in the string read.  If \(EOF\)
is hit, it terminates a non-empty line.  If \(EOF\) is hit at
the beginning of the line, the value \(nil\) is
returned.

If no file descriptor is given to \(readline\), the line is
read using \(stdio\)'s \(fgets\)(3) from SOTEST's standard input
(not the file being read by \(<\)).  The string is
returned, unless \(fgets\)(3) returns \(NULL\), in which case the
\(nil\) is returned.

\Command{reassigndebsym}
\Example\(reassigndebsym 0x40e2, DFE_CODE\)
\Example\(reassigndebsym _dfe_intr_ul\)
\Description This unfortunate command exists to work around a bug in
SOTEST.  SOTEST is not always able to correctly associate
debugging information with its corresponding code
segment.  If there's a public procedure \(foo\) which
should, but doesn't seem to, have debugging information,
try this:

\code
print &foo;
print _foo;
\code

You will see two addresses.  If they have the same offset
but different segments, then the reason that \(foo\)
doesn't seem to have debugging information associated
with it is because of SOTEST's bug. To work around this
bug, merely type

\code
reassigndebsym _foo;
\code

\noindent    and all should be well.  If it isn't, here's another much
more involved strategy.  First, you will need to find the
DEBSYM segment which actually contains the debugging
information for \(foo\) (the \(printsegments\) and 
\(print %p search\) commands can help you).  You also need to know
the name of the segment in which \(foo\) is located (use
\(printsegments\) and \(print %p _foo\) to find out).  When
you find the segment address of the \(DEBSYM\) segment, and
the name of the code segment, do

\code    
reassigndebsym debsym-segment-address, code-segment-name
\code

\noindent             as in

\code    
reassigndebsym 0x44e2, MY_CODE
\code

\noindent             Then the test

\code    
print &foo;
print %p _foo;
\code

\noindent             should print the same exact address twice.

\Command{register}
\Abbreviated{r}
\Example\(r cs:ip = 0x1000:0x2000\)
\Description Displays or sets registers on the current machine.  With
no argument, the registers and flags are displayed.  The
argument can be in the form $reg=value$ or
$reg:reg=value$.  In the first case, the given register
is set to the given value.  In the second case, the first
register is set to the segment portion (upper 16 bits) of
the given value, and the second register is set to the
offset portion.

\Command{return}
\Example\(return "hello"\)
\Description Exits the current SOTL function, returning the given
value.

\Command{search}
\Abbreviated{s}
\Example\(search _start, _end, 10, 20, 30\)
\Description Searches the given range of memory for the given sequence
of bytes, returning the first address where the sequence
was found.  It does not generate read events for any
memory read.

\Command{srandom}
\Example\(srandom 123\)
\Description Seeds the random number generator.  With an argument, the
argument is used as the seed.  Without an argument, the
current system time is used as the seed.

\Command{string}
\Example\(string 10, "hello", 0xff, 0, [_my_data, 20]\)
\Description Constructs a string out of a list of arguments.  The
arguments may either be dwords, strings, or blocks.
Dwords are converted to strings of length one, whose
single byte is the least significant byte of the given
dword.  Blocks are converted to strings whose bytes are
the bytes that make up the block (no memory read events
are generated).  Then the whole list is concatenated
together.

\code    
print %b string 10, "abc", 0     \smallyields(0A 61 62 63 00)
print string "hi", 32, "there"   \smallyields(hi there)
\code

\Command{stringvalue}
\Example\(stringvalue "A43", 16\)
\Description Converts from a string to a dword.  An optional second
dword argument is the base, which defaults to decimal.
\(0x...\) and \(...h\) syntax are not recognized.

\Command{substr}
\Example\(substr "hello there", 3, 2            \yields("lo")\)
\Description Extracts a portion of a string.  The second argument is
the starting position (0 is the first character); the
third argument is optional, and is the number of
characters to extract.  If omitted, characters up to the
end of the string are extracted.

\Command{sourcedir}
\Abbreviated{sd}
\Example\(sourcedir "/build/mysources:/tmp:."\)
\Description Specifies the directories that SOTEST will look in when
trying to find source files.  It takes a single argument
which must be a string; it is a colon-separated list of
pathnames similar to the \(PATH\) environment variable.  When
SOTEST locates a point in your source code, it will
search the directories you specify here to find your
source file and tell the SOTEST front end to display it.
If you don't use a front end, then your source is never
displayed; see the section below on SOTEST front ends for
more information.

The \(sourcedir\) operator returns the source directory
list as a string, so the current source director list can
be displayed with the command

\code    
print sourcedir
\code

\Command{threaddebug}
\Abbreviated{td}
\Description Puts a thread in debug mode.  Such threads will be frozen
when the user gains control; they will continue to queue
events, but they will be processed only when the user
unfreezes the thread (either explicitly with
\(threadunfreeze\) or by using the \(go\) command).  A
misbehaving ({\it i.e.,} continuously-running) thread not in
debug mode will keep the user from being able to do
anything, but when in debug mode the user will be able to
regain control with control-C.  When a thread in debug
mode receives an event, a warning message is printed.

\Command{threadexamine}
\Abbreviated{te}
\Example\(threadexamine getthreadid\)
\Description Displays a considerable amount of information about the
given thread.  This is often useful for debugging SOTL
programs.

\Command{threadlist}
\Abbreviated{tl}
\Description Lists all threads, their thread ID, their state, whether
or not they're frozen, whether or not they have events
queued, their name, and where they were started from.
You can get more information about a thread by with the
command \(threadexamine\).

\Command{threadcont}
\Abbreviated{tc 12}
\Description Continues a thread that has been stopped by \(threadstop\).

\Command{threadkill}
\Abbreviated{tk}
\Example\(threadkill 10, 11, getthreadid\)
\Description Destroys a thread.  Without an argument, destroys the
current thread.

\Command{threadstop}
\Abbreviated{ts}
\Example\(threadstop $my_thread\)
\Description Stops a thread.  Without an argument, stops the current
thread.  Only a running thread can be stopped.  When a
thread is stopped, it cannot run and events for it will
be queued.  The only to resume a stopped thread is to
issue the \(threadcont\) command.

\Command{threadunfreeze}
\Abbreviated{tu}
\Description Unfreezes the given thread.  This is useful for
debugging.  The user may interrupt the system, do
something generating an event, inspect the state of the
(presumably frozen) thread that is supposed to handle the
event, and then manually unfreeze the thread while
leaving other threads frozen, to prevent side effects.
The user can then list the threads and find out which
threads have events, and dump the relevant threads to
find out what's going on.

\Command{trace}
\Abbreviated{t}
\Example\(trace 10\)
\Description Steps through the target program until the current source
line number changes.  If an argument is given, it is used
as a repeat count.  If line number information is not
available, it pretends the line number changes each
instruction.

\Command{traceforward}
\Abbreviated{tf}
\Description Steps through the target program until the current source
line number increases --- that is, it stops when \(CS:IP\)
reaches a point in the same file but a larger line
number.  This is useful at the end of loops, to continue
until the loop ends.  However, it is fooled if the loop
calls a procedure which is later in the same file.  Its
argument, if supplied, is used as a repeat count.

\Command{traceinstruction}
\Abbreviated{ti}
\Description Steps forward a single assembly language instruction. If
an argument is given, it is used as a repeat count.

\Command{traceprocedure}
\Abbreviated{tp}
\Description Steps forward until a procedure call or software
interrupt call is found.  Then it sets a breakpoint at
the point where the call returns, and blocks.

\Command{unassemble}
\Abbreviated{u}
\Example\(u _main\)
\Description Unassembles code at the given address

\Command{unix}
\Description Issue a UNIX system call.  Several system calls are
supported, and are described individually below.

\Command{unpack}
\Abbreviated{un}
\Example\(unpack ds:bx, "CSL", $foo, $bar, $baz\)
\Example\(unpack $packet, "nN", $code, $address\)
\Description Performs the reverse of \(pack\).  It has two forms.  The
first form takes a memory address, a \(pack\) control string,
and arguments (which must be lvalues).  The bytes at the
address are read from memory, interpreted according to
the letters in the control string, and stored in the
corresponding arguments.  The return value is the address
just following the last byte read by \(unpack\).  Memory read
events are generated for locations read.

The second form takes a string as its first argument.  It
unpacks the bytes in the string, rather than bytes in
target memory.  It returns the number of bytes used,
which is also the index into the string just past the
last byte used.

\Command{up}
\Description Performs the reverse of \(down\).  It climbs up one stack
frame, to the current frame's caller, and displays the
frame.

\Command{varlist}
\Abbreviated{vl}
\Description Lists all global variables, and displays their values.

\Command{warnings}
\Abbreviated{w}
\Description Lists the supported warnings, and whether they are
enabled or disabled for the current machine.

\Command{warncontrol}
\Abbreviated{wc}
\Description Toggles whether or not the user is warned when the
current machine undergoes a control transfer (a procedure
call or return, and interrupt call or return, or a long
jump.)  This usually produces lots and lots of warnings,
but used judiciously can be helpful to pinpoint where
code runs foul.  If an argument is specified, it is
interpreted as a boolean; a true value enables the
warning, and a false value disables it.

\Command{warndma}
\Abbreviated{wd}
\Description Toggles whether or not the user is warned when the
current machine's DMA controller performs a DMA
operation.  If an argument is specified, it is
interpreted as a boolean; a true value enables the
warning, and a false value disables it.

\Command{warnevents}
\Abbreviated{we}
\Description Toggles whether or not the user is warned when a thread
is sent an event.  If an argument is specified, it is
interpreted as a boolean; a true value enables the
warning, and a false value disables it.  This warning is
especially useful for debugging threads.  Trace complete
events are never displayed, even if this warning is
enabled, because they are considered completely
uninteresting.

\Command{warninterrupts}
\Abbreviated{wi}
\Description Toggles whether or not the user is warned when hardware
interrupts are requested and serviced.  Like \(warncontrol\),
it accepts an optional boolean argument explicitly
enabling or disabling the warning.

\Command{when}
\Example\(when memorywrite(_myvar) { print "YOW!"; }\)
\Description Takes an event specification list followed by a block of
commands in curly braces.  It forks a thread (returning
its thread ID) that is blocked until an event matching
the specification is received.  At that point, the
commands in the braces are executed and the thread exits.
The command

\code    
when 0:0.100000 { print "It's time"; }
\code

\noindent             is actually syntactic sugar for

\code    
fork { blockuntil 0:0.100000; print "It's time"; }
\code

\Command{whenever}
\Example\(whenever memorywrite(_myvar) { print "YOW!"; }\)

\Description Takes an event specification list followed by a block of
commands in curly braces.  It forks a thread (returning
its thread ID) that is in an infinite loop, blocking
until an event matching the specification is received.
At that point, the commands in the braces are executed
and the thread blocks again.  The command

\code    
whenever _my_proc { print "_my_proc called!"; }
\code

\noindent             is actually syntactic sugar for

\code    
fork {
while (1) {
blockuntil _my_proc;
print "_my_proc called!";
}
}
\code

Note that any expressions you put in the event
specification list are evaluated in the context of the
new thread, and are re-evaluated every time around the
loop.  Thus, code like

\code
whenever .+2 { ... }
\code

\noindent             may not do what you expect (the breakpoint will be set in
a different place each time around the loop.)

\Command{<}
\Example\(< myfile.sot\)
\Description This is not actually a command operator.  It directs
SOTEST to read commands from the named file in the spirit
of \(#include\).  Note that the filename is a literal, not a
string expression; the name is not in quotes, and string
operators are not allowed.

\leftskip=0pt

\section{Events, Event Specifications, Event Predicates}

SOTEST supports 16 event types. Of these, five are used internally and
are never seen by the user or SOTL code.  There are 11 others that
threads (or the user) may subscribe to, receive, display, and act on.
These visible event types are target memory read, memory write, port
read, port write, breakpoint, breaktime, idle machine, interthread
message receive, thread exit, UNIX file descriptor ready, and UNIX
message queue readable.  The internal event types are command start,
fork, target call return, trace complete, and interrupts allowed.

The user tells SOTEST what events are interesting by providing event
specifications.  The \(break\) operator subscribes the user to the given
event specifications; when an event matching one of the specifications
is received, the user is notified and simulation is suspended.  The
\(blockuntil\) operator deletes the thread's old subscriptions,
subscribes the thread to the given event specifications, and blocks
the thread; when an event is received, the thread unblocks.  The \(go\)
operator is like \(blockuntil\), but is meant for use by the foreground
thread; in addition to subscribing the thread to the given
specifications and blocking the thread, it unfreezes all frozen
threads and prints machine state when an event is received.

When \(blockuntil\) (or \(go\)) returns, there is an event waiting for the
thread.  The thread can find out what sort of event it is with event
predicates.  Event predicates are actually like command operators, and
can be used inside expressions just like command operators.  There is
one event predicate per event type.  Each event predicate returns true
if the event is of the given type, and false if it's not.  If the
event is of the given type, details of the event will be written into
the arguments given to the event predicate.

\subsection{Event Types}

The event types listed above are described here.

\leftskip=0.5in

\Type{memoryread}
\Details{address, size}
\Meaning This event is generated whenever a machine reads a memory
location.  It is also generated by certain command operators,
such as \(memoryfetch\), as described above.  The address of the
memory location read and the size of the read (1 for a byte
read, 2 for a word read) are included in a \(memoryread\) event.

\Type{memorywrite}
\Details{address, value, size}
\Meaning This event is generated whenever a machine writes to target
memory.  It is also generated by certain command operators,
such as \(enterbyte\), as described above.  The address of the
memory location written, the value written there, and the
size of the write (1 for a byte write, 2 for a word write)
are included in a \(memorywrite\) event.

\Type{portread}
\Details{port, size}
\Meaning This event is generated whenever a machine reads a target I/O
port.  It is also generated by certain command operators,
such as \(inbyte\), as described above.  The address of the port
read and the size of the read (1 for a byte read, 2 for a
word read) are included in a \(portread\) event.

\Type{portwrite}
\Details{port, value, size}
\Meaning This event is generated whenever a machine writes a target
I/O port.  It is also generated by certain command operators,
such as \(outbyte\), as described above.  The address of the port
written and the size of the write (1 for a byte write, 2 for
a word write) are included in a \(portwrite\) event.

\Type{breakpoint}
\Details{address}
\Meaning This event is generated when the machine starts to execute an
instruction.  The current value of \(CS:IP\) is included in the
event.

\Type{breaktime}
\Details{time}
\Meaning This event is generated when the machine's clock goes past a
certain value.  The current value of the clock is included in
the event.

\Type{idlemachine}
\Details{machine}
\Meaning This event is generated when a machine is declared idle by
the \(machineidle\) command.  The machine declared idle is
included in the event.

\Type{messagereceive}
\Details{sender, message}
\Meaning This event is generated when a thread sends another thread a
message.  The thread ID of the sender, and the contents of
the message, are included in the event.

\Type{threadexit}
\Details{thread ID, exit value}
\Meaning This event is generated when a thread exits.  The thread's ID
and the result of the thread's last evaluation are included
in this event.

\Type{filedescriptor}
\Details{unix file descriptor}
\Meaning This event is generated when a file descriptor is ``ready.''
For a file descriptor receiving connections with unix
\(listen\)(), this means a connection has been initiated.  For
other file descriptors, it means the descriptor is readable.
There is no way to be notified when a descriptor is writable;
an attempt to write a full pipe causes then entire SOTEST
process to block.

\Type{messagequeue}
\Details{unix message queue ID}
\Meaning This event is generated when a message queue has messages in
it.  The message queue ID is included in the event.

\Type{command {\it (internal event type)}}
\Details{none}
\Meaning This event is sent to a thread when it is forked as a user
command, causing it to assume the role of the foreground
thread.  It is never visible to the user.

\Type{fork {\it (internal event type)}}
\Details{parent thread ID}
\Meaning This event is sent to a thread when it is forked from another
thread.

\Type{callreturn {\it (internal event type)}}
\Details{call return value}
\Meaning This event is generated when a target procedure call
(initiated by the \(call\) command) returns.  \(call\) causes the
thread to block; this event is sent to make it unblock.  The
return value of the target call is included in the event, and
becomes the return value of the \(call\) command.  This event is
never visible to the user.

\Type{tracecomplete {\it (internal event type)}}
\Details{none}
\Meaning This event is generated when a target single-step (trace
instruction) operation completes.  All trace commands
actually cause the thread to block momentarily; this event
unblocks the thread.  It is never visible to the user.

\Type{interruptsallowed {\it (internal event type)}}
\Details{none}
\Meaning This event is generated when the target goes into a state in
which hardware-requested interrupts can be serviced, {\it i.e.,}
the interrupt flag is set.  It is used only by the \(interrupt\)
command operator above.

\leftskip=0pt

\subsection{Event Specifications}

Event specifications can be dwords, time values, file descriptors, or
message queue ID's.  A dword is a specifier for a breakpoint; a
\(breakpoint\) event will be received when execution reaches the address
indicated by the dword.  A time value is a specifier for a breaktime;
a \(breaktime\) event will be received when the clock reaches the given
time value.  A file descriptor is a specifier for \(filedescriptor\)
events involving the given file descriptor; when the given file
descriptor becomes readable or has a connection requested, an event
will be received.  A message queue ID is a specifier for \(messagequeue\)
events; a \(messagequeue\) event will be generated when a message is
waiting in the given event queue.

\leftskip=0.5in

\Example\(blockuntil _my_func, 0:0.12345, $descriptor\)
\Meaning The current thread will block until either \(CS:IP\) reaches
\(_my_func\), the clock reaches 12345 ticks, or the file
descriptor stored in \($descriptor\) is ready.

\leftskip=0in

\subsection{Event Specification Constructors}

Only specifiers for those four event types (\(breakpoint\), \(breaktime\),
\(filedescriptor\), and \(messagequeue\)) can be created with SOTL objects.
Specifiers for all user-visible event types can be created by event
specification constructors.  There is one such constructor for each
user-visible event type.  In each case the constructor has the same
name as the event type.

Event specification constructors are allowed only immediately
following \(break\), \(blockuntil\), or \(go\).  Event specifications are
not themselves SOTL objects, and cannot be stored in variables or
passed as arguments to SOTL functions.

\leftskip=0.5in

\Constructor{memoryread}
\Example\(blockuntil memoryread (_my_data, _my_data + 20)\)
\Description Constructs a specifier for memory read events from
addresses from \(_my_data\) to \(_my_data + 19\), inclusive.  If
the constructor is given only one argument, a specifier
for memory reads from that address alone is constructed;
thus, \(memoryread(x)\) is equivalent to \(memoryread(x, x+1)\).

\Constructor{memorywrite}
\Example\(go memorywrite (_my_data, my_data + 20)\)
\Description Like \(memoryread\), but for memory write events

\Constructor{portread}
\Example\(break portread (0x3f0, 0x3f8)\)
\Description Like \(memorywrite\), but for port read events

\Constructor{portwrite}
\Example\(blockuntil portwrite (0x3f0, 0x3f8)\)
\Description Like \(memorywrite\), but for port write events

\Constructor{breakpoint}
\Example\(break breakpoint (_my_func)\)
\Description Constructs a specifier for breakpoint events at the given
address.  Note that breakpoint event specifiers can be
constructed more simply by simply providing the address;
this syntax is provided only for uniformity.  Thus, the
following forms are equivalent:

\code
blockuntil _my_func
blockuntil breakpoint(my_func)
\code

\Constructor{breaktime}
\Example\(go breaktime (01:26.00000000)\)
\Description Like \(breakpoint\), but for \(breaktime\) events.  It is
redundant in the same sense that \(breakpoint\) is.

\Constructor{idlemachine}
\Example\(blockuntil idlemachine (my_machine)\)
\Description Constructs a specifier for \(idlemachine\) events for the
given machine.  When the given machine is declared idle,
an \(idlemachine\) event will be received.  Note that
machines could be allowed as event specifiers, making
this event specification constructor redundant, but
currently they are not.

\Constructor{messagereceive}
\Example\(break messagereceive()\)
\Description Constructs a specifier for \(messagereceive\) events.  When
the current thread is sent a message by any other thread,
a \(messagereceive\) event will be received.  The
\(messagereceive\) event, of course, contains the mesasge
itself.

\Constructor{threadexit}
\Example\(blockuntil threadexit($my_child)\)
\Description Constructs a specifier for \(threadexit\) events.  When the
thread with the given ID exits, a \(threadexit\) event will
be received, containing the exited thread's ID and the
result of its final evaluation.

\Constructor{filedescriptor}
\Example\(go filedescriptor ($descriptor)\)
\Description Like breakpoint, but for \(filedescriptor\) events.  It is
redundant in the same sense that \(breakpoint\) is.

\Constructor{messagequeue}
\Example\(blockuntil messagequeue ($message_queue_ID)\)
\Description Like breakpoint, but for \(messagequeue\) events.  It is
redundant in the same sense that \(breakpoint\) is.

\leftskip=0pt

\subsection{Event Predicates}

When a thread unblocks after receiving an event, it needs some way to
find out what event was received and what its details were.  Event
predicates provide this mechanism.  Event predicates are command
operators that return true if the last event received matches the
pedicate, and false otherwise.  If the event matches, the details of
the event are written into the event predicate's arguments.  Like
event specification constructors, there is one event predicate per
user-visible event type.  Note that event predicates can not be used
anywhere in the arguments to \(break\), \(blockuntil\), or \(go\), because they
will be interpreted as event specification constructors.

\leftskip=0.5in

\Predicate{memoryread}
\Example\(if memoryread($address, $size)) { ... }\)
\Description Tests if the last event received was a \(memoryread\) event.
If so, it returns true and fills in its arguments with
the address and size read.  The size is 1 for a byte
read, or 2 for a word read.

\Predicate{memorywrite}
\Example\(if memorywrite($address, $value, $size) { ... }\)
\Description Tests if the last event received was a \(memorywrite\)
event.  If so, it returns true and fills in its arguments
with the address, value, and size written.  The size is 1
for a byte write, or 2 for a word write.

\Predicate{portread}
\Example\(if portread($port, $size)) { ... }\)
\Description Tests if the last event received was a \(portread\) event.
If so, it returns true and fills in its arguments with
the port and size read.  The size is 1 for a byte read,
or 2 for a word read.

\Predicate{portwrite}
\Example\(if portwrite($port, $value, $size) { ... }\)
\Description Tests if the last event received was a \(portwrite\) event.
If so, it returns true and fills in its arguments with
the port, value, and size written.  The size is 1 for a
byte write, or 2 for a word write.

\Predicate{breakpoint}
\Example\(if breakpoint($where) { ... }\)
\Description Tests if the last event received was a \(breakpoint\) event.
If so, the code location at which the breakpoint was hit
is written into this operator's only argument.

\Predicate{breaktime}
\Example\(if breaktime($when) { ... }\)
\Description Tests if the last event received was a \(breaktime\) event.
If so, the value of the clock when the breaktime event
was generated is written into this operator's only
argument.

\Predicate{idlemachine}
\Example\(if idlemachine($which_machine) { ... }\)
\Description Tests if the last event received was an \(idlemachine\)
event.  If so, the machine that went idle is written into
this operator's only argument.

\Predicate{messagereceive}
\Example\(if messagereceive ($from_whom, $message) { ... }\)
\Description Tests if the last event received was a \(messagereceive\)
event.  If so, the thread ID of the sender and the
message itself are written into this operator's
arguments.

\Predicate{threadexit}
\Example\(if threadexit ($who_died, $exit_value) { ... }\)
\Description Tests if the last event received was a \(threadexit\) event.
If so, the thread ID of the thread that exited and the
result of its final evaluation are written into this
operator's arguments.

\Predicate{filedescriptor}
\Example\(if filedescriptor ($mydesc) { ... }\)
\Description Tests if the last event received was a \(filedescriptor\)
event.  If so, the file descriptor that became ready is
written into this operator's argument.

\Predicate{messagequeue}
\Example\(if messagequeue ($thequeue) { ... }\)
\Description Tests if the last event received was a \(messagequeue\)
event.  If so, the message queue ID that has messages
waiting is written into this operator's argument.

\leftskip=0pt

\section{UNIX System Calls}

As mentioned above, several Unix system calls can be accessed via the
\(unix\) command operator.  They are described below.

\leftskip=0.5in

\SystemCall{unix accept ()}
\Example\($new_connection = unix accept ($fd)\)
\Description Performs the \(accept\)(2) system call.  It returns a new
file descriptor, or \(nil\) in case of error.

\SystemCall{unix bind ()}
\Example\(unix bind ($fd, $sockaddr)\)
\Description Performs the \(bind\)(2) system call.  The second argument
is a string specifying the socket address; the length of
the address is the length of the string.  It returns the
result of \(bind\)(2).

\SystemCall{unix connect ()}
\Example\(unix connect ($fd, $sockaddr)\)
\Description Performs the \(connect\)(2) system call.  The second argument
is a string specifying the socket address; the length of
the address is the length of the string.  It returns the
result of \(connect\)(2).

\SystemCall{unix errno ()}
\Example\($errcode = unix errno()\)
\Description Returns the current value of \(errno\) as a dword.

\SystemCall{unix getenv ()}
\Example\($homedir = unix getenv("HOME")\)
\Description Returns the value of the named environment variable as a
string, or \(nil\) if the variable is not set.

\SystemCall{unix listen ()}
\Example\(unix listen ($fd, 5)\)
\Description Performs the \(listen\)(2) system call.

\SystemCall{unix mkfifo ()}
\Example\(unix mkfifo ("/tmp/my_named_pipe")\)
\Description Performs the \(mkfifo\)(2) system call, using mode \(0666\).

\SystemCall{unix msgget ()}
\Example\($queue = unix msgget ($key)\)
\Description Performs the \(msgget\)(2) system call.  It passes
the key you provide (a dword), and \(IPC_CREAT | 0777\) for
flags.  Returns a message queue, or \(nil\) if it fails.

\SystemCall{unix msgsnd ()}
\Example\(unix msgsnd ($queue, pack("H", 200) . "hello")\)
\Description Sends a message to the given queue.  The first argument
is a message queue, as returned by \(msgget\).  The second
argument is a string representing a \(struct msgbuf\);
according to UNIX definitions (see \(msgsnd\)(2)), it
should be a host long (indicating the message type)
followed by data.  An optional third argument specifies
the length of the data portion of the message.  For
example,

\code
$type = pack("H", 300);
unix msgsnd ($queue, $type . "Test", 1)
\code

\noindent   sends a message of type 300, one character in length,
with that character being a `\(T\)'.

\SystemCall{unix msgrcv ()}
\Example\(unix msgrcv ($queue, $message, 1024, 200);\)
\Description Receives a message from the given queue.  The first
argument is the message queue, as returned by \(msgget\).
The second argument will have the message stored into it.
The third is the maximum size that will be received.  The
fourth argument specifies the type of message that may be
received, as in \(msgrcv\)(2).  0 means any type.

\SystemCall{unix open ()}
\Example\($descriptor = unix open ("/tmp/myfile", 1, 0x3ff)\)
\Description Opens the given file and returns a descriptor if it
succeeds, or \(nil\) otherwise.  The second and third
arguments are the flags and mode words, and default to 0.

\SystemCall{unix read ()}
\Example\(unix read ($descriptor, $result, $size)\)
\Description Reads from a file descriptor.  At most \($size\) bytes are
read, and are stored in the string \($result\).  If EOF is
hit, 0 is returned; if there is an error, -1 is returned;
and if the read is successful, the number of bytes read
is returned.

\SystemCall{unix recv ()}
\Example\(unix recv ($descriptor, $msg, 1024)\)
\Description Calls the unix \(recv\)(2) system call and returns its
result.  The data received is stored as a string in the
second argument; the third argument is the maximum number
of bytes to receive.

\SystemCall{unix recvfrom ()}
\Example\(unix recv ($descriptor, $msg, 1024, $sockaddr)\)
\Description Calls the unix \(recvfrom\)(2) system call and returns its
result.  The data received is stored as a string in the
second argument; the third argument is the maximum number
of bytes to receive.  The fourth is filled in with the
address from which the message was received.

\SystemCall{unix semctl ()}
\Example\(unix semctl ($semid, 0, $SETALL, pack("hhh", 1, 2, 3))\)
\Description Calls the unix \(semctl\)(2) system call and returns its
result.  The arguments are the semaphore set ID returned
by \(semget\), the semaphore number, a command, and an
argument.  The constants used as commands are not defined
for you; see \(<sys/sem.h>\).  If you pass \(GETALL\) or
\(IPC_STAT\), the fourth argument must be a variable which,
after successful completion of the \(semctl\)(2) call, will
hold the \(semval\)'s or \(struct semid_ds\) which the system
call fills in.  If you pass \(SETALL\) or \(IPC_SET\), the fourth
argument must be a string whose bytes make up an array of
\(semval\)'s or a \(struct semid_ds\); the \(pack\) operator is a good
way to generate such a string.

\SystemCall{unix semget ()}
\Example\(unix semget (1000, 10);\)
\Description Calls the unix \(semget\)(2) system call and returns its
result.  The arguments are the key for the semaphore set
and the number of semaphores in the set.  A flags value
of \(IPC_CREATE | 0777\) is passed as \(semget\)'s third
argument.

\SystemCall{unix semop ()}
\Example\(unix semop ($semid, 0, -2, 0, 1, 3, 0);\)
\Description Calls the unix \(semop\)(2) system call and returns its
result.  The first argument is a semaphore set ID.  The
remaining arguments are grouped into sets of three.  Each
set of three arguments makes up a semaphore operation,
corresponding to the fields of \(struct sembuf\).  Thus, the
above call subtracts 2 from semaphore 0 of the given set,
and adds three to semaphore 1 of the set.  (In each
operation, a flags value of 0 is used.)

\SystemCall{unix send ()}
\Example\(unix send ($descriptor, "Hello")\)
\Description Calls the unix \(send\)(2) system call and returns its result.
The third argument is the number of bytes to send, and
defaults to the length of the string.

\SystemCall{unix sendto ()}
\Example\(unix sendto ($descriptor, "Hello", $sockaddr)\)
\Description Calls the unix \(sendto\)(2) system call and returns its
result.  The final argument is the destination address.
If four arguments are given, the third argument is the
number of bytes to send, and defaults to the length of
the string.

\SystemCall{unix socket ()}
\Example\($descriptor = unix socket (PF_UNIX, SOCK_STREAM);\)
\Description Calls the unix \(socket\)(2) system call.  You may use the
symbolic constants \(PF_UNIX\) or \(PF_INET\) as the protocol
family, and \(SOCK_STREAM\) or \(SOCK_DGRAM\) as the type.  You
may also pass a dword for either argument.  The third
argument given to the unix \(socket()\) call is always zero.
In case of error, \(nil\) is returned; otherwise, the file
descriptor associated with the new socket is returned.


\SystemCall{unix sprintf ()}
\Example\($now = unix sprintf ("%03d %s", 10, "hello")\)
\Description Returns the output of the \(sprintf\) library function.  The
first argument must be a control string as described in
\(sprintf\)(3).  The remaining arguments are passed to
\(sprintf\).  If the argument is a string, a pointer to the
string's contents (which will be null-terminated) is
passed; otherwise, the argument is promoted to a dword
and passed like a long.  {\bf Warning:} if you do evil things,
like

\code
unix sprintf ("%s", 100);
\code

\noindent     you will lose; SOTEST will dump core and it's your fault!
(So there.)

\SystemCall{unix time ()}
\Example\($now = unix time ()\)
\Description Returns the number of seconds since midnight on the first
of January, 1970, in Greenwich Mean Time.

\SystemCall{unix unlink ()}
\Example\(unix unlink ("/tmp/myfile")\)
\Description Unlinks the given file.

\SystemCall{unix write ()}
\Example\(unix write ($descriptor, $data, $size)\)
\Description Writes bytes from the given string.  \($size\) is the number
of bytes, which is limited by (and defaults to) the
length of the string.  Returns the number of bytes
successfully written, or -1 for error.

\leftskip=0pt
