next up previous contents index
Next: 2.9.10 threaddict Up: 2.9 Dictionary reference Previous: 2.9.8 sprintsdict   Contents   Index


2.9.9 systemdict

The systemdict dictionary contains most of the operators that are of general use. Although there are no mechanisms that prevent modification of systemdict, programs should not normally need to modify systemdict, since globaldict provides a place for storing globally shared objects. All threads share the same systemdict, which is implicitly locked.

Table 2.10: systemdict summary by functional group
Input(s) Op/Proc/Var Output(s) Description
Operand stack operators
- mark mark Create a mark.
,,,obj aup obj ,,, Rotate stack up one position.
obj ,,, adn ,,,obj Rotate stack down one position.
- count count Get the number of objects on ostack.
mark ... counttomark mark ...count Get the depth of the topmost mark on ostack.
obj dup obj dup Duplicate an object.
obj ,,, bdup obj ,,,dup Duplicate bottom object.
objects count ndup objects objects Duplicate objects.
obj ...index idup obj ... dup Duplicate object on ostack at index.
...obj ,,,index ibdup ... obj ,,,dup Duplicate object on ostack at index from bottom.
a b tuck b a b Tuck duplicate of top object under second object.
a b under a a b Duplicate second object.
a b over a b a Duplicate second object.
a b exch b a Exchange top two objects.
a b c up c a b Roll top three objects up one.
a ...b count nup b a ... Roll count objects up one.
a b c dn b c a Roll top three objects down one.
a ...b count ndn ...b a Roll count objects down one.
...amount rot ... Rotate stack up by amount.
region count amount roll rolled Roll count objects up by amount.
obj pop - Remove object.
obj ,,, bpop ,,, Remove bottom object.
objects count npop - Remove count objects.
objects ...count nbpop ... Remove count objects from bottom.
obj ...index ipop ... Remove object at index.
...obj ,,,index ibpop ... ,,, Remove object at index from bottom.
a b nip b Remove second object.
objects clear - Pop all objects off ostack.
mark ... cleartomark - Remove objects from ostack through topmost mark.
- ostack stack Get a current ostack snapshot.
thread threadostack stack Get a reference to thread's ostack.
Execution, control, and execution stack operators
obj eval - Evaluate object.
boolean obj if - Conditionally evaluate object.
boolean a b ifelse - Conditionally evaluate one of two objects.
init inc limit proc for - Iterate with a control variable.
count proc repeat - Iterate a set number of times.
cond proc while - Loop while cond is true.
proc cond until - Loop until cond is false.
proc loop - Loop indefinitely.
array proc foreach - Iterate on array elements.
dict proc foreach - Iterate on dictionary key/value pairs.
stack proc foreach - Iterate on stack elements.
string proc foreach - Iterate on string elements.
- exit - Terminate innermost looping context.
file/string token false Scan for a token.
file/string token file/substring obj true Scan for a token.
obj start - Evaluate object.
- quit - Unwind to innermost start context.
obj stopped boolean Evaluate object.
- stop - Unwind to innermost stopped or start context.
name throw obj Throw an error.
- estack stack Get a current estack snapshot.
thread threadestack stack Get a reference to thread's estack.
- countestack count Get current estack depth.
- istack stack Get a current istack snapshot.
thread threadistack stack Get a reference to thread's istack.
status die - Exit program.
path symbol modload - Load a module.
file symbol mrequire - Search for and load a module.
file require - Search for and evaluate a source file.
args exec - Overlay a new program and execute it.
args forkexec pid Fork and exec a new process.
pid waitpid status Wait for a program to terminate.
args system status Execute a program.
- pid pid Get process ID.
- ppid pid Get parent's process ID.
- uid uid Get the process's user ID.
uid setuid boolean Set the process's user ID.
- euid uid Get the process's effective user ID.
uid seteuid boolean Set the process's effective user ID.
- gid gid Get the process's group ID.
gid setgid boolean Set the process's group ID.
- egid gid Get the process's effective group ID.
gid setegid boolean Set the process's effective group ID.
- realtime nsecs Get the number of nanoseconds since the epoch.
nanoseconds nsleep - Nanosleep.
Stack operators
- ( fino Begin a stack declaration.
fino objects ) stack Create a stack.
- stack stack Create a stack.
stack obj spush - Push object onto stack.
stack obj sbpush - Push object onto bottom of stack.
stack scount count Get the number of objects on a stack.
stack scounttomark count Get the depth of the topmost mark on stack.
stack sdup - Duplicate an object.
stack sbdup - Duplicate bottom object.
stack count sndup - Duplicate objects on stack.
stack index sidup - Duplicate object on stack at index.
stack index sibdup - Duplicate object on stack at index from bottom.
stack stuck - Tuck duplicate of top object on stack under next object on stack.
stack sunder - Duplicate second object on stack.
stack sover - Duplicate second object on stack.
stack sexch - Exchange top objects on stack.
stack sup - Roll top three objects on stack up one.
stack count snup - Roll count objects on stack up one.
stack saup - Roll objects on stack up one.
stack sdn - Roll top three objects on stack down one.
stack count sndn - Roll count objects on stack down one.
stack sadn - Roll objects on stack down one.
stack amount srot - Rotate objects on stack up by amount.
stack count amount sroll - Roll objects on stack.
stack spop obj Pop object off stack.
stack sbpop obj Pop object off bottom of stack.
stack count snpop array Pop count objects off stack.
stack count snbpop array Pop count objects off bottom of stack.
stack index sipop obj Remove object on stack at index.
stack index sibpop obj Remove object on stack at index from bottom.
stack snip obj Remove second object on stack.
stack sclear - Remove all objects on stack.
stack scleartomark - Remove objects from stack down through topmost mark.
(a) (b) cat (a b) Catenate two stacks.
stacks count ncat stack Catenate stacks.
srcstack dststack copy dststack Copy stack contents.
Number (integer, real) and math operators
a b add r Add a and b.
a inc r Add 1 to a.
a b sub r Subtract b from a.
a dec r Subtract 1 from a.
a b mul r Multiply a and b.
a b div r Divide a by b.
a b idiv r Divide a by b (integers).
a b mod r Mod a by b (integers).
a b exp r Raise a to the power of b.
a sqrt r Square root.
a ln r Natural log.
a log r Base 10 log.
a abs r Get the absolute value of a.
a neg r Get the negative of a.
a ceiling r Integer ceiling of a real.
a floor r Integer floor of a real.
a round r Real rounded to integer.
a trunc r Integer from real with truncated fractional.
a sin r Sine in radians.
a cos r Cosine in radians.
y x atan r Arctangent in radians of $y/x$.
seed srand - Seed pseudo-random number generator.
- rand integer Get a pseudo-random number.
String operators
length string string Create a string.
string length count Get string length.
string index get integer Get string element.
string index integer put - Set string element.
string index length getinterval substring Get a string interval.
string index substring putinterval - Copy substring into string.
`a' `b' cat `ab' Catenate two strings.
strings count ncat string Catenate strings.
srcstring dststring copy dstsubstring Copy string.
obj depth sprints string Create syntactical string from object.
obj flags outputs string Create formatted string from object.
string pattern search post pattern pre true Successfully search for pattern.
string pattern search string false Unsuccessfully earch for pattern.
Name operators
name length count Get name length.
Array operators
- argv args Get program arguments.
- [ mark Begin an array declaration.
mark objects ] array Construct an array.
length array array Create an array.
array length count Get array length.
array index get obj Get array element.
array index obj put - Set array element.
array index length getinterval subarray Get an array interval.
array index subarray putinterval - Copy subarray into array.
[a] [b] cat [a b] Catenate two arrays.
arrays count ncat array Catenate arrays.
srcarray dstarray copy dstsubarray Copy array.
Dictionary and dictionary stack operators
- gcdict dict Get gcdict.
- userdict dict Get userdict.
- globaldict dict Get globaldict.
- systemdict dict Get systemdict.
- onyxdict dict Get onyxdict.
- sprintsdict dict Get sprintsdict.
- outputsdict dict Get outputsdict.
- envdict dict Get envdict.
- threadsdict dict Get threadsdict.
key val setenv - Set environment variable.
key unsetenv - Unset environment variable.
- < mark Begin a dictionary declaration.
mark kvpairs > dict Construct a dictionary.
- dict dict Create a dictionary.
dict begin - Pust dict onto dstack.
- end - Pop a dictionary off dstack.
key val def - Define key/value pair.
dict key undef - Undefine key in dict.
key load val Look up a key's value.
dict key known boolean Check for key in dict.
key where false Get topmost dstack dictionary that defines key.
key where dict true Get topmost dstack dictionary that defines key.
dict length count Get number of dictionary key/value pairs.
dict key get value Get dict value associate with key.
dict key value put - Set dict key/value pair.
srcdict dstdict copy dstdict Copy dictionary contents.
- currentdict dict Get topmost dstack dictionary.
- dstack stack Get dstack snapshot.
thread threaddstack stack Get a reference to thread's dstack.
- countdstack count Get number of stacks on dstack.
File and filesystem operators
filename flags open file Open a file.
filename flags mode open file Open a file, creation mode specified.
- pipe rfile wfile Create a pipe.
file close - Close file.
file read integer boolean Read from file.
file string read substring boolean Read from file.
file readline string boolean Read a line from file.
<file dict ...> timeout poll [file ...] Wait for file(s) to change status.
file bytesavailable count Get number of buffered readable bytes.
file iobuf count Get size of I/O buffer.
file count setiobuf - Set size of I/O buffer.
file nonblocking boolean Get non-blocking mode.
file boolean setnonblocking - Set non-blocking mode.
file integer/string write false Write to file.
file integer/string write integer/substring true Write to file.
string print - Print string to stdout.
obj depth sprint - Syntactically print object to stdout.
obj flags output - Formatted print to stdout.
- pstack - Syntactically print ostack elements.
file flushfile - Flush file buffer.
- flush - Flush stdout buffer.
file length truncate - Truncate file.
file offset seek - Move file position pointer.
file tell offset Get file position pointer offset.
path mkdir - Create a directory.
path mode mkdir - Create a directory, mode specified.
path mkfifo - Create a named pipe.
path mode mkfifo - Create a named pipe, mode specified.
old new rename - Rename a file or directory.
file/filename mode chmod - Change file permissions.
file/filename uid gid chown - Change file owner and group.
filename linkname link - Create a hard link.
filename linkname symlink - Create a symbolic link.
filename unlink - Unlink a file.
path rmdir - Remove an empty directory.
file/filename flag test boolean Test a file.
file/filename status dict Get file information.
linkname readlink string Get symbolic link data.
path proc dirforeach - Iterate on directory entries.
- pwd path Get present working directory.
path cd - Change present working directory.
path chroot - Change root directory.
- stdin file Get thread's stdin.
- stdout file Get thread's stdout.
- stderr file Get thread's stderr.
- gstdin file Get global stdin.
- gstdout file Get global stdout.
- gstderr file Get global stderr.
file setstdin - Set thread's stdin.
file setstdout - Set thread's stdout.
file setstderr - Set thread's stderr.
file setgstdin - Set global stdin.
file setgstdout - Set global stdout.
file setgstderr - Set global stderr.
Socket and networking operators
family type proto socket sock Create a socket.
family type socket sock Create a socket.
sock addr port bindsocket - Bind socket to address/port.
sock addr bindsocket - Bind socket to address.
sock path bindsocket - Bind socket to port.
sock backlog listen - Listen for socket connections.
sock listen - Listen for socket connections.
sock accept sock Accept a socket connection.
sock addr port connect - Connect a socket.
sock path connect - Connect a socket.
service serviceport port Get port number for service name.
sock sockname dict Get socket information.
sock level optname sockopt optval Get socket option.
sock optname sockopt optval Get socket option.
sock level optname optval setsockopt - Set socket option.
sock optname optval setsockopt - Set socket option.
sock peername dict Get peer socket information.
sock mesg flags send nsend Send a message.
sock mesg send count Send a message.
sock string flags recv substring Receive a message.
sock string recv substring Receive a message.
family type proto socketpair sock sock Create a socket pair.
family type socketpair sock sock Create a socket pair.
Logical and bitwise operators
a b lt boolean a less than b? (integer/real, string)
a b le boolean a less than or equal to b? (integer/real, string)
a b eq boolean a equal to b? (any type)
a b ne boolean a not equal to b? (any type)
a b ge boolean a greater than or equal to b? (integer/real, string)
a b gt boolean a greater than b? (integer/real, string)
a b and r Logical/bitwise and. (boolean/integer)
a b or r Logical/bitwise or. (boolean/integer)
a b xor r Logical/bitwise exclusive or. (boolean/integer)
a not r Logical/bitwise not. (boolean/integer)
a shift shift integer Bitwise shift.
- false false Return true.
- true true Return false.
Type, conversion, and attribute operators
obj type name Get object type.
obj echeck boolean Evaluatable?
obj xcheck boolean Executable?
obj cve obj Set evaluatable attribute.
obj cvx obj Set executable attribute.
obj cvlit obj Set literal attribute.
string cvn name Convert string to name.
obj cvs string Convert object to string.
integer radix cvrs string Convert integer to radix string.
real precision cvds string Convert real to decimal string.
real precision cves string Convert real to exponential string.
hook hooktag tag Get hook tag.
Threading and synchronization operators
stack entry thread thread Create and run a thread.
- self thread Get a thread object for the running thread.
thread join - Wait for thread to exit.
thread detach - Detach thread.
- yield - Voluntarily yield the processor.
- mutex mutex Create a mutex.
mutex proc monitor - Evaluate an object under the protection of a mutex.
mutex lock - Acquire mutex.
mutex trylock boolean Try to acquire mutex.
mutex unlock - Release mutex.
- condition condition Create a condition variable.
condition mutex wait - Wait on condition.
condition mutex timeout timedwait boolean Wait on condition with timeout.
condition signal - Signal a condition waiter.
condition broadcast - Signal all condition waiters.
- currentlocking boolean Get implicit locking mode.
boolean setlocking - Set implicit locking mode.
obj lcheck boolean Implicitly locked?
Miscellaneous operators
- product string Get the product string.
- version string Get the version string.
proc bind proc Bind names to operators.
- null null Create a null object.

- ( fino:
Input(s):
None.
Output(s):
fino:
A fino object.
Errors(s):
None.
Description:
Push a fino object onto ostack to denote the bottom of a stack that has not yet been constructed.
Example(s):
onyx:0> (
onyx:1> pstack
-fino-
onyx:1>
fino objects ) stack:
Input(s):
fino:
A fino object, usually created by the ) operator.
objects:
0 or more objects.
Output(s):
stack:
A stack object.
Errors(s):
unmatchedfino.
Description:
Create a stack object and move all objects from ostack down to the first fino object to the new stack.
Example(s):
onyx:0> ()
onyx:1> 1 sprint
()
onyx:0> (1 2
onyx:3> pstack
2
1
-fino-
onyx:3> )
onyx:1> 1 sprint
(1 2)
onyx:0>
- < mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Errors(s):
None.
Description:
Begin a dictionary declaration. See the > operator documentation for more details on dictionary construction.
Example(s):
onyx:0> < 1 sprint
-mark-
onyx:0>
mark kvpairs > dict:
Input(s):
mark:
A mark object.
kvpairs:
Zero or more pairs of non-mark objects, where the first is a key and the second is an associated value.
Output(s):
dict:
A dictionary that contains kvpairs.
Errors(s):
rangecheck.
unmatchedmark.
Description:
Construct a dictionary that contains kvpairs.
Example(s):
onyx:0> <
onyx:1> $foo `foo'
onyx:3> $bar `bar'
onyx:5> $biz `biz'
onyx:7> $pop ~pop
onyx:9> >
onyx:1> pstack
<$pop --pop-- $biz `biz' $bar `bar' $foo `foo'>
onyx:1>
- [ mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Errors(s):
None.
Description:
Begin an array declaration. See the ] operator documentation for more details on array construction.
Example(s):
onyx:0> [ 1 sprint
-mark-
onyx:0>
mark objects ] array:
Input(s):
mark:
A mark object.
objects:
Zero or more non-mark objects.
Output(s):
array:
An array that contains objects.
Errors(s):
unmatchedmark.
Description:
Construct an array that contains all objects on ostack down to the first mark.
Example(s):
onyx:0> mark 1 2 3 ] 1 sprint
[1 2 3]
a abs r:
Input(s):
a:
An integer or real.
Output(s):
r:
Absolute value of a.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the absolute value of a.
Example(s):
onyx:0> 5 abs 1 sprint
5
onyx:0> -5 abs 1 sprint
5
onyx:0> 3.14 abs 1 sprint
3.140000e+00
onyx:0> -3.14 abs 1 sprint
3.140000e+00
onyx:0>
sock accept sock:
Input(s):
sock:
A listening socket.
Output(s):
sock:
A socket that is connected to a client.
Errors(s):
argcheck.
invalidfileaccess.
ioerror.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Accept a connection and create a socket that is connected to a client.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup listen
onyx:1> dup accept
onyx:2> dup peername 1 sprint
<$family $AF_INET $address 2130706433 $port 33742>
onyx:2>
a b add r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
The sum of a and b.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the sum of a and b.
Example(s):
onyx:0> 2 2 add 1 sprint
4
onyx:0> -1 3 add 1 sprint
2
onyx:0> 2.0 3.1 add 1 sprint
5.100000e+00
onyx:0> -1.5 +3e1 add 1 sprint
2.850000e+01
onyx:0>
obj ,,, adn ,,,obj:
Input(s):
obj:
An object.
,,,:
Zero or more objects.
Output(s):
,,,:
Zero or more objects.
obj:
An object.
Errors(s):
stackunderflow.
Description:
Rotate stack down one position.
Example(s):
onyx:0> 1 2 3 adn pstack
1
3
2
onyx:3>
a b and r:
Input(s):
a:
An integer or boolean.
b:
The same type as a.
Output(s):
r:
If a and b are integers, their bitwise and, otherwise their logical and.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the bitwise and of two integers, or the logical and of two booleans.
Example(s):
onyx:0> false true and 1 sprint
false
onyx:0> true true and 1 sprint
true
onyx:0> 5 3 and 1 sprint
1
onyx:0>
- argv args:
Input(s):
None.
Output(s):
args:
An array of strings. The first string in args is the path of this program, and any additional array elements are the arguments that were passed during invocation.
Errors(s):
None.
Description:
Get the argument vector that was used to invoke this program.
Example(s):
onyx:0> argv 1 sprint
[`/usr/local/bin/onyx']
onyx:0>
length array array:
Input(s):
length:
Non-negative number of array elements.
Output(s):
array:
An array of length elements.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create an array of length elements. The elements are initialized to null objects.
Example(s):
onyx:0> 3 array 1 sprint
[null null null]
onyx:0> 0 array 1 sprint
[]
onyx:0>
y x atan r:
Input(s):
y:
An integer or real.
x:
An integer or real.
Output(s):
r:
Arctangent of $y/x$ in radians.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the arctangent of $y/x$ in radians.
Example(s):
onyx:0> 1 1 atan 1 sprint
7.853982e-01
onyx:0> 0 1 atan 1 sprint
0.000000e+00
onyx:0> -1.0 0 atan 1 sprint
-1.570796e+00
onyx:0>
,,,obj aup obj ,,,:
Input(s):
,,,:
Zero or more objects.
obj:
An object.
Output(s):
obj:
An object.
,,,:
Zero or more objects.
Errors(s):
stackunderflow.
Description:
Rotate stack up one position.
Example(s):
onyx:0> 1 2 3 aup pstack
2
1
3
onyx:3>
obj ,,, bdup obj ,,,dup:
Input(s):
obj:
An object.
,,,:
Zero or more objects.
Output(s):
obj:
An object.
,,,:
Zero or more objects.
dup:
A duplicate of obj.
Errors(s):
stackunderflow.
Description:
Create a duplicate of the bottom object on ostack and put it on top of ostack.
Example(s):
onyx:0> 1 2 3
onyx:3> bdup pstack
1
3
2
1
onyx:4>
dict begin -:
Input(s):
dict:
A dictionary.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Push dict onto dstack, thereby adding its keys to the namespace.
Example(s):
onyx:0> <$foo `foo'> begin
onyx:0> foo 1 sprint
`foo'
onyx:0>
proc bind proc:
Input(s):
proc:
A procedure (array). proc will be bound even if it is literal, but contained literal arrays will not be recursively bound.
Output(s):
proc:
The same procedure as was passed in.
Errors(s):
stackunderflow.
typecheck.
Description:
Recursively bind unbound procedures. Executable names within a procedure are replaced with their values if defined in dstack, in any of the following cases:
  • The value is a literal object.
  • The value is an executable or evaluatable operator.
  • The value is an executable or evaluatable hook.
  • The value is an executable or evaluatable array.

Binding has a large positive impact on performance, since name lookups are thereafter avoided. However, binding is not done by default because there are situations where it is useful to leave procedures unbound:

  • Debugging is easier, since the names associated with objects are still available.
  • Behavior is more dynamic. It is possible to replace a definition on dstack and have it immediately take effect on unbound procedures. Note however that care must be taken when relying on this, since binding is recursive, and a lack of complete understanding of what procedures reference each other can result in undesired bound procedures. For this reason, it is generally best to make dynamic behavior explicit by using evaluatable names.
  • There are situations where a program needs to do some setup before binding a procedure, and providing manual control over when binding happens allows more sophisticated use of binding.
Example(s):
onyx:0> {pop sprint {pop sprint}}
onyx:1> dup 2 sprint
{pop sprint {pop sprint}}
onyx:1> bind
onyx:1> dup 2 sprint
{--pop-- _{sprints --print-- `\n' --print-- --flush--}_ {--pop-- -array-}}
onyx:1>
sock addr port bindsocket -:
sock addr bindsocket -:
sock path bindsocket -:
Input(s):
sock:
A socket.
addr:
An IPv4 address or DNS hostname.
port:
An IPv4 port number. If not specified, the OS chooses a port number.
path:
A filesystem path for a Unix-domain socket.
Output(s):
None.
Errors(s):
argcheck.
invalidfileaccess.
neterror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Bind an address/port to an IPv4 socket, or a filesystem path to a Unix-domain socket.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_INET $address 2130706433 $port 7777>
onyx:1> close
onyx:0> $AF_LOCAL $SOCK_STREAM socket
onyx:1> dup `/tmp/socket' bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_LOCAL $path `/tmp/socket'>
onyx:1>
obj ,,, bpop ,,,:
Input(s):
,,,:
Zero or more objects.
obj:
An object.
Output(s):
,,,:
Zero or more objects.
Errors(s):
stackunderflow.
Description:
Remove the bottom object from ostack and discard it.
Example(s):
onyx:0> 1 2
onyx:2> bpop pstack
2
onyx:1>
condition broadcast -:
Input(s):
condition:
A condition object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Signal all threads that are waiting on condition. If there are no waiters, this operator has no effect.
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch broadcast unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> wait unlock join
onyx:0>
file bytesavailable count:
Input(s):
file:
A file object.
Output(s):
count:
Number of buffered readable bytes.
Errors(s):
stackunderflow.
typecheck.
Description:
Get the number of buffered readable bytes that can be read without the possibility of blocking.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup `Goodbye\n' write
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1> dup bytesavailable 1 sprint
8
onyx:1>
[a] [b] cat [a b]:
(a) (b) cat (a b):
`a' `b' cat `ab':
Input(s):
a:
An array, stack, or string.
b:
An array, stack, or string.
Output(s):
ab:
The catenation of a and b.
Errors(s):
stackunderflow.
typecheck.
Description:
Catenate two arrays, strings, or stacks.
Example(s):
onyx:0> [`a'] [`b'] cat
onyx:1> 1 sprint
[`a' `b']
onyx:0> (`a') (`b') cat
onyx:1> 1 sprint
(`a' `b')
onyx:0> `a' `b' cat
onyx:1> 1 sprint
`ab'
onyx:0>
path cd -:
Input(s):
path:
A string that represents a filesystem path.
Output(s):
None.
Errors(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
Change the present working directory to path.
Example(s):
onyx:0> pwd 1 sprint
`/usr/local'
onyx:0> `bin' cd
onyx:0> pwd 1 sprint
`/usr/local/bin'
onyx:0>
a ceiling r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer ceiling of a.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the integer ceiling of a.
Example(s):
onyx:0> -1.51 ceiling 1 sprint
-1
onyx:0> -1.49 ceiling 1 sprint
-1
onyx:0> 0 ceiling 1 sprint
0
onyx:0> 1.49 ceiling 1 sprint
2
onyx:0> 1.51 ceiling 1 sprint
2
onyx:0>
file/filename mode chmod -:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
mode:
An integer that represents a Unix file mode.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir 
onyx:0> `/tmp/tdir' status $mode get 1 sprint
16877
onyx:0> `/tmp/tdir' `r' open 
onyx:1> dup 8@555 chmod
onyx:1> `/tmp/tdir' status $mode get 1 sprint
16749
onyx:1>
file/filename uid gid chown -:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
uid:
An integer that represents a user ID.
gid:
An integer that represents a group ID.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Change the owner and group of a file.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' status 
onyx:1> dup $uid get 1 sprint
1001
onyx:1> $gid get 1 sprint
0
onyx:0> `/tmp/tdir' 1001 1001 chown
onyx:0> `/tmp/tdir' status
onyx:1> dup $uid get 1 sprint
1001
onyx:1> $gid get 1 sprint
1001
onyx:0>
path chroot -:
Input(s):
path:
A string that represents a filesystem path.
Output(s):
None.
Errors(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
Change the root directory to path. This operator requires super-user priviledges.
Example(s):
onyx:0> pwd 1 sprint
`/home/jasone/cw/devroot'
onyx:0> `/home/jasone' chroot
onyx:0> pwd 1 sprint
`/cw/devroot'
onyx:0>
objects clear -:
Input(s):
objects:
All objects on ostack.
Output(s):
None.
Errors(s):
None.
Description:
Pop all objects off of ostack.
Example(s):
onyx:0> 1 2 3 pstack
3
2
1
onyx:3> clear pstack
onyx:0>
mark ... cleartomark -:
Input(s):
...:
Zero or more objects.
mark:
A mark object.
Output(s):
None.
Errors(s):
unmatchedmark.
Description:
Remove objects from ostack down to and including the topmost mark.
Example(s):
onyx:0> 3 mark 1 0 pstack
0
1
-mark-
3
onyx:4> cleartomark pstack
3
onyx:1>
file close -:
Input(s):
file:
A file object.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Close a file.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> close
onyx:0>
- condition condition:
Input(s):
None.
Output(s):
condition:
A condition object.
Errors(s):
None.
Description:
Create a condition object.
Example(s):
onyx:0> condition 1 sprint
-condition-
onyx:0>
sock addr port connect -:
sock path connect -:
Input(s):
sock:
A socket.
addr:
An IPv4 address or DNS hostname.
port:
An IPv4 port number. If not specified, the OS chooses a port number.
path:
A filesystem path for a Unix-domain socket.
Output(s):
None.
Errors(s):
argcheck.
invalidfileaccess.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Connect sock.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 connect
onyx:1>
srcarray dstarray copy dstsubarray:
srcdict dstdict copy dstdict:
srcstack dststack copy dststack:
srcstring dststring copy dstsubstring:
Input(s):
srcarray:
An array object.
srcdict:
A dict object.
srcstack:
A stack object.
srcstring:
A string object.
dstarray:
An array object, at least as long as srcarray.
dstdict:
A dict object.
dststack:
A stack object.
dststring:
A string object, at least as long as srcstring.
Output(s):
dstsubarray:
A subarray of dstarray, with the same contents as srcarray.
dstdict:
The same object as the input dstdict, but with the contents of srcdict inserted.
dststack:
The same object as the input dststack, but with the contents of srcstack pushed.
dstsubstring:
A substring of dststring, with the same contents as srcstring.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Copy from one object to another. Array and string copying are destructive; dictionary and stack copying are not.
Example(s):
onyx:0> [`a'] [`b' `c'] copy 1 sprint
[`a']
onyx:0> <$foo `foo'> <$bar `bar'> copy 1 sprint
<$bar `bar' $foo `foo'>
onyx:1> (1 2) (3 4) copy 1 sprint
(3 4 1 2)
onyx:1> `a' `bc' copy 1 sprint
`a'
onyx:1>
a cos r:
Input(s):
a:
An integer or real.
Output(s):
r:
Cosine of a in radians.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the cosine of a in radians.
Example(s):
onyx:0> 0 cos 1 sprint
1.000000e+00
onyx:0> 3.14 cos 1 sprint
-9.999987e-01
onyx:0> 3.1415927 cos 1 sprint
-1.000000e+00
onyx:0>
- count count:
Input(s):
None.
Output(s):
count:
The number of objects on ostack.
Errors(s):
None.
Description:
Get the number of objects on ostack.
Example(s):
onyx:0> 2 1 0 count pstack
3
0
1
2
onyx:4>
- countdstack count:
Input(s):
None.
Output(s):
count:
Number of dictionaries on dstack.
Errors(s):
None.
Description:
Get the number of dictionaries on dstack.
Example(s):
onyx:0> countdstack 1 sprint
4
onyx:0> dict begin
onyx:0> countdstack 1 sprint
5
onyx:0>
- countestack count:
Input(s):
None.
Output(s):
count:
The number of objects currently on the execution stack (recursion depth).
Errors(s):
None.
Description:
Get the current number of objects on the execution stack.
Example(s):
onyx:0> countestack 1 sprint
3
onyx:0> estack 1 sprint
(--start-- -file- --estack--)
onyx:0>
mark ... counttomark mark ...count:
Input(s):
...:
Zero or more objects.
mark:
A mark object.
Output(s):
...:
count objects.
mark:
The same mark that was passed in.
count:
The depth of mark on ostack.
Errors(s):
unmatchedmark.
Description:
Get the depth of the topmost mark on ostack.
Example(s):
onyx:0> 4 mark 2 1 0 counttomark 1 sprint
3
onyx:5>
- currentdict dict:
Input(s):
None.
Output(s):
dict:
Topmost stack on dstack.
Errors(s):
None.
Description:
Get the topmost dictionary on dstack.
Example(s):
onyx:0> <$foo `foo'> begin 
onyx:0> currentdict 1 sprint
<$foo `foo'>
onyx:0>
- currentlocking boolean:
Input(s):
None.
Output(s):
boolean:
If false, new objects are created with implicit locking disabled. Otherwise, new objects are created with implicit locking enabled.
Errors(s):
None.
Description:
Get the current implicit locking mode. See Section 2.7.1 for implicit synchronization details.
Example(s):
onyx:0> currentlocking 1 sprint
false
onyx:0> true setlocking
onyx:0> currentlocking 1 sprint
true
onyx:0>
real precision cvds string:
Input(s):
real:
A real.
precision:
Number of digits after the decimal point to show.
Output(s):
string:
A string representation of real in decimal form with precision digits of decimal precision.
Errors(s):
stackunderflow.
typecheck.
Description:
Convert real to a string representation in decimal notation, with precision digits of decimal precision.
Example(s):
onyx:0> 42.3 0 cvds 1 sprint
`42'
onyx:0> 42.3 1 cvds 1 sprint
`42.3'
onyx:0> -42.3 4 cvds 1 sprint
`-42.3000'
onyx:0>
obj cve obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the evaluatable attribute set.
Errors(s):
stackunderflow.
Description:
Set the evaluatable attribute for obj.
Example(s):
onyx:0> [1 2 3] cve 1 sprint
_{1 2 3}_
onyx:0>
real precision cves string:
Input(s):
real:
A real.
precision:
Number of digits after the decimal point to show.
Output(s):
string:
A string representation of real in exponential form with precision digits of decimal precision.
Errors(s):
stackunderflow.
typecheck.
Description:
Convert real to a string representation in exponential notation, with precision digits of decimal precision.
Example(s):
onyx:0> 42.3 0 cves 1 sprint
`4e+01'
onyx:0> 42.3 1 cves 1 sprint
`4.2e+01'
onyx:0> 42.3 2 cves 1 sprint
`4.23e+01'
onyx:0> -42.3 5 cves 1 sprint
`-4.23000e+01'
onyx:0>
obj cvlit obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the literal attribute set.
Errors(s):
stackunderflow.
Description:
Set the literal attribute for obj.
Example(s):
onyx:0> {1 2 3} cvlit 1 sprint
[1 2 3]
onyx:0>
string cvn name:
Input(s):
string:
A string.
Output(s):
name:
A literal name that corresponds to string.
Errors(s):
stackunderflow.
typecheck.
Description:
Convert string to a literal name.
Example(s):
onyx:0> `foo' cvn 1 sprint
$foo
onyx:0>
integer radix cvrs string:
Input(s):
integer:
An integer.
radix:
A numerical base, from 2 to 36, inclusive.
Output(s):
string:
A string representation of integer in base radix.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Convert integer to a string representation in base radix.
Example(s):
onyx:0> 42 2 cvrs 1 sprint
`101010'
onyx:0> 42 16 cvrs 1 sprint
`2a'
onyx:0>
obj cvs string:
Input(s):
obj:
An object.
Output(s):
string:
A string representation of obj. The string depends on the type of obj:
boolean:
`true' or `false'.
name:
The string representation of the name.
integer:
The integer in base 10.
operator:
The string representation of the operator name or `-operator-'.
real:
The real in exponential notation.
string:
A printable representation of obj. The result can be evaluated to produce the original string.
Other types:
`-nostringval-'.
Errors(s):
stackunderflow.
Description:
Convert obj to a string representation.
Example(s):
onyx:0> true cvs 1 sprint
`true'
onyx:0> $foo cvs 1 sprint
`foo'
onyx:0> 42 cvs 1 sprint
`42'
onyx:0> ~pop cvs 1 sprint
`pop'
onyx:0> 42.0 cvs 1 sprint
`4.200000e+01'
onyx:0> `foo\nbar\\biz\`baz' cvs 1 sprint
`\`foo\\nbar\\\\biz\\\`baz\''
onyx:0> mutex cvs 1 sprint
`--nostringval--'
onyx:0>
obj cvx obj:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in, but with the executable attribute set.
Errors(s):
stackunderflow.
Description:
Set the executable attribute for obj.
Example(s):
onyx:0> [1 2 3] cvx 1 sprint
{1 2 3}
onyx:0>
a dec r:
Input(s):
a:
An integer.
Output(s):
r:
$a - 1$.
Errors(s):
stackunderflow.
typecheck.
Description:
Subtract one from a.
Example(s):
onyx:0> 1 dec 1 sprint
0
onyx:0>
key val def -:
Input(s):
key:
An object.
val:
A value associated with key.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Define key with associated value val in the topmost dictionary on dstack. If key is already defined in that dictionary, the old definition is replaced.
Example(s):
onyx:0> $foo `foo' def
onyx:0> foo 1 sprint
`foo'
onyx:0> $foo `FOO' def
onyx:0> foo 1 sprint
`FOO'
onyx:0>
thread detach -:
Input(s):
thread:
A thread object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Detach thread so that its resources will be automatically reclaimed after it exits. A thread may only be detached or joined once; any attempt to do so more than once results in undefined behavior (likely crash).
Example(s):
onyx:0> (1 2) {add 1 sprint self detach} thread
3
onyx:1>
- dict dict:
Input(s):
None.
Output(s):
dict:
An empty dictionary.
Errors(s):
None.
Description:
Create an empty dictionary.
Example(s):
onyx:0> dict 1 sprint
<>
onyx:0>
status die -:
Input(s):
status:
A integer from 0 to 255 that is used as the program exit code.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Exit the program with exit code status.
Example(s):
onyx:0> 1 die
path proc dirforeach -:
Input(s):
path:
A string that represents a filesystem path.
proc:
An object to be executed.
Output(s):
None.
Errors(s):
invalidaccess.
ioerror.
stackunderflow.
typecheck.
Description:
For each entry in the directory represented by path except for ``.'' and ``..'', push a string that represents the entry onto ostack and execute proc. This operator supports the exit operator.
Example(s):
onyx:0> pwd {1 sprint} dirforeach
`CVS'
`.cvsignore'
`Cookfile'
`Cookfile.inc'
`latex'
`Cookfile.inc.in'
onyx:0> pwd {`Cookfile.inc' search
     {pop `Yes: ' print 1 sprint pop exit}
     {`Not: ' print 1 sprint} ifelse
} dirforeach
Not: `CVS'
Not: `.cvsignore'
Not: `Cookfile'
Yes: `Cookfile.inc'
onyx:0>
a b div r:
Input(s):
a:
An integer or real.
b:
A non-zero integer or real.
Output(s):
r:
The quotient of a divided by b.
Errors(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the quotient of a divided by b.
Example(s):
onyx:0> 4 2 div 1 sprint
2.000000e+00
onyx:0> 5 2.0 div 1 sprint
2.500000e+00
onyx:0> 5.0 0 div
Error $undefinedresult
ostack: (5.000000e+00 0)
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      --div--
1:      -file-
2:      --start--
onyx:3>
a b c dn b c a:
Input(s):
a:
An object.
b:
An object.
c:
An object.
Output(s):
b:
An object.
c:
An object.
a:
An object.
Errors(s):
stackunderflow.
Description:
Rotate the top three objects on ostack down one position.
Example(s):
onyx:0> `a' `b' `c' `d' dn pstack
`b'
`d'
`c'
`a'
onyx:4>
- dstack stack:
Input(s):
None.
Output(s):
stack:
A snapshot of dstack.
Errors(s):
None.
Description:
Get a snapshot of dstack.
Example(s):
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
obj dup obj dup:
Input(s):
obj:
An object.
Output(s):
obj:
The same object that was passed in.
dup:
A duplicate of obj.
Errors(s):
stackunderflow.
Description:
Create a duplicate of the top object on ostack. For composite objects, the new object is a reference to the same composite object.
Example(s):
onyx:0> 1 dup pstack
1
1
onyx:2>
obj echeck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the evaluatable attribute, false otherwise.
Errors(s):
stackunderflow.
Description:
Check obj for evaluatable attribute.
Example(s):
onyx:0> {1 2 3} cve
onyx:1> dup 1 sprint
_{1 2 3}_
onyx:1> echeck 1 sprint
true
onyx:0> {1 2 3} echeck 1 sprint
false
onyx:0> [1 2 3] echeck 1 sprint
false
onyx:0>
- egid gid:
Input(s):
None.
Output(s):
gid:
Process's effective group ID.
Errors(s):
None.
Description:
Get the process's effective group ID.
Example(s):
onyx:0> egid 1 sprint
1001
onyx:0>
- end -:
Input(s):
None.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Pop the topmost dictionary off dstack, thereby removing its contents from the namespace.
Example(s):
onyx:0> <$foo `foo'> begin
onyx:0> foo 1 sprint
`foo'
onyx:0> end
onyx:0> foo 1 sprint
Error $undefined
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      foo
1:      -file-
2:      --start--
onyx:1>
- envdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get envdict. See Section 2.9.2 for details on envdict.
Example(s):
onyx:0> envdict 0 sprint
-dict-
onyx:0>
a b eq boolean:
Input(s):
a:
An object.
b:
An object.
Output(s):
boolean:
True if a is equal to b, false otherwise.
Errors(s):
stackunderflow.
Description:
Compare two objects for equality. Equality has the following meaning, depending on the types of a and b:
array, condition, dict, file, hook, mutex, stack, thread:
a and b are equal iff they refer to the same memory.
operator:
a and b are equal iff they refer to the same function.
name, string:
a and b are equal iff they are lexically equivalent. A name can be equal to a string.
boolean:
a and b are equal iff they are the same value.
integer, real:
a and b are equal iff they are the same value.
Example(s):
onyx:0> mutex mutex eq 1 sprint
false
onyx:0> mutex dup eq 1 sprint
true
onyx:0> $foo `foo' eq 1 sprint
true
onyx:0> true true eq 1 sprint
true
onyx:0> true false eq 1 sprint
false
onyx:0> 1 1 eq 1 sprint
true
onyx:0> 1 2 eq 1 sprint
false
onyx:0> 1.0 1 eq 1 sprint
true
onyx:0> 1.0 1.1 eq 1 sprint
false
onyx:0>
- estack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of the execution stack.
Errors(s):
None.
Description:
Get a current snapshot of the execution stack.
Example(s):
onyx:0> estack 1 sprint
(--start-- -file- --estack--)
onyx:0>
- euid uid:
Input(s):
None.
Output(s):
uid:
Process's effective user ID.
Errors(s):
None.
Description:
Get the process's effective user ID.
Example(s):
onyx:0> euid 1 sprint
1001
onyx:0>
obj eval -:
Input(s):
obj:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Evaluate object. See Section 2.1 for details on object evaluation.
Example(s):
onyx:0> ``hi' 1 sprint' cvx eval
`hi'
onyx:0>
a b exch b a:
Input(s):
a:
An object.
b:
An object.
Output(s):
b:
The same object that was passed in.
a:
The same object that was passed in.
Errors(s):
stackunderflow.
Description:
Exchange the top two objects on ostack.
Example(s):
onyx:0> 1 2 pstack
2
1
onyx:2> exch pstack
1
2
onyx:2>
args exec -:
Input(s):
args:
An array of strings. The first string in args is the path of the program to invoke, and any additional array elements are passed as command line arguments to the invoked program.
Output(s):
None (this operator does not return).
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Overlay a new program and execute it. The current contents of envdict are used to construct the new program's environment.
Example(s):
onyx:0> `Old program'
onyx:1> [`/usr/local/bin/onyx'] exec
Canonware Onyx, version 1.0.0.
onyx:0>
- exit -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Exit the innermost enclosing looping context immediately. This operator can be called within the looping context of for , repeat , while , until , loop , foreach , and dirforeach .
Example(s):
onyx:0> {`hi' 1 sprint exit `bye' 1 sprint} loop
`hi'
onyx:0>
a b exp r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
a to the b power.
Errors(s):
stackunderflow.
typecheck.
Description:
Return a to the b power. If a negative exponent is specified, the result will always be a real, even if both arguments are integers.
Example(s):
onyx:0> 5 0 exp 1 sprint
1
onyx:0> 5 1 exp 1 sprint
5
onyx:0> 5 2 exp 1 sprint
25
onyx:0> -5 3 exp 1 sprint
-125
onyx:0> 5 -3 exp 1 sprint
8.000000e-03
onyx:0> 2.1 3.5 exp 1 sprint
1.342046e+01
onyx:0> 100 .01 exp 1 sprint
1.000000e+02
onyx:0>
- false false:
Input(s):
None.
Output(s):
false:
The boolean value false.
Errors(s):
None.
Description:
Return false.
Example(s):
onyx:0> false 1 sprint
false
onyx:0>
a floor r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer floor of a.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the integer floor of a.
Example(s):
onyx:0> -1.51 floor 1 sprint
-2
onyx:0> -1.49 floor 1 sprint
-2
onyx:0> 0 floor 1 sprint
0
onyx:0> 1.49 floor 1 sprint
1
onyx:0> 1.51 floor 1 sprint
1
onyx:0>
- flush -:
Input(s):
None.
Output(s):
None.
Errors(s):
ioerror.
Description:
Flush any buffered data associated with stdout.
Example(s):
onyx:0> `Hi\n' print
onyx:0> flush
Hi
onyx:0>
file flushfile -:
Input(s):
file:
A file object.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Flush any buffered data associated with file.
Example(s):
onyx:0> `Hi\n' print
onyx:0> stdout flushfile
Hi
onyx:0>
init inc limit proc for -:
Input(s):
init:
Initial value of control variable.
inc:
Amount to increment control variable by at the end of each iteration.
limit:
Inclusive upper bound for control variable if less than or equal to init, otherwise inclusive lower bound for control variable.
proc:
An object.
Output(s):
At the beginning of each iteration, the current value of the control variable is pushed onto ostack.
Errors(s):
stackunderflow.
typecheck.
Description:
Iteratively evaluate proc, pushing a control variable onto ostack at the beginning of each iteration, until the control variable has exceeded limit. This operator supports the exit operator.
Example(s):
onyx:0> 0 1 3 {1 sprint} for
0
1
2
3
onyx:0> 0 -1 -3 {1 sprint} for
0
-1
-2
-3
onyx:0> 0 2 7 {1 sprint} for
0
2
4
6
onyx:0> 0 1 1000 {dup 1 sprint 3 eq {exit} if} for
0
1
2
3
onyx:0>
array proc foreach -:
dict proc foreach -:
stack proc foreach -:
string proc foreach -:
Input(s):
array:
An array object.
dict:
A dict object.
stack:
A stack object.
string:
A string object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
For each entry in the first input argument (array, dict, stack, or string), push the entry onto ostack and execute proc. This operator supports the exit operator.
Example(s):
onyx:0> [1 2] {1 sprint} foreach
1
2
onyx:0> <$foo `foo' $bar `bar'> {pstack clear} foreach
`bar'
$bar
`foo'
$foo
onyx:0> (1 2) {pstack clear} foreach
2
1
onyx:0> `ab' {pstack clear} foreach
97
98
onyx:0>
args forkexec pid:
Input(s):
args:
An array of strings. The first string in args is the path of the program to invoke, and any additional array elements are passed as command line arguments to the invoked program.
Output(s):
pid:
Process identifier for the new process, or 0 if the child process.
Errors(s):
limitcheck.
rangecheck.
stackunderflow.
typecheck.
Description:
Fork and exec a new process. The current contents of envdict are used to construct the new program's environment.
Example(s):
onyx:0> [`/bin/date'] forkexec dup 1 sprint waitpid 1 sprint
6516
Sat Jul 13 20:47:54 PDT 2002
0
onyx:0>
- gcdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get gcdict. See Section 2.9.4 for details on gcdict.
Example(s):
onyx:0> gcdict 0 sprint
-dict-
onyx:0>
a b ge boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is greater than or equal to b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 2 ge 1 sprint
false
onyx:0> 1 1 ge 1 sprint
true
onyx:0> 2 1 ge 1 sprint
true
onyx:0> 1 1.1 ge 1 sprint
false
onyx:0> 1.1 1.1 ge 1 sprint
true
onyx:0> 1.1 1 ge 1 sprint
true
onyx:0> `a' `b' ge 1 sprint
false
onyx:0> `a' `a' ge 1 sprint
true
onyx:0> `b' `a' ge 1 sprint
true
onyx:0>
array index get obj:
dict key get value:
string index get integer:
Input(s):
array:
An array object.
dict:
A dict object.
string:
A string object.
index:
Offset of array element or string element.
key:
A key in dict.
Output(s):
obj:
The object in array at offset index.
value:
The value in dict corresponding to key.
integer:
The ascii value of the character in string at offset index.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
undefined.
Description:
Get an element of array, a value in dict, or an element of string.
Example(s):
onyx:0> [`a' `b' `c'] 1 get 1 sprint
`b'
onyx:0> <$foo `foo' $bar `bar'> $bar get 1 sprint
`bar'
onyx:0> `abc' 1 get 1 sprint
98
onyx:0>
array index length getinterval subarray:
string index length getinterval substring:
Input(s):
array:
An array object.
string:
A string object.
index:
The offset into array or string to get the interval from.
length:
The length of the interval in array or string to get.
Output(s):
subarray:
A subarray of array at offset index and of length length.
substring:
A substring of string at offset index and of length length.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Get an interval of array or string.
Example(s):
onyx:0> [0 1 2 3] 1 2 getinterval 1 sprint
[1 2]
onyx:0> `abcd' 1 2 getinterval 1 sprint
`bc'
onyx:0>
- gid gid:
Input(s):
None.
Output(s):
gid:
Process's group ID.
Errors(s):
None.
Description:
Get the process's group ID.
Example(s):
onyx:0> gid 1 sprint
1001
onyx:0>
- globaldict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get globaldict. See Section 2.9.5 for details on globaldict.
Example(s):
onyx:0> globaldict 1 sprint
<>
onyx:0>
- gstderr file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the global stderr.
Errors(s):
None.
Description:
Get the global stderr that is inherited by new threads. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> gstderr pstack
-file-
onyx:1>
- gstdin file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the global stdin.
Errors(s):
None.
Description:
Get the global stdin that is inherited by new threads. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> gstdin pstack
-file-
onyx:1>
- gstdout file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the global stdout.
Errors(s):
None.
Description:
Get the global stdout that is inherited by new threads. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> gstdout pstack
-file-
onyx:1>
a b gt boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is greater than b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 1 gt 1 sprint
false
onyx:0> 2 1 gt 1 sprint
true
onyx:0> 1.1 1.1 gt 1 sprint
false
onyx:0> 1.1 1 gt 1 sprint
true
onyx:0> `a' `a' gt 1 sprint
false
onyx:0> `b' `a' gt 1 sprint
true
onyx:0>
hook hooktag tag:
Input(s):
hook:
A hook object.
Output(s):
tag:
The tag associated with hook.
Errors(s):
stackunderflow.
typecheck.
Description:
Get the tag associated with hook.
Example(s):

OPARGS hostbyname OPOUTS:
Input(s):
:
Output(s):
:
Errors(s):
stackunderflow.
typecheck.
Description:
Example(s):

...obj ,,,index ibdup ...obj ,,,dup:
Input(s):
...:
index objects.
obj:
An object.
,,,:
Zero or more objects.
index:
Offset from bottom of ostack, counting from 0.
Output(s):
...:
index objects.
obj:
An object.
,,,:
Zero or more objects.
dup:
Duplicate of obj.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on ostack that is at offset index from the bottom of ostack.
Example(s):
onyx:4> 2 ibdup pstack
2
3
2
1
0
onyx:5>
...obj ,,,index ibpop ...,,,:
Input(s):
...:
index objects.
obj:
An object.
,,,:
Zero or more objects.
index:
Offset from bottom of ostack, counting from 0.
Output(s):
...:
index objects.
,,,:
Zero or more objects.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the object from ostack that is at offset index from the bottom of ostack.
Example(s):
onyx:0> 0 1 2 3
onyx:4> 2 ibpop pstack
3
1
0
onyx:3>
a b idiv r:
Input(s):
a:
An integer.
b:
A non-zero integer.
Output(s):
r:
The integer quotient of a divided by b.
Errors(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the integer quotient of a divided by b.
Example(s):
onyx:0> 4 2 idiv 1 sprint
2
onyx:0> 5 2 idiv 1 sprint
2
onyx:0> 5 0 idiv
Error $undefinedresult
ostack: (5 0)
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      --idiv--
1:      -file-
2:      --start--
onyx:3>
obj ...index idup obj ...dup:
Input(s):
obj:
An object.
index:
Offset from top of ostack, counting from 0, not counting index), of the object to duplicate on ostack.
Output(s):
obj:
The same object that was passed in.
dup:
A duplicate of obj.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on ostack at index.
Example(s):
onyx:0> 3 2 1 0 2 idup pstack
2
0
1
2
3
onyx:5>
boolean obj if -:
Input(s):
boolean:
A boolean.
obj:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Evaluate obj if boolean is true.
Example(s):
onyx:0> true {`yes' 1 sprint} if
`yes'
onyx:0> false {`yes' 1 sprint} if
onyx:0>
boolean a b ifelse -:
Input(s):
boolean:
A boolean.
a:
An object.
b:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Evaluate a if boolean is true, evaluate b otherwise. See Section 2.1 for details on object evaluation.
Example(s):
onyx:0> true {`yes'}{`no'} ifelse 1 sprint
`yes'
onyx:0> false {`yes'}{`no'} ifelse 1 sprint
`no'
onyx:0>
a inc r:
Input(s):
a:
An integer.
Output(s):
r:
$a + 1$.
Errors(s):
stackunderflow.
typecheck.
Description:
Add one to a.
Example(s):
onyx:0> 1 inc 1 sprint
2
onyx:0>
file iobuf count:
Input(s):
file:
A file object.
Output(s):
count:
The size in bytes of the I/O buffer associated with file.
Errors(s):
stackunderflow.
typecheck.
Description:
Get the size of the I/O buffer associated with file.
Example(s):
onyx:0> stdout iobuf 1 sprint
512
onyx:0> stderr iobuf 1 sprint
0
onyx:0>
obj ...index ipop ...:
Input(s):
obj:
An object.
index:
Offset from top of ostack, counting from 0, not counting index), of the object to remove from ostack.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Remove the obj at index from ostack.
Example(s):
onyx:0> 2 1 0 
onyx:3> 1 ipop pstack
0
2
onyx:2>
- istack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of the index stack.
Errors(s):
None.
Description:
Get a current snapshot of the index stack.
Example(s):
onyx:0> istack 1 sprint
(0 0 0)
onyx:0>
thread join -:
Input(s):
thread:
A thread object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Wait for thread to exit. A thread may only be detached or joined once; any attempt to do so more than once results in undefined behavior (likely crash).
Example(s):
onyx:0> (1 2) {add 1 sprint} thread join `Done\n' print flush
3
Done
onyx:0>
dict key known boolean:
Input(s):
dict:
A dictionary.
key:
A key to look for in dict.
Output(s):
boolean:
True if key is defined in dict, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Check whether key is defined in dict.
Example(s):
onyx:1> <$foo `foo'> $foo known 1 sprint
true
onyx:1> <$foo `foo'> $bar known 1 sprint
false
onyx:1>
obj lcheck boolean:
Input(s):
obj:
An array, dict, file, or string.
Output(s):
boolean:
True if obj is implicitly locked, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Check if obj is implicitly locked.
Example(s):
onyx:0> false setlocking
onyx:0> [1 2 3] lcheck 1 sprint
false
onyx:0> true setlocking
onyx:0> [1 2 3] lcheck 1 sprint
true
onyx:0>
a b le boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is less than or equal to b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 2 le 1 sprint
true
onyx:0> 1 1 le 1 sprint
true
onyx:0> 2 1 le 1 sprint
false
onyx:0> 1 1.1 le 1 sprint
true
onyx:0> 1.1 1.1 le 1 sprint
true
onyx:0> 1.1 1 le 1 sprint
false
onyx:0> `a' `b' le 1 sprint
true
onyx:0> `a' `a' le 1 sprint
true
onyx:0> `b' `a' le 1 sprint
false
onyx:0>
array length count:
dict length count:
name length count:
string length count:
Input(s):
array:
An array object.
dict:
A dict object.
name:
A name object.
string:
A string object.
Output(s):
count:
Number of elements in array, number of entries in dict, number of characters in name, or number of characters in string.
Errors(s):
stackunderflow.
typecheck.
Description:
Get the umber of elements in array, number of entries in dict, number of characters in name, or number of characters in string.
Example(s):
onyx:0> [1 2 3] length 1 sprint
3
onyx:0> <$foo `foo' $bar `bar'> length 1 sprint
2
onyx:0> $foo length 1 sprint
3
onyx:0> `foo' length 1 sprint
3
onyx:0>
filename linkname link -:
Input(s):
filename:
A string that represents a filename.
linkname:
A string that represents a filename.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Create a hard link from linkname to filename.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> close
onyx:0> `/tmp/foo' `/tmp/bar' link
onyx:0> `/tmp/bar' `r' open
onyx:1> readline
onyx:2> pstack
false
`Hello'
onyx:2>
sock backlog listen -:
Input(s):
sock:
A socket.
backlog:
Maximum backlog of connections to listen for. If not specified, the maximum backlog is used.
Output(s):
None.
Errors(s):
invalidfileaccess.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Listen for connections on a socket.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup listen
onyx:1>
a ln r:
Input(s):
a:
An integer or real.
Output(s):
r:
Natural logarithm of a.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the natural logarithm of a.
Example(s):
onyx:0> 5 ln 1 sprint
1.609438e+00
onyx:0> 8.5 ln 1 sprint
2.140066e+00
onyx:0>
key load val:
Input(s):
key:
A key to look up in dstack.
Output(s):
val:
The value associated with the topmost definition of key in dstack.
Errors(s):
stackunderflow.
undefined.
Description:
Get the topmost definition of key in dstack.
Example(s):
onyx:1> <$foo `foo'> begin
onyx:1> <$foo `FOO'> begin
onyx:1> $foo load 1 sprint
`FOO'
onyx:1>
mutex lock -:
Input(s):
mutex:
A mutex object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Acquire mutex, waiting if necessary. Attempting to acquire mutex recursively will result in undefined behavior (likely deadlock or crash).
Example(s):
onyx:0> mutex dup lock unlock
onyx:0>
a log r:
Input(s):
a:
An integer or real.
Output(s):
r:
Base 10 logarithm of a.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the base 10 logarithm of a.
Example(s):
onyx:0> 5 log 1 sprint
6.989700e-01
onyx:0> 8.5 log 1 sprint
9.294189e-01
onyx:0>
proc loop -:
Input(s):
proc:
An object to evaluate.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Repeatedly evaluate proc indefinitely. This operator supports the exit operator.
Example(s):
onyx:0> 0 {1 add dup 1 sprint dup 3 eq {pop exit} if} loop
1
2
3
onyx:0>
a b lt boolean:
Input(s):
a:
A number (integer or real) or string.
b:
An object of a type compatible with a.
Output(s):
boolean:
True if a is less than b, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Compare two numbers or strings.
Example(s):
onyx:0> 1 2 lt 1 sprint
true
onyx:0> 1 1 lt 1 sprint
false
onyx:0> 1 1.1 lt 1 sprint
true
onyx:0> 1.1 1.1 lt 1 sprint
false
onyx:0> 1.1 1 lt 1 sprint
false
onyx:0> `a' `b' lt 1 sprint
true
onyx:0> `a' `a' lt 1 sprint
false
onyx:0>
- mark mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Errors(s):
None.
Description:
Push a mark onto ostack.
Example(s):
onyx:0> mark pstack
-mark-
onyx:1>
path mkdir -:
path mode mkdir -:
Input(s):
path:
A string object that represents a directory path.
mode:
An integer that represents a Unix file mode.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Create a directory.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' {1 sprint} dirforeach
`.'
`..'
onyx:0>
path mkfifo -:
path mode mkfifo -:
Input(s):
path:
A string object that represents a directory path.
mode:
An integer that represents a Unix file mode.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Create a named pipe.
Example(s):
onyx:0> `/tmp/fifo' mkfifo
onyx:0>
a b mod r:
Input(s):
a:
An integer.
b:
A non-zero integer.
Output(s):
r:
The modulus of a and b.
Errors(s):
stackunderflow.
typecheck.
undefinedresult.
Description:
Return the modulus of a and b.
Example(s):
onyx:0> 4 2 mod 1 sprint
0
onyx:0> 5 2 mod 1 sprint
1
onyx:0> 5 0 mod
Error $undefinedresult
ostack: (5 0)
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      --mod--
1:      -file-
2:      --start--
onyx:3>
path symbol modload -:
Input(s):
path:
A string that represents a module filename.
symbol:
A string that represents the symbol name of a module initialization function to be executed.
Output(s):
None.
Errors(s):
invalidfileaccess.
stackunderflow.
typecheck.
undefined.
Description:
Dynamically load a module, create a hook object that encapsulates the handle returned by dlopen(3) (hook data pointer) and the module initialization function (hook evaluation function), and evaluate the hook.

All objects that refer to code and/or data that are part of the module must directly and/or indirectly maintain a reference to the hook that is evaluated by this operator, since failing to do so would allow the garbage collector to unload the module, which could result in dangling pointers to unmapped memory regions.

Loadable modules present a problem for the garbage collector during the sweep phase. All objects that refer to memory that is dynamically mapped as part of the module must be destroyed before the module is unloaded. Destruction ordering constraints show up in other situations as well, but in the case of loadable modules, there is no reasonable solution except to explicitly order the destruction of objects. Therefore, by default, the hook that is evaluated by modload is destroyed during the second sweep pass. It is possible for a module to override what sweep pass the hook is destroyed on, in cases where there are additional ordering constraints for the objects created by a module. This isn't important from the Onyx language perspective, but is important to understand when implementing modules.

Example(s):
onyx:0> `/usr/local/share/onyx/nxmod/mdprompt.nxm' `modprompt_init'
onyx:2> modload
onyx:0>
mutex proc monitor -:
Input(s):
mutex:
A mutex.
proc:
Any object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Execute proc while holding mutex.
Example(s):
onyx:0> mutex {`hello\n' print} monitor flush
hello
onyx:0>
file symbol mrequire -:
Input(s):
file:
A string that represents a module filename.
symbol:
A string that represents the symbol name of a module initialization function to be executed.
Output(s):
None.
Errors(s):
invalidfileaccess.
stackunderflow.
typecheck.
undefined.
undefinedfilename.
Description:
Search for and load a module. The module is searched for by catenating a prefix, a ``/'', and file to form a file path. Prefixes are tried in the following order:
  1. The ordered elements of the mpath_pre array, which is defined in onyxdict.
  2. If defined, the ordered elements of the ONYX_MPATH environment variable, which is a colon-separated list.
  3. The ordered elements of the mpath_post array, which is defined in onyxdict.
Example(s):
onyx:0> `modgtk.nxm' `modgtk_init' mrequire
onyx:0>
a b mul r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
The product of a and b.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the product of a and b.
Example(s):
onyx:0> 3 17 mul 1 sprint
51
onyx:0> -5 -6 mul 1 sprint
30
onyx:0> 3.5 4.0 mul 1 sprint
1.400000e+01
onyx:0> -1.5 3 mul 1 sprint
-4.500000e+00
onyx:0>
- mutex mutex:
Input(s):
None.
Output(s):
mutex:
A mutex object.
Errors(s):
None.
Description:
Create a mutex.
Example(s):
onyx:0> mutex 1 sprint
-mutex-
onyx:0>
objects ...count nbpop ...:
Input(s):
objects:
Zero or more objects.
count:
Number of objects to pop.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the bottom count objects from ostack and discard them.
Example(s):
onyx:0> `a' `b' `c' 2 nbpop pstack
`c'
onyx:1>
arrays count ncat array:
stacks count ncat stack:
strings count ncat string:
Input(s):
arrays:
count arrays.
stacks:
count stacks.
strings:
count strings.
count:
Number of arrays, stacks, or strings to catenate.
Output(s):
obj:
The catenation of arrays, stacks, or strings.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Catenate count arrays, stacks, or strings.
Example(s):
onyx:0> [`a'] [`b'] [`c'] 3 ncat 1 sprint
[`a' `b' `c']
onyx:0> (`a') (`b') (`c') 3 ncat 1 sprint
(`a' `b' `c')
onyx:0> `a' `b' `c' 3 ncat 1 sprint
`abc'
onyx:0>
a ...b count ndn ...b a:
Input(s):
a:
An object.
...:
$count - 2$ objects.
b:
An object.
count:
Number of objects to rotate downward.
Output(s):
...:
$count - 2$ objects.
b:
An object.
a:
An object.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Rotate count objects on ostack down one position.
Example(s):
onyx:0> `a' `b' `c' `d' `e' 4 ndn pstack
`b'
`e'
`d'
`c'
`a'
onyx:5>
objects count ndup objects objects:
Input(s):
objects:
Zero or more objects.
count:
The number of objects do duplicate.
Output(s):
objects:
The same objects that were passed in.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create duplicates of the top count objects on ostack. For composite objects, the new object is a reference to the same composite object.
Example(s):
onyx:0> `a' `b' `c' 2 ndup pstack
`c'
`b'
`c'
`b'
`a'
onyx:5>
a b ne boolean:
Input(s):
a:
An object.
b:
An object.
Output(s):
boolean:
True if a is not equal to b, false otherwise.
Errors(s):
stackunderflow.
Description:
Compare two objects for inequality. Inequality has the following meaning, depending on the types of a and b:
array, condition, dict, file, hook, mutex, stack, thread:
a and b are not equal unless they refer to the same memory.
operator:
a and b are not equal unless they refer to the same function.
name, string:
a and b are not equal iff they are lexically equivalent. A name can be equal to a string.
boolean:
a and b are not equal unless they are the same value.
integer, real:
a and b are not equal unless they are the same value.
Example(s):
onyx:0> mutex mutex ne 1 sprint
true
onyx:0> mutex dup ne 1 sprint
false
onyx:0> $foo `foo' ne 1 sprint
false
onyx:0> $foo $bar ne 1 sprint
true
onyx:0> true false ne 1 sprint
true
onyx:0> true true ne 1 sprint
false
onyx:0> 1 1 ne 1 sprint
false
onyx:0> 1 2 ne 1 sprint
true
onyx:0> 1.0 1 ne 1 sprint
false
onyx:0> 1.0 1.1 ne 1 sprint
true
onyx:0>
a neg r:
Input(s):
a:
An integer.
Output(s):
r:
The negative of a.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the negative of a.
Example(s):
onyx:0> 0 neg 1 sprint
0
onyx:0> 5 neg 1 sprint
-5
onyx:0> -5 neg 1 sprint
5
onyx:0> 3.14 neg 1 sprint
-3.140000e+00
onyx:0> -3.14 neg 1 sprint
3.140000e+00
onyx:0>
a b nip b:
Input(s):
a:
An object.
b:
An object.
Output(s):
b:
An object.
Errors(s):
stackunderflow.
Description:
Remove the second to top object from ostack.
Example(s):
onyx:0> `a' `b' `c'
onyx:3> nip pstack
`c'
`a'
onyx:2>
file nonblocking boolean:
Input(s):
file:
A file object.
Output(s):
boolean:
Nonb-blocking mode for file.
Errors(s):
stackunderflow.
typecheck.
Description:
Get non-blocking mode for file.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup nonblocking 1 sprint
false
onyx:1> dup true setnonblocking
onyx:1> dup nonblocking 1 sprint
true
onyx:1>
a not r:
Input(s):
a:
An integer or boolean.
Output(s):
r:
If a is an integer, the bitwise negation of a, otherwise the logical negation of a.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the bitwise negation of an integer, or the logical negation of a boolean.
Example(s):
onyx:0> true not 1 sprint
false
onyx:0> false not 1 sprint
true
onyx:0> 1 not 1 sprint
-2
onyx:0>
objects count npop -:
Input(s):
objects:
Zero or more objects.
count:
Number of objects to pop.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the top count objects from ostack and discard them.
Example(s):
onyx:0> `a' `b' `c' 2 npop pstack
`a'
onyx:1>
nanoseconds nsleep -:
Input(s):
nanoseconds:
Minimum number of nanoseconds to sleep. Must be greater than 0.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Sleep for at least nanoseconds nanonseconds.
Example(s):
onyx:0> 1000 nsleep
onyx:0>
- null null:
Input(s):
None.
Output(s):
null:
A null object.
Errors(s):
None.
Description:
Create a null object.
Example(s):
onyx:0> null pstack
null
onyx:1>
a ...b count nup b a ...:
Input(s):
a:
An object.
...:
$count - 2$ objects.
b:
An object.
count:
Number of objects to rotate upward.
Output(s):
b:
An object.
a:
An object.
...:
$count - 2$ objects.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Rotate count objects on ostack up one position.
Example(s):
onyx:0> `a' `b' `c' `d' `e' 4 nup pstack
`d'
`c'
`b'
`e'
`a'
onyx:5>
- onyxdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get onyxdict. See Section 2.9.6 for details on onyxdict.
Example(s):
onyx:0> onyxdict 1 sprint
<$rpath_pre -array- $rpath_post -array- $mpath_pre -array- $mpath_post -array->
onyx:0>
filename flags open file:
filename flags mode open file:
Input(s):
filename:
A string that represents a filename.
flags:
A string that represents a file mode:
`r':
Read only.
`r+':
Read/write, starting at offset 0.
`w':
Write only. Create file if necessary. Truncate file if non-zero length.
`w+':
Read/write, starting at offset 0. Create file if necessary.
`a':
Write only, starting at end of file.
`a+':
Read/write, starting at end of file.
mode:
Mode to use when creating a new file (defaults to 0777). Note that the process's umask also affects creation mode.
Output(s):
file:
A file object.
Errors(s):
invalidfileaccess.
ioerror.
limitcheck.
rangecheck.
stackunderflow.
typecheck.
Description:
Open a file.
Example(s):
onyx:0> `/tmp/foo' `w' open pstack
-file-
onyx:1>
a b or r:
Input(s):
a:
An integer or boolean.
b:
The same type as a.
Output(s):
r:
If a and b are integers, their bitwise or, otherwise their logical or.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the bitwise or of two integers, or the logical or of two booleans.
Example(s):
onyx:0> false false or 1 sprint
false
onyx:0> true false or 1 sprint
true
onyx:0> 5 3 or 1 sprint
7
onyx:0>
- ostack stack:
Input(s):
None.
Output(s):
stack:
A current snapshot (copy) of ostack.
Errors(s):
None.
Description:
Get a current snapshot of ostack.
Example(s):
onyx:0> 1 2 3 ostack pstack
(1 2 3)
3
2
1
onyx:4>
obj depth output -:
Input(s):
obj:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print obj. See Section 2.9.7 for format specifier details.
Example(s):
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 1> output `\n' print flush
___[1 -array- 4]____
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 2> output `\n' print flush
____[1 [2 3] 4]_____
onyx:0> 4242 <$s $+> output `\n' print flush
+4242
onyx:0> `0x' print 4242 <$b 16> output `\n' print flush
0x1092
onyx:0> `0x' 4242 <$b 16> outputs cat <$w 10 $p `.'>
onyx:2>  output `\n' print flush
....0x1092
onyx:0> `0x' print 4242 <$w 8 $p `0' $b 16> output `\n' print flush
0x00001092
onyx:0>
obj flags outputs string:
Input(s):
obj:
An object to print syntactically.
depth:
Formatting flags. See Section 2.9.7 for details on the supported flags.
Output(s):
string:
A formatted string representation of obj. See Section 2.9.7 for format specifier details.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of obj.
Example(s):
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 1> outputs print `\n' print flush
___[1 -array- 4]____
onyx:0> [1 [2 3] 4] <$w 20 $p `_' $j $c $r 2> outputs print `\n' print flush
____[1 [2 3] 4]_____
onyx:0> 4242 <$s $+> outputs print `\n' print flush
+4242
onyx:0> `0x' print 4242 <$b 16> outputs print `\n' print flush
0x1092
onyx:0> `0x' 4242 <$b 16> outputs cat <$w 10 $p `.'> outputs 
onyx:1> print `\n' print flush
....0x1092
onyx:0> `0x' print 4242 <$w 8 $p `0' $b 16> outputs print `\n' print flush
0x00001092
onyx:0>
- outputsdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get outputsdict. See Section 2.9.7 for details on outputsdict.
Example(s):
onyx:0> outputsdict 0 sprint
-dict-
onyx:0>
a b over a b a:
Input(s):
a:
An object.
b:
An object.
Output(s):
a:
An object.
b:
An object.
Errors(s):
stackunderflow.
Description:
Create a duplicate of the second object on ostack and push it onto ostack.
Example(s):
onyx:0> 0 1 2 over pstack
1
2
1
0
onyx:4>
sock peername dict:
Input(s):
sock:
A socket.
Output(s):
dict:
A dictionary of information about the peer end of sock. Depending on the socket family, the following entries may exist:
family:
Socket family.
address:
IPv4 address.
port:
IPv4 port.
path:
Unix-domain socket path.
Errors(s):
argcheck.
ioerror.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Get information about the peer end of sock.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup listen
onyx:1> dup accept
onyx:2> dup peername 1 sprint
<$family $AF_INET $address 2130706433 $port 33746>
onyx:2>
- pid pid:
Input(s):
None.
Output(s):
pid:
Process identifier.
Errors(s):
None.
Description:
Get the process ID of the running process.
Example(s):
onyx:0> pid 1 sprint
80624
onyx:0>
- pipe rfile wfile:
Input(s):
None.
Output(s):
rfile:
A readable file object. Data read from rfile were previously written to wfile.
wfile:
A writeable file object. Data written to wfile can subsequently be read from rfile.
Errors(s):
ioerror.
unregistered.
Description:
Create a pipe.
Example(s):
onyx:0> pipe
onyx:2> $wfile exch def
onyx:1> $rfile exch def
onyx:0> wfile `foo\n' write
onyx:0> wfile flushfile
onyx:0> rfile readline pop 1 sprint
`foo'
onyx:0>
obj pop -:
Input(s):
obj:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Remove the top object from ostack and discard it.
Example(s):
onyx:0> 1 2
onyx:2> pstack
2
1
onyx:2> pop
onyx:1> pstack
1
onyx:1>
<file flags ...> timeout poll [file ...]:
Input(s):
<...>:
A dictionary of file/flags key/value pairs.
file:
A file object.
flags:
A dictionary that contains keys corresponding to file status attributes to poll. The following keys are heeded:
$POLLIN:
Normal or priority data are available for reading.
$POLLRDNORM:
Normal data are available for reading.
$POLLRDBAND:
Priority data are available for reading.
$POLLPRI:
High-priority data are available for reading.
$POLLOUT:
Normal data can be written.
$POLLWRNORM:
Normal data can be written.
$POLLWRBAND:
Priority data can be written.
The values associated with the keys are disregarded, but are set appropriately before poll returns (true/false).
timeout:
Timeout, in milliseconds (maximum $2^{31} - 1$). -1 is treated specially to mean infinite timeout.
Output(s):
[...]:
An array containing a reference to each file in <...> for which a non-zero number of status attributes is set to true. A zero-length array indicates that the poll timed out.
file:
A reference to a file object passed in that has one or more attributes set to true.
Although <...> is not returned, its contents are modified.
flags:
The dictionary passed in. For recognized key that is defined, the associated value is set to true or false, depending on the status of file. In addition, the following keys may defined (if not already defined) with a value of true in the case of errors:
$POLLERR:
An error has occurred.
$POLLHUP:
Hangup has occurred.
$POLLNVAL:
file is not an open file.
Errors(s):
stackunderflow.
rangecheck.
typecheck.
Description:
Wait for any of the flags associated with a file in <...> to be true.
Example(s):
onyx:0> <stdout <$POLLOUT null> stderr <$POLLWRNORM null>> dup 0 poll
onyx:2> 2 sprint 2 sprint
[-file- -file-]
<-file- <$POLLWRNORM true> -file- <$POLLOUT true>>
onyx:0>
- ppid pid:
Input(s):
None.
Output(s):
pid:
Process identifier.
Errors(s):
None.
Description:
Get the process ID of the running process's parent.
Example(s):
onyx:0> ppid 1 sprint
352
onyx:0>
string print -:
Input(s):
string:
A string object.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Print string to stdout.
Example(s):
onyx:0> `Hi\n' print flush
Hi
onyx:0>
- product string:
Input(s):
None.
Output(s):
string:
A string that contains the product name, normally `Canonware Onyx'.
Errors(s):
None.
Description:
Get the product string. The string returned is a reference to the original product string.
Example(s):
onyx:0> product pstack
`Canonware Onyx'
onyx:1>
- pstack -:
Input(s):
None.
Output(s):
None.
Errors(s):
ioerror.
Description:
Syntactically print the elements of ostack, one per line.
Example(s):
onyx:0> `a' 1 mark $foo [1 2 3] (4 5 6)
onyx:6> pstack
(4 5 6)
[1 2 3]
$foo
-mark-
1
`a'
onyx:6>
array index obj put -:
dict key value put -:
string index integer put -:
Input(s):
array:
An array object.
dict:
A dict object.
string:
A string object.
index:
Offset in array or string to put obj or integer, respectively.
key:
An object to use as a key in dict.
obj:
An object to insert into array at offset index.
value:
An object to associate with key in dict.
integer:
The ascii value of a character to insert into string at offset index.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Insert into array, dict, or string.
Example(s):
onyx:0> 3 array dup 1 `a' put 1 sprint
[null `a' null]
onyx:0> dict dup $foo `foo' put 1 sprint
<$foo `foo'>
onyx:0> 3 string dup 1 97 put 1 sprint
`\x00a\x00'
onyx:0>
array index subarray putinterval -:
string index substring putinterval -:
Input(s):
array:
An array object.
string:
A string object.
index:
Offset into array or string to put subarray or substring, respectively.
subarray:
An array object to put into array at offset index. When inserted subarray must not extend past the end of array.
substring:
A string object to put into string at offset index. When inserted substring must not extend past the end of string.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Replace a portion of array or string.
Example(s):
onyx:0> 4 array dup 1 [`a' `b'] putinterval 1 sprint
[null `a' `b' null]
onyx:0> 4 string dup 1 `ab' putinterval 1 sprint
`\x00ab\x00'
onyx:0>
- pwd path:
Input(s):
None.
Output(s):
path:
A string that represents the present working directory.
Errors(s):
invalidaccess.
Description:
Push a string onto ostack that represents the present working directory.
Example(s):
onyx:0> pwd
onyx:1> pstack
`/usr/local/bin'
onyx:1>
- quit -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Unwind the execution stack to the innermost start context. Under normal circumstances, there is always at least one such context.
Example(s):
onyx:0> stdin cvx start
onyx:0> estack 1 sprint
(--start-- -file- --start-- -file- --estack--)
onyx:0> quit
onyx:0> estack 1 sprint
(--start-- -file- --estack--)
onyx:0>
- rand integer:
Input(s):
None.
Output(s):
integer:
A pseudo-random non-negative integer, with 63 bits of psuedo-randomness.
Errors(s):
None.
Description:
Return a pseudo-random integer.
Example(s):
onyx:0> 0 srand
onyx:0> rand 1 sprint
9018578418316157091
onyx:0> rand 1 sprint
8979240987855095636
onyx:0>
file read integer boolean:
file string read substring boolean:
Input(s):
file:
A file object.
string:
A string object.
Output(s):
integer:
An integer that represents the ascii value of a character that was read from file.
substring:
A substring of string that contains data read from file.
boolean:
If true, end of file reached during read.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Read from file.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> dup 0 seek
onyx:1> dup 10 string read
onyx:3> pop 1 sprint
`Hello\n'
file readline string boolean:
Input(s):
file:
A file object.
Output(s):
string:
A string that contains a line of text from file.
boolean:
If true, end of file reached during read.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Read a line of text from file. Lines are separated by ``\n'' or ``\r\n'', which is removed. The last line in a file may not have a newline at the end.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup `Goodbye\n' write
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1> dup readline 1 sprint 1 sprint
false
`Goodbye'
onyx:1> dup readline 1 sprint 1 sprint
true
`'
onyx:1>
linkname readlink string:
Input(s):
linkname:
A string that represents the path of a symbolic link.
Output(s):
string:
A string that represents the link data associated with linkname.
Errors(s):
invalidaccess.
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Get the data for the symbolic link at linkname.
Example(s):
onyx:0> `bar' `foo' symlink
onyx:0> `foo' readlink 1 sprint
`bar'
onyx:0>
- realtime nsecs:
Input(s):
None.
Output(s):
nsecs:
Number of nanoseconds since the epoch (midnight on 1 January 1970).
Errors(s):
None.
Description:
Get the number of nanoseconds since the epoch.
Example(s):
onyx:0> realtime 1 sprint
993539837806479000
onyx:0>
sock string flags recv substring:
sock string recv substring:
Input(s):
sock:
A socket.
string:
A string to use as a buffer for the message being received.
flags:
An array of flag names. The following flags are supported:
$MSG_OOB
$MSG_PEEK
$MSG_WAITALL
Output(s):
substring:
A substring of string that contains message data.
Errors(s):
argcheck.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Example(s):
onyx:0> $AF_INET $SOCK_DGRAM socket
onyx:1> dup `localhost' 7777 bindsocket
onyx:1> dup true setnonblocking
onyx:1> dup 10 string recv
onyx:2> 1 sprint
`hello'
onyx:1>
old new rename -:
Input(s):
old:
A string object that represents a file path.
new:
A string object that represents a file path.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
limitcheck.
stackunderflow.
typecheck.
undefinedfilename.
Description:
Rename a file or directory from old to new.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir 
onyx:0> `/tmp/tdir' `/tmp/ndir' rename
onyx:0> `/tmp/ndir' {1 sprint} dirforeach
`.'
`..'
onyx:0>
count proc repeat -:
Input(s):
count:
Number of times to evaluate proc (non-negative).
proc:
An object to evaluate.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Evaluate proc count times. This operator supports the exit operator.
Example(s):
onyx:0> 3 {`hi' 1 sprint} repeat
`hi'
`hi'
`hi'
onyx:0>
file require -:
Input(s):
file:
A string that represents a module filename.
Output(s):
None.
Errors(s):
invalidfileaccess.
stackunderflow.
typecheck.
undefined.
undefinedfilename.
Description:
Search for and evaluate an Onyx source file. The file is searched for by catenating a prefix, a ``/'', and file to form a file path. Prefixes are tried in the following order:
  1. The ordered elements of the rpath_pre array, which is defined in onyxdict.
  2. If defined, the ordered elements of the ONYX_RPATH environment variable, which is a colon-separated list.
  3. The ordered elements of the rpath_post array, which is defined in onyxdict.
Example(s):
onyx:0> `modgtk/modgtk_defs.nx' require
onyx:0>
path rmdir -:
Input(s):
path:
A string object that represents a directory path.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
unregistered.
Description:
Remove an empty directory.
Example(s):
onyx:0> `/tmp/tdir' 8@755 mkdir
onyx:0> `/tmp/tdir' rmdir
onyx:0>
region count amount roll rolled:
Input(s):
region:
0 or more objects to be rolled.
count:
Number of objects in region.
amount:
Amount by which to roll. If positive, roll upward. If negative, roll downward.
Output(s):
rolled:
Rolled version of region.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Roll the top count objects on ostack (not counting count and amount) by amount positions. A positive amount indicates an upward roll, whereas a negative amount indicates a downward roll.
Example(s):
onyx:0> 3 2 1 0 
onyx:4> pstack
0
1
2
3
onyx:4> 3 1 roll
onyx:4> pstack
1
2
0
3
onyx:4> 3 -2 roll
onyx:4> pstack
2
0
1
3
onyx:4> 4 0 roll
onyx:4> pstack
2
0
1
3
onyx:4>
a round r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer round of a.
Errors(s):
stackunderflow.
typecheck.
Description:
Round a to the nearest integer and return the result.
Example(s):
onyx:0> -1.51 round 1 sprint
-2
onyx:0> -1.49 round 1 sprint
-1
onyx:0> 0 round 1 sprint
0
onyx:0> 1.49 round 1 sprint
1
onyx:0> 1.51 round 1 sprint
2
onyx:0>
...amount rot ...:
Input(s):
...:
One or more objects.
amount:
Number of positions to rotate the stack upward. A negative value causes downward rotation.
Output(s):
...:
One or more objects.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate the stack contents up amount positions.
Example(s):
onyx:0> 1 2 3 4 5 2 rot pstack clear
3
2
1
5
4
onyx:0> 1 2 3 4 5 -2 rot pstack clear
2
1
5
4
3
onyx:0>
stack sadn -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate the contents of stack down one position.
Example(s):
onyx:0> (1 2 3 4) dup sadn 1 sprint
(2 3 4 1)
onyx:0>
stack saup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate the contents of stack up one position.
Example(s):
onyx:0> (1 2 3 4) dup saup 1 sprint
(4 1 2 3)
onyx:0>
stack sbdup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Duplicate the bottom object on stack and push it onto stack.
Example(s):
onyx:0> (2 1 0) dup sbdup pstack
(2 1 0 2)
onyx:1>
stack sbpop obj:
Input(s):
stack:
A stack object.
Output(s):
obj:
An object.
Errors(s):
stackunderflow.
typecheck.
Description:
Pop obj off the bottom of stack.
Example(s):
onyx:0> (1 2 3) dup sbpop pstack
1
(2 3)
onyx:2>
stack obj sbpush -:
Input(s):
stack:
A stack object.
obj:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Push obj onto the bottom of stack.
Example(s):
onyx:0> (0) dup 1 sbpush
onyx:1> pstack
(1 0)
onyx:1>
stack sclear -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Remove all objects on stack.
Example(s):
onyx:0> (1 2 3 4) dup sclear pstack
()
onyx:1>
stack scleartomark -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
unmatchedmark.
Description:
Remove objects from stack down to and including the topmost mark.
Example(s):
onyx:0> (3 mark 1 0) dup scleartomark pstack
(3)
onyx:1>
stack scount count:
Input(s):
stack:
A stack object.
Output(s):
count:
The number of objects on stack.
Errors(s):
stackunderflow.
typecheck.
Description:
Get the number of objects on stack.
Example(s):
onyx:0> (1 2) scount 1 sprint
2
onyx:0>
stack scounttomark count:
Input(s):
stack:
A stack object.
Output(s):
count:
The depth of the topmost mark on stack.
Errors(s):
stackunderflow.
typecheck.
unmatchedmark.
Description:
Get the depth of the topmost mark on stack.
Example(s):
onyx:0> (3 mark 1 0) scounttomark 1 sprint
2
onyx:0>
stack sdn -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate the top three objects on stack down one position.
Example(s):
onyx:0> (3 2 1 0) dup sdn pstack
(3 1 0 2)
onyx:1>
stack sdup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Duplicate the top object on stack and push it onto stack.
Example(s):
onyx:0> (1) dup sdup 1 sprint
(1 1)
onyx:0>
string pattern search post pattern pre true:
string pattern search string false:
Input(s):
string:
A string object.
pattern:
A string that represents a substring to search for in string.
Output(s):
post:
The substring of string that follows the match.
pattern:
The substring of string that matches the input pattern.
pre:
The substring of string that precedes the match.
true:
Success.
string:
The same object as the input string.
false:
Failure.
Errors(s):
stackunderflow.
typecheck.
Description:
Search for the first instance of pattern in string, and if found, return substrings that partition string into pre, pattern, and post.
Example(s):
onyx:0> `abcabc' `ab' search pstack clear
true
`'
`ab'
`cabc'
onyx:0> `abcabc' `ca' search pstack clear
true
`ab'
`ca'
`bc'
onyx:0> `abcabc' `cb' search pstack clear
false
`abcabc'
onyx:0>
file offset seek -:
Input(s):
file:
A file object.
offset:
Offset in bytes from the beginning of file to move the file position pointer to.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Move the file position pointer for file to offset.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup 0 seek
onyx:1> readline pstack
false
`Hello'
onyx:2>
- self thread:
Input(s):
None.
Output(s):
thread:
A thread object that corresponds to the running thread.
Errors(s):
None.
Description:
Get a thread object for the running thread.
Example(s):
onyx:0> self 1 sprint
-thread-
onyx:0>
sock mesg flags send nsend:
sock mesg send nsend:
Input(s):
sock:
A socket.
mesg:
A message string.
flags:
An array of flag names. The following flags are supported:
$MSG_OOB
$MSG_PEEK
$MSG_WAITALL
Output(s):
nsend:
Number of bytes of mesg actually sent.
Errors(s):
argcheck.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Send a message.
Example(s):
onyx:0> $AF_INET $SOCK_DGRAM socket
onyx:1> dup `localhost' 7777 connect
onyx:1> dup `hello' send
onyx:2> 1 sprint
5
onyx:1>
service serviceport port:
Input(s):
service:
A string that represents a network service name.
Output(s):
port:
The port number corresponding to service, or 0 if the service is unknown.
Errors(s):
stackunderflow.
typecheck.
Description:
Example(s):
onyx:0> `ftp' serviceport 1 sprint
21
onyx:0>
gid setegid boolean:
Input(s):
gid:
A group ID.
Output(s):
boolean:
If false, success, otherwise failure.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's effective group ID to gid.
Example(s):
onyx:0> 1001 setegid 1 sprint
false
onyx:0> 0 setegid 1 sprint
true
onyx:0>
key val setenv -:
Input(s):
key:
A name object.
val:
A value to associate with key.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set an environment variable named key and associate val with it. If val is not a string, it is converted to a string using the cvs operator before the environment variable is set. A corresponding entry is also created in the envdict dictionary.
Example(s):
onyx:0> $foo `foo' setenv
onyx:0> envdict $foo known 1 sprint
true
onyx:0> envdict $foo get 1 sprint
`foo'
onyx:0> $foo unsetenv
onyx:0> envdict $foo known 1 sprint
false
onyx:0>
uid seteuid boolean:
Input(s):
uid:
A user ID.
Output(s):
boolean:
If false, success, otherwise failure.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's effective user ID to uid.
Example(s):
onyx:0> 1001 seteuid 1 sprint
false
onyx:0> 0 seteuid 1 sprint
true
onyx:0>
gid setgid boolean:
Input(s):
gid:
A group ID.
Output(s):
boolean:
If false, success, otherwise failure.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's group ID to gid.
Example(s):
onyx:0> 1001 setgid 1 sprint
false
onyx:0> 0 setgid 1 sprint
true
onyx:0>
file setgstderr -:
Input(s):
file:
A file to set the global stderr to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the global stderr to file. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> `/tmp/stderr' `w' open dup 0 setiobuf setgstderr
onyx:0> () {stderr `Some text\n' write} thread join
onyx:0> `/tmp/stderr' `r' open readline pop 1 sprint
`Some text'
onyx:0>
file setgstdin -:
Input(s):
file:
A file to set the global stdin to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the global stdin to file. See Section 2.4 for standard I/O details.
Example(s):
Under normal interactive operation, stdin is pushed onto estack during interpreter initialization and evaluated until EOF is reached. Therefore, changing stdin has no effect on the file descriptor already on estack. The following example recursively evaluates stdin after redefining it.
lawine:~> cat /tmp/stdin
1 2 3 pstack
lawine:~> onyx 
Canonware Onyx, version 3.1.0.
onyx:0> `/tmp/stdin' `r' open cvx setgstdin
onyx:0> () {stdin eval} thread join
3
2
1
onyx:0>
file setgstdout -:
Input(s):
file:
A file to set the global stdout to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the global stdout to file. See Section 2.4 for standard I/O details.
Example(s):
In the following example, the prompt continues to be printed, even though stdout has been redefined, because the prompt module was initialized to print to file descriptor 1. This demonstrates the only known exception in the stock Onyx interpreter where redefining stdout will not redirect output.
onyx:0> `/tmp/stdout' `w' open dup 0 setiobuf setgstdout
onyx:0> () {`Some text\n' print} thread join
onyx:0> `/tmp/stdout' `r' open readline pop 1 sprint
`Some text'
onyx:0>
file count setiobuf -:
Input(s):
file:
A file object.
count:
The size in bytes to set the I/O buffer associated with file to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the size of the I/O buffer associated with file.
Example(s):
onyx:0> stdout iobuf 1 sprint
512
onyx:0> stdout 0 setiobuf
onyx:0> stdout iobuf 1 sprint
0
onyx:0>
boolean setlocking -:
Input(s):
boolean:
A boolean to set the implicit locking mode to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the current implicit locking mode. See Section 2.7.1 for implicit synchronization details.
Example(s):
onyx:0> currentlocking 1 sprint
false
onyx:0> true setlocking
onyx:0> currentlocking 1 sprint
true
onyx:0>
file boolean setnonblocking -:
Input(s):
file:
A file object.
boolean:
Non-blocking mode to set file to.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Set non-blocking mode for file to boolean.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup nonblocking 1 sprint
false
onyx:1> dup true setnonblocking
onyx:1> dup nonblocking 1 sprint
true
onyx:1>
sock level optname optval setsockopt -:
sock optname optval setsockopt -:
Input(s):
sock:
A socket.
level:
Level at which to set the socket option. If not specified, $SOL_SOCKET is used.
optname:
Name of option to set the value of. The following option names are supported:
$SO_DEBUG
$SO_REUSEADDR
$SO_REUSEPORT
$SO_KEEPALIVE
$SO_DONTROUTE
$SO_BROADCAST
$SO_OOBINLINE
$SO_SNDBUF
$SO_RCVBUF
$SO_SNDLOWAT
$SO_RCVLOWAT
$SO_TYPE
$SO_ERROR:
optval is an integer.
$SO_LINGER:
optval is a dictionary, and the following entries are defined:
$on:
Boolean.
$time:
Linger time in seconds.
$SO_SNDTIMEO
$SO_RCVTIMEO:
optval is an integer, in nanoseconds.
optval:
Value to associate with optname.
Output(s):
None.
Errors(s):
argcheck.
stackunderflow.
typecheck.
unregistered.
Description:
Set a socket option.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup $SO_OOBINLINE sockopt 1 sprint
0
onyx:1> dup $SO_OOBINLINE 1 setsockopt 
onyx:1> dup $SO_OOBINLINE sockopt 1 sprint
1
onyx:1>
file setstderr -:
Input(s):
file:
A file to set the calling thread's stderr to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the thread's stderr to file. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> `/tmp/stderr' `w' open dup 0 setiobuf setstderr
onyx:0> stderr `Some text\n' write
onyx:0> `/tmp/stderr' `r' open readline pop 1 sprint
`Some text'
onyx:0>
file setstdin -:
Input(s):
file:
A file to set the calling thread's stdin to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the thread's stdin to file. See Section 2.4 for standard I/O details.
Example(s):
Under normal interactive operation, stdin is pushed onto estack during interpreter initialization and evaluated until EOF is reached. Therefore, changing stdin has no effect on the file descriptor already on estack. The following example recursively evaluates stdin after redefining it.
lawine:~> cat /tmp/stdin
1 2 3 pstack
lawine:~> onyx 
Canonware Onyx, version 3.1.0.
onyx:0> `/tmp/stdin' `r' open cvx setstdin
onyx:0> stdin eval
3
2
1
onyx:3>
file setstdout -:
Input(s):
file:
A file to set the calling thread's stdout to.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the thread's stdout to file. See Section 2.4 for standard I/O details.
Example(s):
In the following example, the prompt continues to be printed, even though stdout has been redefined, because the prompt module was initialized to print to file descriptor 1. This demonstrates the only known exception in the stock Onyx interpreter where redefining stdout will not redirect output.
onyx:0> `/tmp/stdout' `w' open dup 0 setiobuf setstdout
onyx:0> `Some text\n' print
onyx:0> gstdout setstdout
onyx:0> `/tmp/stdout' `r' open readline pop 1 sprint
`Some text'
onyx:0>
uid setuid boolean:
Input(s):
uid:
A user ID.
Output(s):
boolean:
If false, success, otherwise failure.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Set the process's user ID to uid.
Example(s):
onyx:0> 1001 setuid 1 sprint
false
onyx:0> 0 setuid 1 sprint
true
onyx:0>
stack sexch -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Exchange the top two objects on stack.
Example(s):
onyx:0> (1 2 3) dup sexch pstack
(1 3 2)
onyx:1>
- shift -:
Input(s):
a:
An integer.
shift:
An integer that represents a bitwise shift amount. Negative means right shift, and positive means left shift.
Output(s):
r:
a shifted by shift bits.
Errors(s):
stackunderflow.
typecheck.
Description:
Shift an integer bitwise.
Example(s):
onyx:0> 4 1 shift 1 sprint
8
onyx:0> 4 -1 shift 1 sprint
2
onyx:0>
stack index sibdup -:
Input(s):
stack:
A stack object.
index:
Offset from bottom of stack, counting from 0, of the object to duplicate.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on stack that is at offset index from the bottom of stack and push it onto stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sibdup pstack
(3 2 1 0 1)
onyx:1>
stack index sibpop obj:
Input(s):
stack:
A stack object.
index:
Offset from bottom of stack, counting from 0, of the object to remove from stack.
Output(s):
obj:
An object removed from stack.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the obj from stack that is at offset index from the bottom of stack.
Example(s):
onyx:0> (0 1 2 3) dup 2 sibpop pstack
2
(0 1 3)
onyx:2>
stack index sidup -:
Input(s):
stack:
A stack object.
index:
Depth (count starts at 0) of the object to duplicate in stack.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on stack at depth index and push it onto stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sidup
onyx:1> 1 sprint
(3 2 1 0 2)
onyx:0>
condition signal -:
Input(s):
condition:
A condition object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Signal a thread that is waiting on condition. If there are no waiters, this operator has no effect.
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch signal unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> wait unlock join
onyx:0>
a sin r:
Input(s):
a:
An integer or real.
Output(s):
r:
Sine of a in radians.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the sine of a in radians.
Example(s):
onyx:0> 0 sin 1 sprint
0.000000e+00
onyx:0> 1.570796 sin 1 sprint
1.000000e+00
onyx:0> 0.7853982 sin 1 sprint
7.071068e-01
onyx:0>
stack index sipop obj:
Input(s):
stack:
A stack object.
index:
Offset from top of stack, counting from 0, of the object to remove from stack.
Output(s):
obj:
An object removed from stack.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Remove the obj at index from stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sipop pstack
2
(3 1 0)
onyx:2>
stack count snbpop array:
Input(s):
stack:
A stack object.
count:
Number of objects to pop off the bottom of stack.
Output(s):
array:
An array of objects popped off the bottom of stack, with the same object ordering as when on stack.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Pop count objects off the bottom of stack and put them into an array.
Example(s):
onyx:0> (1 2 3 4) dup 2 snbpop pstack
[1 2]
(3 4)
onyx:2>
stack count sndn -:
Input(s):
stack:
A stack object.
count:
Number of objects on stack to rotate down one position.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate count objects on stack down one position.
Example(s):
onyx:0> (5 4 3 2 1 0) dup 4 sndn pstack
(5 4 2 1 0 3)
onyx:1>
stack count sndup -:
Input(s):
stack:
A stack object.
count:
Number of objects on stack to duplicate.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create duplicates of the top count objects on stack.
Example(s):
onyx:0> (3 2 1 0) dup 2 sndup pstack
(3 2 1 0 1 0)
onyx:1>
stack snip obj:
Input(s):
stack:
A stack object.
Output(s):
obj:
The object that was the second to top object on stack.
Errors(s):
stackunderflow.
typecheck.
Description:
Remove the second to top object from stack.
Example(s):
onyx:0> (2 1 0) dup snip pstack
1
(2 0)
onyx:2>
stack count snpop array:
Input(s):
stack:
A stack object.
count:
Number of objects to pop off of stack.
Output(s):
array:
An array of objects popped off of stack, with the same object ordering as when on stack.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Pop count objects off of stack and put them into an array.
Example(s):
onyx:0> (1 2 3 4) dup 2 snpop pstack
[3 4]
(1 2)
onyx:2>
stack count snup -:
Input(s):
stack:
A stack object.
count:
Number of objects on stack to rotate up one position.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Rotate count objects on stack up one position.
Example(s):
onyx:0> (5 4 3 2 1 0) dup 4 snup pstack
(5 4 0 3 2 1)
onyx:1>
family type proto socket sock:
family type socket sock:
Input(s):
family:
The name of a socket address family, either $AF_INET or $AF_LOCAL.
type:
The name of a socket type, either $SOCK_STREAM or $SOCK_DGRAM.
proto:
The name of a socket protocol. This argument is not useful, given the current limited choice of address families.
Output(s):
sock:
A socket.
Errors(s):
argcheck.
invalidaccess.
stackunderflow.
typecheck.
unregistered.
Description:
Create a socket.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> $AF_LOCAL $SOCK_DGRAM socket
onyx:2>
family type proto socketpair sock sock:
family type socketpair sock sock:
Input(s):
family:
The name of a socket address family, either $AF_INET or $AF_LOCAL.
type:
The name of a socket type, either $SOCK_STREAM or $SOCK_DGRAM.
proto:
The name of a socket protocol. This argument is not useful, given the current limited choice of address families.
Output(s):
sock:
A connected socket. There are no functional differences between the two sockets that are returned.
Errors(s):
argcheck.
invalidaccess.
stackunderflow.
typecheck.
unregistered.
Description:
Create a pair of sockets that are connected to each other.
Example(s):
onyx:0> $AF_LOCAL $SOCK_STREAM socketpair
onyx:2> pstack
-file-
-file-
onyx:2>
sock sockname dict:
Input(s):
sock:
A socket.
Output(s):
dict:
A dictionary of information about sock. Depending on the socket family, the following entries may exist:
family:
Socket family.
address:
IPv4 address.
port:
IPv4 port.
path:
Unix-domain socket path.
Errors(s):
argcheck.
ioerror.
neterror.
stackunderflow.
typecheck.
unregistered.
Description:
Get information about sock.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup `localhost' bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_INET $address 2130706433 $port 33745>
onyx:1> close
onyx:0> $AF_LOCAL $SOCK_STREAM socket
onyx:1> dup `/tmp/socket' bindsocket
onyx:1> dup sockname 1 sprint
<$family $AF_LOCAL $path `/tmp/socket'>
onyx:1>
sock level optname sockopt optval:
sock optname sockopt optval:
Input(s):
sock:
A socket.
level:
Level at which to get the socket option. If not specified, $SOL_SOCKET is used.
optname:
Name of option to get the value of. The following option names are supported:
$SO_DEBUG
$SO_REUSEADDR
$SO_REUSEPORT
$SO_KEEPALIVE
$SO_DONTROUTE
$SO_BROADCAST
$SO_OOBINLINE
$SO_SNDBUF
$SO_RCVBUF
$SO_SNDLOWAT
$SO_RCVLOWAT
$SO_TYPE
$SO_ERROR:
optval is an integer.
$SO_LINGER:
optval is a dictionary, and the following entries are defined:
$on:
Boolean.
$time:
Linger time in seconds.
$SO_SNDTIMEO
$SO_RCVTIMEO:
optval is an integer, in nanoseconds.
Output(s):
optval:
Value associated with optname.
Errors(s):
argcheck.
stackunderflow.
typecheck.
unregistered.
Description:
Get a socket option.
Example(s):
onyx:0> $AF_INET $SOCK_STREAM socket
onyx:1> dup $SO_SNDBUF sockopt 1 sprint
16384
onyx:1>
stack sover -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a duplicate of the second object on stack and push it onto stack.
Example(s):
onyx:0> (2 1 0) dup sover pstack
(2 1 0 1)
onyx:1>
stack spop obj:
Input(s):
stack:
A stack object.
Output(s):
obj:
The object that was popped off of stack.
Errors(s):
stackunderflow.
typecheck.
Description:
Pop an object off of stack and push it onto ostack.
Example(s):
onyx:0> (1 2) dup spop
onyx:2> pstack
2
(1)
onyx:2>
obj depth sprint -:
Input(s):
obj:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print obj. See Section 2.9.8 for printing details.
Example(s):
onyx:0> [1 [2 3] 4]
onyx:1> dup 0 sprint
-array-
onyx:1> dup 1 sprint
[1 -array- 4]
onyx:1> dup 2 sprint
[1 [2 3] 4]
onyx:1>
obj depth sprints string:
Input(s):
obj:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
string:
A syntactical string representation of obj. See Section 2.9.8 for printing details.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of obj.
Example(s):
onyx:0> [1 [2 3] 4]
onyx:1> dup 0 sprints print `\n' print flush
-array-
onyx:1> dup 1 sprints print `\n' print flush
[1 -array- 4]
onyx:1> dup 2 sprints print `\n' print flush
[1 [2 3] 4]
onyx:1>
- sprintsdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get sprintsdict. See Section 2.9.8 for details on sprintsdict.
Example(s):
onyx:0> sprintsdict 0 sprint
-dict-
onyx:0>
stack obj spush -:
Input(s):
stack:
A stack object.
obj:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Push obj onto stack.
Example(s):
onyx:0> (0) dup 1 spush
onyx:1> pstack
(0 1)
onyx:1>
a sqrt r:
Input(s):
a:
A non-negative integer or real.
Output(s):
r:
Square root of a.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Return the square root of a.
Example(s):
onyx:0> 4 sqrt 1 sprint
2.000000e+00
onyx:0> 2.0 sqrt 1 sprint
1.414214e+00
onyx:0>
seed srand -:
Input(s):
seed:
A non-negative integer.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Seed the pseudo-random number generator with seed.
Example(s):
onyx:0> 5 srand
onyx:0>
stack count amount sroll -:
Input(s):
stack:
A stack object.
count:
Number of objects to roll in stack.
amount:
Amount by which to roll. If positive, roll upward. If negative, roll downward.
Output(s):
None.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Roll the top count objects on stack by amount positions. A positive amount indicates an upward roll, whereas a negative amount indicates a downward roll.
Example(s):
onyx:0> (3 2 1 0)
onyx:1> dup 3 1 sroll pstack
(3 0 2 1)
onyx:1> dup 3 -2 sroll pstack
(3 1 0 2)
onyx:1> dup 4 0 sroll pstack
(3 1 0 2)
onyx:1>
stack amount srot -:
Input(s):
stack:
One or more objects.
amount:
Number of positions to rotate stack upward. A negative value causes downward rotation.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate stack up count positions.
Example(s):
onyx:0> (1 2 3 4 5) dup 2 srot 1 sprint
(4 5 1 2 3)
onyx:0> (1 2 3 4 5) dup -2 srot 1 sprint
(3 4 5 1 2)
onyx:0>
- stack stack:
Input(s):
None.
Output(s):
stack:
An empty stack object.
Errors(s):
None.
Description:
Create a new stack object and push it onto ostack.
Example(s):
onyx:0> stack
onyx:1> pstack
()
obj start -:
Input(s):
obj:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Evaluate obj. This operator provides a context that silently terminates execution stack unwinding due to the exit , quit , and stop operators.
Example(s):
onyx:0> stdin cvx start
onyx:0> quit
onyx:0>
file/filename status dict:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
Output(s):
dict:
A dictionary that contains the following entries:
dev:
Inode's device.
ino:
Inode's number.
mode:
Inode permissions.
nlink:
Number of hard links.
uid:
User ID of the file owner.
gid:
Group ID of the file owner.
rdev:
Device type.
size:
File size in bytes.
atime:
Time of last access, in nanoseconds since the epoch.
mtime:
Time of last modification, in nanoseconds since the epoch.
ctime:
Time of last file status change, in nanoseconds since the epoch.
blksize:
Optimal block size for I/O.
blocks:
Number of blocks allocated.
Errors(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
unregistered.
Description:
Get status information about a file.
Example(s):
onyx:0> `/tmp' status 1 sprint
<$dev 134405 $ino 2 $mode 17407 $nlink 5 $uid 0 $gid 0 $rdev 952 $size 3584
$atime 994883041000000000 $mtime 994883041000000000 $ctime 994883041000000000
$blksize 0 $blocks 8>
onyx:0>
- stderr file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the calling thread's stderr.
Errors(s):
None.
Description:
Get the thread's stderr. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> stderr pstack
-file-
onyx:1>
- stdin file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the calling thread's stdin.
Errors(s):
None.
Description:
Get the thread's stdin. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> stdin pstack
-file-
onyx:1>
- stdout file:
Input(s):
None.
Output(s):
file:
A file object corresponding to the calling thread's stdout.
Errors(s):
None.
Description:
Get the thread's stdout. See Section 2.4 for standard I/O details.
Example(s):
onyx:0> stdout pstack
-file-
onyx:1>
- stop -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Unwind the execution stack to the innermost stopped or start context.
Example(s):
onyx:0> {stop} stopped 1 sprint
true
onyx:0>
obj stopped boolean:
Input(s):
obj:
An object to evaluate.
Output(s):
boolean:
True if stop operator was executed, false otherwise.
Errors(s):
invalidexit.
stackunderflow.
Description:
Evaluate obj. This operator provides a context that terminates execution stack unwinding due to the stop . It will also terminate execution stack unwinding due to the exit operator, but will throw an invalidexit error, then do the equivalent of calling quit .
Example(s):
onyx:0> {stop} stopped 1 sprint
true
onyx:0> {} stopped 1 sprint
false
onyx:0>
length string string:
Input(s):
length:
Non-negative number of bytes.
Output(s):
string:
A string of length bytes.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a string of length bytes. The bytes are initialized to 0.
Example(s):
onyx:0> 3 string 1 sprint
`\x00\x00\x00'
onyx:0>
onyx:0> 0 string 1 sprint
`'
onyx:0>
stack stuck -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Tuck duplicate of top object on stack under second object on stack.
Example(s):
onyx:0> (2 1 0) dup stuck pstack
(2 0 1 0)
onyx:1>
a b sub r:
Input(s):
a:
An integer or real.
b:
An integer or real.
Output(s):
r:
The value of b subtracted from a.
Errors(s):
stackunderflow.
typecheck.
Description:
Subtract b from a and return the result.
Example(s):
onyx:0> 5 3 sub 1 sprint
2
onyx:0> -3 4 sub 1 sprint
-7
onyx:0> 5.1 1.1 sub 1 sprint
4.000000e+00
onyx:0> 5 1.0 sub 1 sprint
4.000000e+00
onyx:0> -3.0 4.1 sub 1 sprint
-7.100000e+00
onyx:0>
stack sunder -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a duplicate of the second object on stack and put it under the top object on stack.
Example(s):
onyx:0> (2 1 0) dup sunder pstack
(2 1 1 0)
onyx:1>
stack sup -:
Input(s):
stack:
A stack object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Rotate the top three objects on stack up one position.
Example(s):
onyx:0> (3 2 1 0) dup sup pstack
(3 0 2 1)
onyx:1>
filename linkname symlink -:
Input(s):
filename:
A string that represents a filename.
linkname:
A string that represents a filename.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Create a symbolic link from linkname to filename.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> close
onyx:0> `/tmp/foo' `/tmp/bar' symlink
onyx:0> `/tmp/bar' `r' open
onyx:1> readline
onyx:2> pstack
false
`Hello'
onyx:2>
args system status:
Input(s):
args:
An array of strings. The first string in args is the path of the program to invoke, and any additional array elements are passed as command line arguments to the invoked program.
Output(s):
status:
Exit code of terminated process. A negative value indicates that the process was terminated by a signal (use the neg operator to get the signal number), and a non-negative value is the exit code of a program that terminated normally.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Execute a program as a child process and wait for it to terminate.
Example(s):
onyx:0> [`/usr/bin/which' `onyx'] system
/usr/local/bin/onyx
onyx:1> 1 sprint
0
onyx:0>
- systemdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get systemdict. See Section 2.9.9 for details on systemdict.
Example(s):
onyx:0> systemdict 0 sprint
-dict-
onyx:0>
file tell offset:
Input(s):
fil:
A file object.
Output(s):
offset:
Offset of the file position pointer for file.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Get the file position pointer offset for file.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup tell 1 sprint
0
onyx:1> dup `Hello\n' write
onyx:1> dup tell 1 sprint
6
onyx:1>
file/filename flag test boolean:
Input(s):
file:
A file object.
filename:
A string that represents a filename.
flag:
A single-character string that represents the test to do on file or filename:
`b':
Block special device?
`c':
Character special device?
`d':
Directory?
`e':
Exists?
`f':
Regular file?
`g':
Setgid?
`k':
Sticky?
`p':
Named pipe?
`r':
Readable?
`s':
Size greater than 0?
`t':
tty?
`u':
Setuid?
`w':
Write bit set?
`x':
Executable bit set?
`L':
Symbolic link?
`O':
Owner matches effective uid?
`G':
Group matches effective gid?
`S':
Socket?
Output(s):
boolean:
If true, the test evaluated to true; false otherwise.
Errors(s):
invalidfileaccess.
ioerror.
rangecheck.
stackunderflow.
typecheck.
unregistered.
Description:
Test a file for an attribute.
Example(s):
onyx:0> `/blah' `e' test 1 sprint
false
onyx:0> `/tmp' `e' test 1 sprint
true
onyx:0>
stack entry thread thread:
Input(s):
stack:
A stack that contains the contents for the new thread's ostack.
entry:
An initial object to execute in the new thread.
Output(s):
thread:
A thread object that corresponds to the new thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Create and run a new thread.
Example(s):
onyx:0> (1 2) {add 1 sprint} thread join `Done\n' print flush
3
Done
onyx:0>
thread threaddstack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The dictionary stack belonging to thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Get a reference to the dictionary stack belonging to thread.
Example(s):
onyx:0> self threaddstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
thread threadestack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The execution stack belonging to thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Get a reference to the execution stack belonging to thread.
Example(s):
onyx:0> self threadestack 1 sprint
(-file- -array- --eval-- --ifelse-- -array- --for-- -array-)
onyx:0>
thread threadistack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The index stack belonging to thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Get a reference to the index stack belonging to thread.
Example(s):
onyx:0> self threadistack 1 sprint
(0 0 0 0 7 0 3)
onyx:0>
thread threadostack stack:
Input(s):
thread:
A thread object.
Output(s):
stack:
The operand stack belonging to thread.
Errors(s):
stackunderflow.
typecheck.
Description:
Get a reference to the operand stack belonging to thread.
Example(s):
onyx:0> self threadostack 1 sprint
(-stack- -stack- -stack- -stack-)
onyx:0>
- threadsdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary. Each key is a thread reference. By default, each value is null, but this need not be so, and the value can be redefined for debugging purposes.
Errors(s):
None.
Description:
Get a dictionary containing references to all threads.
Example(s):
onyx:0> threadsdict 1 sprint
<-thread- null>
onyx:0>
name throw obj:
Input(s):
name:
The name of an error.
Output(s):
obj:
The object that was being executed when the error was thrown.
Errors(s):
stackunderflow.
typecheck.
undefined.
Description:
Throw an error, using the following steps:
  1. Set newerror in the currenterror dictionary to true.
  2. Set errorname in the currenterror dictionary to name.
  3. Set ostack, dstack, estack, and istack in the currenterror dictionary to be current stack snapshots.
  4. Push the object that was being executed before throw was called onto ostack.
  5. If there is an error handler in the errordict dictionary that corresponds to name, evaluate it. Otherwise, evaluate errordict's handleerror and stop operators.
Example(s):
onyx:0> $unregistered throw
Error $unregistered
ostack: ()
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..1):
0:      -file-
1:      --start--
onyx:1> pstack
-file-
onyx:1>
condition mutex timeout timedwait boolean:
Input(s):
condition:
A condition object.
mutex:
A mutex object that this thread currently owns.
timeout:
Minimum number of nanoseconds to wait for condition.
Output(s):
boolean:
If false, success, otherwise timeout.
Errors(s):
stackunderflow.
typecheck.
Description:
Wait on condition for at least timeout nanoseconds. mutex is atomically released when the current thread blocks, then acquired again before the current thread runs again. Using a mutex that the current thread does not own will result in undefined behavior (likely crash).
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch signal unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> 1000000000 timedwait 1 sprint unlock join
false
onyx:0> mutex condition 1 idup dup lock 1000000000 timedwait 1 sprint unlock
true
onyx:0>
file/string token false:
file/string token file/substring obj true:
Input(s):
file:
A file that is used as onyx source code to scan a token from.
string:
A string that is used as onyx source code to scan a token from.
Output(s):
file:
The same file object that was passed in.
substring:
The remainder of string after scanning a token.
obj:
An object that was constructed by scanning a token.
false/true:
If true, a token was successfully scanned, false otherwise.
Errors(s):
stackunderflow.
syntaxerror.
typecheck.
undefined.
Description:
Scan a token from a file or string, using onyx syntax rules. If a token is followed by whitespace, one character of whitespace is consumed when the token is scanned.
Example(s):
onyx:0> `1 2' token pstack clear
true
1
`2'
onyx:0> `foo' token pstack clear
true
foo
`'
onyx:0> `foo ' token pstack clear
true
foo
`'
onyx:0> `foo  ' token pstack clear
true
foo
` '
onyx:0> `foo$bar' token pstack clear
true
foo
`$bar'
onyx:0> `foo{}' token pstack clear
true
foo
`{}'
onyx:0> ` ' token pstack clear
false
onyx:0>
a trunc r:
Input(s):
a:
An integer or real.
Output(s):
r:
Integer created from a by discarding the fractional portion.
Errors(s):
stackunderflow.
typecheck.
Description:
Discard the fractional portion of a to create an integer, and return the result.
Example(s):
onyx:0> -1.51 trunc 1 sprint
-1
onyx:0> -1.49 trunc 1 sprint
-1
onyx:0> 0 trunc 1 sprint
0
onyx:0> 1.49 trunc 1 sprint
1
onyx:0> 1.51 trunc 1 sprint
1
onyx:0>
file length truncate -:
Input(s):
file:
A file object.
length:
New length for file.
Output(s):
None.
Errors(s):
ioerror.
rangecheck.
stackunderflow.
typecheck.
Description:
Set the length of file to length. If this causes the file to grow, the appended bytes will have the value zero.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> dup 0 seek
onyx:1> dup 10 string read
onyx:3> pop 1 sprint
`Hello\n'
onyx:1> dup 3 truncate
onyx:1> dup 0 seek
onyx:1> dup 10 string read
onyx:3> pop 1 sprint
`Hel'
onyx:1>
- true true:
Input(s):
None.
Output(s):
true:
The boolean value true.
Errors(s):
None.
Description:
Return true.
Example(s):
onyx:0> true 1 sprint
true
onyx:0>
mutex trylock boolean:
Input(s):
mutex:
A mutex object.
Output(s):
boolean:
If false, mutex was successfully acquired. Otherwise the mutex acquisition failed.
Errors(s):
stackunderflow.
typecheck.
Description:
Try to acquire mutex, but return a failure immediately if mutex cannot be acquired, rather than blocking.
Example(s):
onyx:0> mutex dup 
onyx:2> trylock 1 sprint
false
onyx:1> trylock 1 sprint
true
onyx:0>
a b tuck b a b:
Input(s):
a:
An object.
b:
An object.
Output(s):
:
Errors(s):
stackunderflow.
typecheck.
Description:
Create a duplicate of the top object on ostack and put it under the second object on ostack.
Example(s):
onyx:0> `a' `b' `c' 
oonyx:3> tuck pstack
`c'
`b'
`c'
`a'
onyx:4>
obj type name:
Input(s):
obj:
An object.
Output(s):
name:
An executable name that corresponds to the type of obj:
array:
arraytype.
boolean:
booleantype.
condition:
conditiontype.
dict:
dicttype.
file:
filetype.
fino:
finotype.
hook:
hooktype.
integer:
integertype.
mark:
marktype.
mutex:
mutextype.
name:
nametype.
null:
nulltype.
operator:
operatortype.
pmark:
pmarktype.
stack:
stacktype.
string:
stringtype.
thread:
threadtype.
Errors(s):
stackunderflow.
Description:
Get a name that represent the type of obj.
Example(s):
onyx:0> true type 1 sprint
booleantype
onyx:0>
- uid uid:
Input(s):
None.
Output(s):
uid:
Process's user ID.
Errors(s):
None.
Description:
Get the process's user ID.
Example(s):
onyx:0> uid 1 sprint
1001
onyx:0>
nmask umask omask:
Input(s):
nmask:
Value to set umask to.
Output(s):
omask:
Old umask.
Errors(s):
stackunderflow.
typecheck.
Description:
Set the process's umask to nmask and return the old umask.
Example(s):
onyx:0> 8@777 umask <$b 8 $w 3 $p `0'> output `\n' print flush
022
onyx:0>
dict key undef -:
Input(s):
dict:
A dictionary.
val:
A key in dict to undefine.
Output(s):
None
Errors(s):
stackunderflow.
typecheck.
Description:
If key is defined in dict, undefine it.
Example(s):
onyx:0> $foo `foo' def
onyx:0> currentdict $foo undef
onyx:0> currentdict $foo undef
onyx:0>
a b under a a b:
Input(s):
a:
An object.
b:
An object.
Output(s):
a:
An object.
b:
An object.
Errors(s):
stackunderflow.
Description:
Create a duplicate of the second object on ostack and put it under the top object on ostack.
Example(s):
onyx:0> 0 1 2 under pstack
2
1
1
0
onyx:4>
filename unlink -:
Input(s):
filename:
A string that represents a filename.
Output(s):
None.
Errors(s):
invalidfileaccess.
ioerror.
stackunderflow.
typecheck.
undefinedfilename.
unregistered.
Description:
Unlink filename.
Example(s):
onyx:0> `/tmp/foo' `w' open
onyx:1> dup `Hello\n' write
onyx:1> dup flushfile
onyx:1> close
onyx:0> `/tmp/foo' unlink
onyx:0> `/tmp/foo' `r' open
Error $invalidfileaccess
ostack: (`/tmp/foo' `r')
dstack: (-dict- -dict- -dict- -dict-)
estack/istack trace (0..2):
0:      --open--
1:      -file-
2:      --start--
onyx:3>
mutex unlock -:
Input(s):
mutex:
A mutex object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Unlock mutex. Unlocking a mutex that the running thread does not own will result in undefined behavior (likely crash).
Example(s):
onyx:0> mutex dup lock unlock
onyx:0>
key unsetenv -:
Input(s):
key:
A name object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Unset key in the environment and in the envdict dictionary, if key is defined.
Example(s):
onyx:0> $foo `foo' setenv
onyx:0> envdict $foo known 1 sprint
true
onyx:0> envdict $foo get 1 sprint
`foo'
onyx:0> $foo unsetenv
onyx:0> envdict $foo known 1 sprint
false
onyx:0>
proc cond until -:
Input(s):
proc:
An object to be repeatedly evaluated.
cond:
An object that, when evaluated, places a boolean on ostack.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Repeatedly evaluate proc and cond, terminating the first time that cond places false on ostack. This operator supports the exit operator.
Example(s):
onyx:0> 0 {inc dup 1 sprint}{dup 3 lt} until pop
1
2
3
onyx:0> 0 {inc dup 1 sprint exit}{dup 3 lt} until pop
1
onyx:0>
a b c up c a b:
Input(s):
a:
An object.
b:
An object.
c:
An object.
Output(s):
c:
An object.
a:
An object.
b:
An object.
Errors(s):
stackunderflow.
Description:
Rotate the top three objects on ostack up one position.
Example(s):
onyx:0> `a' `b' `c' `d' up pstack
`c'
`b'
`d'
`a'
onyx:4>
- userdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get userdict. See Section 2.9.12 for details on userdict.
Example(s):
onyx:0> userdict 1 sprint
<>
onyx:0>
- version string:
Input(s):
None.
Output(s):
string:
A string that contains the version name.
Errors(s):
None.
Description:
Get the version string. The string returned is a reference to the original version string.
Example(s):
onyx:0> version pstack
`1.0.0'
onyx:1>
condition mutex wait -:
Input(s):
condition:
A condition object.
mutex:
A mutex object that this thread currently owns.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Wait on condition. mutex is atomically released when the current thread blocks, then acquired again before the current thread runs again. Using a mutex that the current thread does not own will result in undefined behavior (likely crash).
Example(s):
onyx:0> condition mutex dup lock ostack
onyx:3> {dup lock exch signal unlock}
onyx:4> thread 3 1 roll
onyx:3> dup 3 1 roll
onyx:4> wait unlock join
onyx:0>
pid waitpid status:
Input(s):
pid:
Process identifier.
Output(s):
status:
Exit code of terminated process. A negative value indicates that the process was terminated by a signal (use the neg operator to get the signal number), and a non-negative value is the exit code of a program that terminated normally.
Errors(s):
stackunderflow.
typecheck.
Description:
Wait for the process with process ID pid to exit.
Example(s):
onyx:0> [`/bin/date'] forkexec dup 1 sprint waitpid 1 sprint
6516
Sat Jul 13 20:47:54 PDT 2002
0
onyx:0>
key where false:
key where dict true:
Input(s):
key:
A key to search for in dstack.
Output(s):
dict:
The topmost dictionary in dstack that contains a definition for key.
false/true:
If false, no definition of key was found in dstack. Otherwise dict is the topmost dictionary in dstack that contains a definition for key.
Errors(s):
stackunderflow.
Description:
Get the topmost dictionary in dstack that defines key.
Example(s):
onyx:0> $foo where pstack clear
false
onyx:0> $threaddict where pstack clear
true
<$threaddict -dict- $userdict -dict- $currenterror -dict- $errordict -dict-
$resume --stop-->
onyx:0>
cond proc while -:
Input(s):
cond:
An object that, when evaluated, places a boolean on ostack.
proc:
An object to be repeatedly evaluated.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Repeatedly evaluate cond and proc, terminating the first time that cond places false on ostack. This operator supports the exit operator.
Example(s):
onyx:0> 0 {dup 3 lt}{inc dup 1 sprint} while pop
1
2
3
onyx:0> 0 {dup 3 lt}{inc dup 1 sprint exit} while pop
1
onyx:0>
file integer/string write false:
file integer/string write integer/substring true:
Input(s):
file:
A file object.
integer:
An integer that represents an ascii character value.
string:
A string object.
Output(s):
false:
Successful complete write.
integer:
The integer that was passed in.
substring:
The substring of string that was not written.
true:
Successful partial write.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Write integer or string to file. Partial writes can only happen for non-blocking files.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write pop
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1>
obj xcheck boolean:
Input(s):
obj:
An object.
Output(s):
boolean:
True if obj has the executable or evaluatable attribute, false otherwise.
Errors(s):
stackunderflow.
Description:
Check obj for executable or evaluatable attribute.
Example(s):
onyx:0> {1 2 3} xcheck 1 sprint
true
onyx:0> [1 2 3] xcheck 1 sprint
false
onyx:0>
a b xor r:
Input(s):
a:
An integer or boolean.
b:
The same type as a.
Output(s):
r:
If a and b are integers, their bitwise exclusive or, otherwise their logical exclusive or.
Errors(s):
stackunderflow.
typecheck.
Description:
Return the bitwise exclusive or of two integers, or the logical exclusive or of two booleans.
Example(s):
onyx:0> true false xor 1 sprint
true
onyx:0> true true xor 1 sprint
false
onyx:0> 5 3 xor 1 sprint
6
onyx:0>
- yield -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Vuluntarily yield the processor, so that another thread or process may be run.
Example(s):
onyx:0> 0 100000 {1 add yield} repeat 1 sprint
100000
onyx:0>


next up previous contents index
Next: 2.9.10 threaddict Up: 2.9 Dictionary reference Previous: 2.9.8 sprintsdict   Contents   Index
Jason Evans 2002-09-08