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 .
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 in radians.
  Errors(s):
    stackunderflow.
    typecheck.
  Description:
    Return the arctangent of 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: 1.8.10 threaddict Up: 1.8 Dictionary reference Previous: 1.8.8 sprintsdict Contents Index