next up previous contents index
Next: 1.8.10 threaddict Up: 1.8 Dictionary reference Previous: 1.8.8 sprintsdict   Contents   Index


1.8.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 1.10: systemdict summary by functional group
Input(s) Op/Proc/Var Output(s) Description
Operand stack operators
- mark mark Create a mark.
- count count Get the number of objects on ostack.
mark ... counttomark mark ... count Get the depth of the topmost mark on ostack.
object dup object object Duplicate an object.
objects count ndup objects objects Duplicate objects.
object ...index index object ... object Duplicate object on ostack at a given index.
a b exch b a Exchange the top two objects on ostack.
region count amount roll rolled Roll the top count objects up by amount.
any pop - Remove the top object from ostack.
objects count npop - Remove objects from ostack.
objects clear - Pop all objects off ostack.
mark ... cleartomark - Remove objects from ostack through topmost mark.
- ostack stack Get a current ostack snapshot.
Execution, control, and execution stack operators
object eval - Evaluate object.
boolean object 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.
proc loop - Iterate 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 object true Scan for a token.
object start - Evaluate object.
- quit - Unwind to innermost start context.
object stopped boolean Evaluate object.
- stop - Unwind to innermost stopped or start context.
name throw object Throw an error.
- estack stack Get a current estack snapshot.
- countestack count Get current estack depth.
- istack stack Get a current istack snapshot.
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.
- fork pid Fork a new process.
args exec - Overlay a new program and execute it.
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 object spush - Push an object onto a 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 index sindex - Duplicate object in a stack at a given index.
stack sexch - Exchange top objects on stack.
stack count amount sroll - Roll objects on stack.
stack spop object Pop an object off stack.
stack sclear - Remove all objects on stack.
stack scleartomark - Remove objects from stack down through topmost mark.
(a) (b) catenate (a b) Catenate two stacks.
srcstack dststack copy dststack Copy stack contents.
Number (integer, real) and math operators
a b add r Add a and b.
a b sub r Subtract b 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' catenate `ab' Catenate two strings.
srcstring dststring copy dstsubstring Copy string.
object depth sprints string Create syntactical string from object.
object 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 object Get array element.
array index object put - Set array element.
array index length getinterval subarray Get an array interval.
array index subarray putinterval - Copy subarray into array.
[a] [b] catenate [a b] Catenate two arrays.
srcarray dstarray copy dstsubarray Copy array.
Dictionary and dictionary stack operators
- gcdict dict Get gcdict.
- globaldict dict Get globaldict.
- onyxdict dict Get onyxdict.
- sprintsdict dict Get sprintsdict.
- outputsdict dict Get outputsdict.
- envdict dict Get envdict.
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.
- countdstack count Get number of stacks on dstack.
- cleardstack - Pop all dstack elements pushed by begin .
File and filesystem operators
filename flags open file Open a file.
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 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 integer/string write - Write to file.
string print - Print string to stdout.
object depth sprint - Syntactically print object to stdout.
object 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 mode mkdir - Create a directory.
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.
path proc dirforeach - Iterate on directory entries.
- pwd path Get present working directory.
path cd - Change present working directory.
- stdin file Get stdin.
- stdout file Get stdout.
- stderr file Get stderr.
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
object type name Get object type.
object echeck boolean Evaluatable?
object xcheck boolean Executable?
object cve object Set evaluatable attribute.
object cvx object Set executable attribute.
object cvlit object Set literal attribute.
string cvn name Convert string to name.
object 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.
object lcheck boolean Implicitly locked?
Miscellaneous operators
- #! mark Begin interpreter magic.
mark names !# - End interpreter magic.
- 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.

mark names !# -:
Input(s):
mark:
A mark object.
names:
Zero or more name objects.
Output(s):
None.
Errors(s):
unmatchedmark.
Description:
Remove mark and name objects constructed as a side effect of interpreter magic. This operator is an alias of cleartomark.
Example(s):
onyx:0> #!/usr/local/bin/onyx pstack
/onyx
/bin
/local
/usr
-mark-
onyx:5> !#
onyx:0>
- #! mark:
Input(s):
None.
Output(s):
mark:
A mark object.
Errors(s):
None.
Description:
Create a mark object in preparation for an interpreter path. This operator is an alias of mark.
Example(s):
onyx:0> #! pstack
-mark-
onyx:1>
- ( 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>
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>
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>
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 evaluatable array.
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>
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] catenate [a b]:
(a) (b) catenate (a b):
`a' `b' catenate `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'] catenate
onyx:1> 1 sprint
[`a' `b']
onyx:0> (`a') (`b') catenate
onyx:1> 1 sprint
(`a' `b')
onyx:0> `a' `b' catenate
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>
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>
- cleardstack -:
Input(s):
None.
Output(s):
None.
Errors(s):
None.
Description:
Pop all dictionaries on dstack that were pushed by begin .
Example(s):
onyx:0> dict begin
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict- -dict-)
onyx:0> cleardstack
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0> cleardstack
onyx:0> dstack 1 sprint
(-dict- -dict- -dict- -dict-)
onyx:0>
mark ... cleartomark -:
Input(s):
mark:
A mark object.
...:
Zero or more non-mark objects.
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>
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):
mark:
A mark object.
...:
Zero or more non-mark objects.
Output(s):
mark:
The same mark that was passed in.
...:
The same non-mark objects that were 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 1.6.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>
object cve object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in, but with the evaluatable attribute set.
Errors(s):
stackunderflow.
Description:
Set the evaluatable attribute for object.
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>
object cvlit object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in, but with the literal attribute set.
Errors(s):
stackunderflow.
Description:
Set the literal attribute for object.
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>
object cvs string:
Input(s):
object:
An object.
Output(s):
string:
A string representation of object. The string depends on the type of object:
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 object. The result can be evaluated to produce the original string.
Other types:
`-nostringval-'.
Errors(s):
stackunderflow.
Description:
Convert object 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>
object cvx object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in, but with the executable attribute set.
Errors(s):
stackunderflow.
Description:
Set the executable attribute for object.
Example(s):
onyx:0> [1 2 3] cvx 1 sprint
{1 2 3}
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>
- 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>
object dup object object:
Input(s):
object:
An object.
Output(s):
object:
The same object that was passed in.
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>
object echeck boolean:
Input(s):
object:
An object.
Output(s):
boolean:
True if object has the evaluatable attribute, false otherwise.
Errors(s):
stackunderflow.
Description:
Check object 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):
dstackunderflow.
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 1.8.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>
object eval -:
Input(s):
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Evaluate object. See Section 1.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 , 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>
- fork pid:
Input(s):
None.
Output(s):
pid:
Process identifier for the new process, or 0 if the child process.
Errors(s):
limitcheck.
Description:
Fork a new process. Care must be taken when using the fork operator due to the fact that onyx consumes programs on the fly. The child process cannot reliably scan onyx code from the same source as the parent, so the child process should be forked into an environment where it is executing an object that has already been constructed by the interpreter, which in turn avoids unwinding the onyx execution stack.
Example(s):
onyx:0> {fork dup 0 eq
        {pop `Child\n' print flush}
        {`Parent\n' print flush waitpid}
        ifelse} eval
Parent
Child
onyx:0>
- gcdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get gcdict. See Section 1.8.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 object:
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):
object:
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 1.8.5 for details on globaldict.
Example(s):
onyx:0> globaldict 1 sprint
<>
onyx:0>
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):

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>
boolean object if -:
Input(s):
boolean:
A boolean.
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Evaluate object 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 1.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>
object ...index index object ...object:
Input(s):
object:
An object.
...:
index objects.
index:
Depth (count starts at 0, not counting index) of the object to duplicate on ostack.
Output(s):
object:
The same object that was passed in.
...:
The same index objects that were passed in.
Errors(s):
rangecheck.
stackunderflow.
typecheck.
Description:
Create a duplicate of the object on on ostack at depth index.
Example(s):
onyx:0> 3 2 1 0 2 index pstack
2
0
1
2
3
onyx:5>
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>
- 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>
object lcheck boolean:
Input(s):
object:
An array, dict, file, or string.
Output(s):
boolean:
True if object is implicitly locked, false otherwise.
Errors(s):
stackunderflow.
typecheck.
Description:
Check if object 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>
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:
Iteratively 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 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>
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/gtk.nxm' `modpane_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 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 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 off 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>
- onyxdict dict:
Input(s):
None.
Output(s):
dict:
A dictionary.
Errors(s):
None.
Description:
Get onyxdict. See Section 1.8.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:
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.
Output(s):
file:
A file object.
Errors(s):
invalidfileaccess.
ioerror.
limitcheck.
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>
object depth output -:
Input(s):
object:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print object. See Section 1.8.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 catenate </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>
object flags outputs string:
Input(s):
object:
An object to print syntactically.
depth:
Formatting flags. See Section 1.8.7 for details on the supported flags.
Output(s):
string:
A formatted string representation of object. See Section 1.8.7 for format specifier details.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a formatted string representation of object.
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 catenate </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 1.8.7 for details on outputsdict.
Example(s):
onyx:0> outputsdict 0 sprint
-dict-
onyx:0>
- 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>
any pop -:
Input(s):
any:
Any object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Remove the top object off ostack and discard it.
Example(s):
onyx:0> 1 2
onyx:2> pstack
2
1
onyx:2> pop
onyx:1> pstack
1
onyx:1>
- 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 object 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 object or integer, respectively.
key:
An object to use as a key in dict.
object:
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>
- 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>
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>
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 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>
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. An 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 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 1.6.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>
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>
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 sindex -:
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 sindex
onyx:1> 1 sprint
(3 2 1 0 2)
onyx:0>
stack spop object:
Input(s):
stack:
A stack object.
Output(s):
object:
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>
object depth sprint -:
Input(s):
object:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Syntactically print object. See Section 1.8.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>
object depth sprints string:
Input(s):
object:
An object to print syntactically.
depth:
Maximum recursion depth.
Output(s):
string:
A syntactical string representation of object. See Section 1.8.8 for printing details.
Errors(s):
stackunderflow.
typecheck.
Description:
Create a syntactical string representation of object.
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 1.8.8 for details on sprintsdict.
Example(s):
onyx:0> sprintsdict 0 sprint
-dict-
onyx:0>
stack object spush -:
Input(s):
stack:
A stack object.
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
typecheck.
Description:
Push object onto stack.
Example(s):
onyx:0> () dup 1 spush
onyx:1> pstack
(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 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
()
object start -:
Input(s):
object:
An object.
Output(s):
None.
Errors(s):
stackunderflow.
Description:
Evaluate object. 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 stderr.
Errors(s):
None.
Description:
Get stdout.
Example(s):
onyx:0> stderr pstack
-file-
onyx:1>
- stdin file:
Input(s):
None.
Output(s):
file:
A file object corresponding to stdin.
Errors(s):
None.
Description:
Get stdin.
Example(s):
onyx:0> stdin pstack
-file-
onyx:1>
- stdout file:
Input(s):
None.
Output(s):
file:
A file object corresponding to stdout.
Errors(s):
None.
Description:
Get stdout.
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>
object stopped boolean:
Input(s):
object:
An object to evaluate.
Output(s):
boolean:
True if stop operator was executed, false otherwise.
Errors(s):
invalidexit.
stackunderflow.
Description:
Evaluate object. 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>
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>
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>
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>
name throw object:
Input(s):
name:
The name of an error.
Output(s):
object:
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 index dup lock 1000000000 timedwait 1 sprint unlock
true
onyx:0>
file/string token false:
file/string token file/substring object 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.
object:
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>
object type name:
Input(s):
object:
An object.
Output(s):
name:
An executable name that corresponds to the type of object:
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 object.
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>
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>
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>
- 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> {fork dup 0 eq
        {pop `Child\n' print flush}
        {`Parent\n' print flush waitpid}
        ifelse} eval
Parent
Child
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>
file integer/string write -:
Input(s):
file:
A file object.
integer:
An integer that represents an ascii character value.
string:
A string object.
Output(s):
None.
Errors(s):
ioerror.
stackunderflow.
typecheck.
Description:
Write integer or string to file.
Example(s):
onyx:0> `/tmp/foo' `w+' open
onyx:1> dup `Hello\n' write
onyx:1> dup 0 seek
onyx:1> dup readline 1 sprint 1 sprint
false
`Hello'
onyx:1>
object xcheck boolean:
Input(s):
object:
An object.
Output(s):
boolean:
True if object has the executable or evaluatable attribute, false otherwise.
Errors(s):
stackunderflow.
Description:
Check object 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: 1.8.10 threaddict Up: 1.8 Dictionary reference Previous: 1.8.8 sprintsdict   Contents   Index
Jason Evans 2002-03-30