Dictionary



  1. Dictionary Maintenance
  2. Word Lists and Search Order
  3. Compilation and Execution Words
  4. Defining Words
  5. Control Structures
  6. Stack Operations
  7. Memory Operations
  8. String Operations
  9. Logic and Bit Manipulation Operations
  10. Arithmetic and Relational Operations
  11. Floating Point Functions
  12. Number Conversion
  13. Input and Output
  14. File Access
  15. Operating System Interface
  16. Miscellaneous

Stack diagram notation:

Data TypeStack Cells
aaddress1
nsigned single integer1
uunsigned single integer1
dsigned double length integer2
udunsigned double length integer2
tsigned triple length integer3
utunsigned triple length integer3
bboolean flag: true or false (-1 or 0)1
rdouble precision floating point value2
^strcounted string address1


Word names shown in BOLDFACE are not standard in ANS Forth.



Dictionary Maintenance

FORGET -- remove the next word in the input stream and later words from the dictionary
COLD -- remove all non-intrinsic definitions from the dictionary
WORDS -- list the defined words in the current search order


The word FORGET may be used to remove words from the dictionary. Typing

FORGET name


will remove name and all words defined after name from the dictionary.

The word COLD deletes all non-intrinsic definitions and strings, resets all stacks, and restarts the Forth environment in interpreter mode.


Word Lists and Search Order

Words in the dictionary are grouped into word lists. kForth provides the following built-in word lists:

Root Forth Assembler

New definitions are added to the current compilation word list, which is initially the Forth word list. When the compiler searches the dictionary for a word name, the search proceeds in a specified order through a specified series of word lists. This set of ordered word lists is known as the search order. The Root word list must always be a part of the search order; however, any other word lists may be added or removed from the search order. The user may create custom word lists to group new words added to the dictionary, and control their visibility to the Forth compiler.

ORDER -- display the word lists in the search order. The word list at the
beginning of the search order is displayed to the left,
and the compilation word list is shown in brackets
GET-ORDER -- awidn ... awid1 n return the word list address identifiers, and the number of word lists
awid1 is the first word list in the search order
SET-ORDERawidn ... awid1 n -- set the search order to the specified sequence of word lists,
where awid1 is the first word list in the search order
ONLY -- remove all word lists from the search order, except the minimal Root word list
FORTH -- replace the first word list in the search order with the Forth word list
ASSEMBLER -- replace the first word list in the search order with the Assembler word list
GET-CURRENT -- awid return the word list address for the current compilation word list
SET-CURRENT awid -- set the compilation word list to be the word list identified by awid
FORTH-WORDLIST -- awid return the word list address identifying the Forth word list
ALSO -- duplicate the word list at the beginning of the search order
PREVIOUS -- remove the first word list in the search order
DEFINITIONS -- set the first word list in the search order as the compilation word list
WORDLIST -- awid create a new empty word list and return its identifier address, awid
VOCABULARY -- create a new named word list which, when executed, will replace the
first word list in the search order
SEARCH-WORDLIST a u awid -- 0 | axt n search the word list identified by awid for the word name in the string,
a u. Return n=0 if the word is not found in the word list,
n=1 if the word is found and is an immediate word
n=-1 if the word is found and is not an immediate word
FIND ^str -- a n search all the word lists in the search order for
the word specified by the counted string;
n is 0 if not found,
n is 1 if found and the word is an IMMEDIATE word,
n is -1 if found and the word is not an immediate word,
and a is a valid EXECUTE address if the word is found
[DEFINED] -- b parse a word name from the input stream, search for
the name in the search order, and return a flag indicating
whether or not the name was found (-1 if found).
[UNDEFINED] -- b parse a word name from the input stream, search for
the name in the search order, and return a flag indicating
whether or not the name was found (0 if found).


Compilation and Execution Words

IMMEDIATE -- set the precedence during compilation of the most recently defined word
NONDEFERRED -- set the precedence during interpretation of the most recently defined word
POSTPONE -- append the run-time semantics of the next word to the current definition
LITERALn | a -- compile a number or address on the stack into the current definition
2LITERALd -- compile a double number on the stack into the current definition
SLITERALa u -- compile a string address and count from the stack into the current definition
FLITERALr -- compile a floating point number on the stack into the current definition
' -- areturns the code field address (cfa) of the next word in the input stream
['] -- immediate version of ' for use inside a word definition
>BODYa1 -- a2convert the cfa of a word to its parameter field address (pfa)
COMPILE, a -- compile the execution semantics for the cfa of a word into the current definition
EXECUTEa -- execute a word with its cfa given on the stack
EVALUATEa u -- interpret and execute source code contained in a string
: -- create a new word definition and enter the compilation state
; --
[ -- enter interpretation state
] -- enter compilation state
STATE -- breturn true (-1) if compiling; false (0) otherwise


The words ' (TICK), and ['] may be used to search the dictionary for a specified word. These words behave according to the ANS Forth standard, and return an execution address on the stack. The word EXECUTE may be used to execute a word given the execution address on the stack. The word NONDEFERRED is a non-standard word which is used to set the enhanced precedence state of a word in kForth. For more information on the concept of precedence in kForth, refer to the Technical Information section of the user's guide.

The following standard compilation words are provided in Forth source in ans-words.4th :

TO -- determine the body address of the next word and append the
run-time semantics to store a value at that address



Defining Words

In addition to ordinary "colon definitions" of the form,

: NAME ... ;

the following defining words are also provided:

CREATE name
VARIABLE name
n  CONSTANT name
2VARIABLE name
d  2CONSTANT name
FVARIABLE name
f  FCONSTANT name

CREATE can be used inside a word definition to make your own defining words. The word DOES>, as part of a CREATE ... DOES> expression, allows you to specify the run time behavior of words created by the defining word.

At present, kForth does not allow making a defining word with the use of ":" inside the definition of a word -- use CREATE ... DOES> instead.

The following common Forth defining words have source code definitions, provided in ans-words.4th:

n VALUE name
DEFER name

An existing word may be referred to by another name, using the non-standard word ALIAS.

ALIAS xt -- create a new word which has the same execution behavior as xt


It may be used as follows,

' name1 ALIAS name2


where name1 is the name of an existing word in the search order, and name2 is the new name.

Control Structures

The following control structures are provided in kForth:

DO ... LOOP
DO ... +LOOP
?DO ... LOOP
?DO ... +LOOP
IF ... THEN
IF ... ELSE ... THEN
BEGIN ... AGAIN
BEGIN ... UNTIL
BEGIN ... WHILE ... REPEAT
CASE ... OF ... ENDOF ... ENDCASE

All control stuctures may be nested --- for DO loops the number of levels of nesting is only limited by return stack space. The following execution control words are also defined:

RECURSE
LEAVE
EXIT
QUIT
ABORT
ABORT"

RECURSE causes the currently executing word to be executed.

LEAVE removes the current loop parameters from the return stack, by calling UNLOOP, and causes an immediate jump out of the current loop. Execution resumes at the instruction following the loop.

EXIT causes an immediate return from the word currently being executed. Note that EXIT from within a loop requires that the loop parameters be discarded from the return stack explicitly with UNLOOP.

QUIT empties the return stack, terminates execution of the current word and returns kForth to the interpreter mode.

ABORT empties the data stack and executes QUIT.

ABORT" examines the flag on top of the stack and if the flag is true, prints the message delimited by ", then executes ABORT.

The exception handling words CATCH and THROW are defined in source in ans-words.4th.


Stack Operations


DUPn -- n nduplicate
?DUPn -- n n | 0 dup if not zero
SWAPn1 n2 -- n2 n1swap
OVERn1 n2 -- n1 n2 n1over
ROTn1 n2 n3 -- n2 n3 n1 rotate cw
-ROTn1 n2 n3 -- n3 n1 n2 rotate ccw
DROPn1 --drop
NIPn1 n2 -- n2nip
TUCKn1 n2 -- n2 n1 n2tuck
PICK... n -- ... m copy nth item deep
ROLL... n -- ... m rotate nth item deep to top of stack
DEPTH ... -- ... nstack depth
2DUPn1 n2 -- n1 n2 n1 n2
2SWAP n1 n2 n3 n4 -- n3 n4 n1 n2
2OVER n1 n2 n3 n4 -- n1 n2 n3 n4 n1 n2
2ROT n1 n2 n3 n4 n5 n6 -- n3 n4 n5 n6 n1n2
2DROP n1 n2 --
FDUPr -- r r duplicate a floating point number on top of the stack
FSWAPr1 r2 -- r2 r1 swap two floating point numbers on the stack
FOVERr1 r2 -- r1 r2 r1 copy the floating point number one deep onto top of stack
FROTr1 r2 r3 -- r2 r3 r1 rotate the order of three fp numbers on the stack
FDROPr -- drop a floating point number from the stack
F2DROPr1 r2 -- drop two fp numbers from the stack
F2DUPr1 r2 -- r1 r2 r1 r2 duplicate a pair of fp numbers on the stack

Return stack operations are:

>R n -- push onto return stack
R> -- n pop from return stack
R@ -- n copy from top of return stack
2>R d -- push two stack cells onto return stack
2R> -- d pop two cells from return stack
2R@ -- d copy two cells from top of return stack
I-- ncurrent loop index
J-- nnext outer loop index
UNLOOP -- discard loop parameters from return stack

Note that 2>R is not equivalent to the sequence >R >R. The order of the two single length elements on top of the return stack is different for the two cases. 2>R pushes two items from the top of the stack so that they have the same order on the return stack. The sequence 2>R 2R>, however, is identical to the sequence >R >R R> R>.


Memory Operations




@a -- nfetch single
!n a -- store single n to address a
2@a -- d fetch double number from address a
2!d a -- store double number to address a
A@a1 -- a2 fetch address from address a
C@a -- n fetch byte
C! n a --store byte
W@a -- n fetch signed word
W!n a --store signed word
SF@a -- r fetch single precision float
SF!r a -- store r as single precision float
DF@a -- r fetch double precision float
DF!r a -- store double precision float
F@a -- r same as DF@
F!r a -- same as DF!
SP@-- a fetch data stack pointer
RP@-- a fetch return stack pointer
SP!a -- set data stack pointer
RP!a -- set return stack pointer
?a -- fetch and print single; equivalent to @ .
ALLOTu -- allocates u bytes in the dictionary
?ALLOTu -- a allocates u bytes in the dictionary and returns
starting address of the allocated region
ALLOCATEu -- a n reserve u bytes of system memory and return starting
address of the allocated region and error code
FREEa -- n release memory previously reserved with ALLOCATE
and return error code (0 = success)
RESIZEa1 u -- a2 ior change size of previously ALLOCATEd region
to u bytes; ior = 0 if success
C" -- ^str compile a counted string into the string table;
the string is taken from the input stream and
must be terminated by "
S" -- a u compile a string and return address and count
COUNT^str -- a u convert counted string address to character
buffer address a and character count u
MOVEa1 a2 u -- move u bytes from source a1 to dest a2; handle overlapping region
FILLa u1 n2 -- fill u1 bytes with byte value n2 starting at a
ERASEa u -- fill u bytes with zero starting at a

See also String Operations.

The following standard memory words are provided in Forth source in ans-words.4th and dump.4th:

PAD -- a return address of a scratch-pad in memory for temporary useans-words.4th
DUMPa u -- output a hexadecimal display of the u bytes starting at address 'a' dump.4th

The non-ANS standard word A@ is needed because kForth performs type checking for operands involved in memory access. It is essentially identical to @ except the type field is set to be an address for the retrieved value. Addresses may be stored in ordinary variables using !; however they should be retrieved with A@.

The behavior of ALLOT does not conform exactly to the ANS standard. ALLOT dynamically allocates the requested amount of memory and sets the parameter field address (PFA) of the last created word to the address of the alloted region. Thus, ALLOT should always be preceeded by CREATE. In kForth, an attempt to ALLOT without first creating a named dictionary entry, using CREATE, will result in a virtual machine error. Thus kForth limits the use of ALLOT, but code written for kForth will be portable to ANS Forths.

The non-ANS standard word ?ALLOT is provided because kForth contains no HERE address. ?ALLOT should be preceeded by CREATE as described above. All memory is dynamically allocated, and freed upon exiting kForth.


String Operations


-TRAILINGa u1 -- a u2 reduce string length to ignore trailing spaces
/STRINGa1 u1 n -- a2 u2 a2 = a1 + n, u2 = u1 - n
BLANKa u -- fill u bytes with the blank-space character starting at a
CMOVEa1 a2 u -- move u bytes from source a1 to dest a2
CMOVE>a1 a2 u -- move u bytes from a1 to a2 in descending order
COMPAREa1 u1 a2 u2 -- n compare the strings a1 u1 and a2 u2. Return zero if they are equal.
SEARCHa1 u1 a2 u2 -- a3 u3 b search for the string a2 u2 within the string a1 u1;
return true if found and the substring a3 u3
SLITERALa u -- compile a string address and count from the stack into the current definition

The following useful string words are provided in strings.4th.

SCANa1 u1 n -- a2 u2 search for first occurence of character value n in the string
specified by a1 u1. Return the substring a2 u2 starting
with the search character
SKIP a1 u1 n -- a2 u2 search for first occurence of character value not equal to n

See also Memory Operations.


Logic and Bit Manipulation Operations


ANDn1 n2 -- n3 bitwise AND of n1 and n2
ORn1 n2 -- n3 bitwise OR of n1 and n2
XORn2 n2 -- n3 bitwise exclusive OR of n1 and n2
NOTn1 -- n2 one's complement of n1
INVERTn1 -- n2 same as NOT
LSHIFTn1 n2 -- n3 n3 is n1 shifted left by n2 bits
RSHIFTn1 n2 -- n3 n3 is n1 shifted right by n2 bits


Arithmetic and Relational Operations

Single and Double Integer Operations

1+n1 -- n2 increment (n2 = n1 + 1)
1-n1 -- n2decrement (n2 = n1 - 1)
2+n1 -- n2n2 = n1 + 2
2-n1 -- n2n2 = n1 - 2
2*n1 -- n2arithmetic left shift (n2 = n1*2)
2/n1 -- n2arithmetic right shift (n2 = n1/2)
CELLSn1 -- n2 n2 is n1 times size in bytes of a cell (4)
CELL+n1 -- n2 n2 is n1 plus the size in bytes of a cell
FLOATSn1 -- n2 n2 is n1 times size of a floating point number
FLOAT+n1 -- n2 n2 is n1 plus the size of a floating point number
DFLOATSn1 -- n2 n2 is n1 times size of double precision fp number
DFLOAT+n1 -- n2 n2 is n1 plus size of double precision fp number
SFLOATSn1 -- n2 n2 is n1 times size of single precision fp number
SFLOAT+n1 -- n2 n2 is n1 plus size of single precision fp number
CHAR+n1 -- n2 same as 1+
+n1 n2 -- n3add
-n1 n2 -- n3subtract (n3 = n1 - n2)
*n1 n2 -- n3multiply
/n1 n2 -- n3divide ( n3 = n1/n2)
+!n a -- add n to value at address a
MODn1 n2 -- n3 modulus or remainder
/MODn1 n2 -- n3 n4 n3 = remainder and n4 = quotient for n1/n2
*/n1 n2 n3 -- n4 n4 = n1*n2/n3; intermediate value is 64 bit
*/MODn1 n2 n3 -- n4 n5 n4 and n5 are remainder and quotient for n1*n2/n3
M+d1 n -- d2 add single to double integer
M*n1 n2 -- d multiply two singles and return signed double
M*/d1 n1 +n2 -- d2 multiply d1 by n1 to obtain triple cell result; then divide result by n2>0 to give signed double d2
UM*u1 u2 -- ud multiply unsigned singles and return unsigned double
UM/MODud u1 -- u2 u3 divide unsigned double number by unsigned single
and return remainder (u2) and quotient (u3).
Returns -1 -1 for u2 and u3 on division overflow
FM/MODd n1 -- n2 n3 divide double by single to give floored quotient n3 and modulus n2
SM/REMd n1 -- n2 n3 divide double by single to give symmetric quotient n3 and remainder n2
DS*d n -- t multiply double and single to give signed triple length product
UDM*ud u -- ut multiply unsigned double and unsigned single to give unsigned triple length product
UTM/ut u -- ud divide unsigned triple by unsigned single to give unsigned double quotient
UTS/MODut1 u1 -- ut2 u2 Divide unsigned triple ut1 by unsigned single u1 to give unsigned triple quotient ut2 and unsigned single remainder u2
STS/REMt1 n1 -- t2 n2 Divide signed triple t1 by signed single n1 to give signed triple quotient t2 and signed remainder n2
D+d1 d2 -- d3 double number addition
D-d1 d2 -- d3 double number subtraction
ABSn1 -- n2 absolute value
NEGATEn1 -- n2 n2 = -n1
DABSd1 -- d2 double number absolute value
DNEGATEd1 -- d2 double number negation
MINn1 n2 -- n1 | n2 minimum of n1 and n2
MAXn1 n2 -- n1 | n2 maximum of n1 and n2
DMINd1 d2 -- d1|d2 minimum of d1 and d2
DMAXd1 d2 -- d1|d2 maximum of d1 and d2
=n1 n2 -- btest n1 equal to n2
<>n1 n2 -- b test n1 not equal to n2
<n1 n2 -- b test n1 less than n2
>n1 n2 -- b test n1 greater than n2
<=n1 n2 -- b test n1 less than or equal to n2
>=n1 n2 -- b test n1 greater than or equal to n2
U<u1 u2 -- b test unsigned u1 less than u2
U>u1 u2 -- b test unsigned u1 greater than u2
D=d1 d2 -- b test d1 equal to d2
D<d1 d2 -- b test d1 less than d2
DU<ud1 ud2 -- b test ud1 less than ud2
0<n -- b test n less than zero
0>n -- btest n greater than zero
0=n -- btest n equal to zero
0<>n -- btest n not equal to zero
D0=d -- b test d equal to zero
D2*d1 -- d2 d2 is the arithmetic left shift of d1
D2/d1 -- d2 d2 is the arithmetic right shift of d1
WITHINn1|u1 n2|u2 n3|u3 -- b return TRUE if n2|u2 <= n1|u1 < n3|u3, given n2|u2 < n3|u3

kForth provides pre-defined constants TRUE (-1) and FALSE (0).

Floating Point Operations

F+r1 r2 -- r3fadd
F-r1 r2 -- r3fsubtract (r3 = r1 - r2)
F*r1 r2 -- r3fmultiply
F/r1 r2 -- r3fdivide ( r3 = r1/r2)
FABSr1 -- r2absolute value
FNEGATEr1 -- r2r2 = -r1
FROUNDr1 -- r2round to nearest whole number
FTRUNCr1 -- r2 truncate, towards zero, to whole number
FLOORr1 -- r2truncate, towards minus infinity, to whole number
FMINr1 r2 -- r1 | r2 minimum of r1 and r2
FMAXr1 r2 -- r1 | r2 maximum of r1 and r2
F0=r -- btest r equal to zero
F0<r -- btest r less than zero
F0>r -- btest r greater than zero
F=r1 r2 -- btest r1 equal to r2
F<>r1 r2 -- b test r1 not equal to r2
F<r1 r2 -- b test r1 less than r2
F>r1 r2 -- b test r1 greater than r2
F<=r1 r2 -- b test r1 less than or equal to r2
F>=r1 r2 -- b test r1 greater than or equal to r2


The following standard word is provided as Forth source in ans-words.4th:

F~ r1 r2 r3 -- b test r1 approximately equal to r2, within uncertainty r3;
if r3 = 0e, r1 and r2 must be exactly equal in their binary representation



Floating Point Functions


F**r1 r2 -- r3 r3 = r1 raised to power of r2
FSQRTr1 -- r2 square root
FLOGr1 -- r2 r2 = log base 10 of r1
FALOGr1 -- r2 r2 = 10 raised to power of r1
FEXPr1 -- r2 r2 = exp(r1)
FLNr1 -- r2 r2 = log base e of r1
DEG>RADr1 -- r2 degrees to radians
RAD>DEGr1 -- r2 radians to degrees
FSINr1 -- r2r2 = sin(r1)
FCOSr1 -- r2r2 = cos(r1)
FSINCOSr1 -- r2 r3 r2 = sin(r1); r3 = cos(r1)
FTANr1 -- r2r2 = tan(r1)
FASINr1 -- r2 arc sine
FACOSr1 -- r2 arc cosine
FATANr1 -- r2 arc tangent
FATAN2r1 r2 -- r3 r3 is arc tangent of r1/r2 with proper quadrant
FSINHr1 -- r2r2 = sinh(r1)
FCOSHr1 -- r2r2 = cosh(r1)
FTANHr1 -- r2r2 = tanh(r1)
FASINHr1 -- r2 inverse hyperbolic sine
FACOSHr1 -- r2 inverse hyperbolic cosine
FATANHr1 -- r2 inverse hyperbolic tangent


Number Conversion


S>Dn -- d convert single integer to double length integer
D>Sd -- n convert signed double integer to signed integer
S>Fn -- r convert single integer to floating point number
D>Fd -- r convert double length integer to fp number
FROUND>Sr -- n convert floating point to integer by rounding
FTRUNC>Sr -- n convert floating point to integer by truncating towards zero
F>Dr -- d convert fp number to double integer by truncating towards zero
>FLOATa u -- r TRUE | FALSE convert string to floating point number
return fp number and TRUE if successful, FALSE otherwise
>NUMBERud1 a1 u1 -- ud2 a2 u2 convert digits of string a1 u1 and add this number
to ud1*base; result is ud2, and a2 u2 point
to remaining part of string
NUMBER?^str -- d b convert counted string to signed double number
b is TRUE if successful
<#ud -- ud begin conversion of unsigned double to a string
#ud1 -- ud2 convert the least significant digit of ud1 to a character;
concatenate character to conversion string.
#Sud1 -- 0 0 convert all significant digits in ud1 to string
SIGNn -- attach minus sign to conversion string if n < 0
HOLDn -- attach character with ASCII code n to the conversion string
#>ud -- a u drop the double number and return the string address and count


Other useful conversion words for number to string conversion and vice-versa are given in Forth source in strings.4th.


Input and Output


BASE -- a return the address containing current number base
DECIMAL -- set the number base to ten
BINARY -- set the number base to two
HEX -- set the number base to sixteen
KEY -- n wait for key press and return key code
ACCEPTa n1 -- n2 read up to n1 characters into buffer a
from keyboard. n2 is actual number input.
BL -- 32 return the ascii value for a blank space character
WORDn -- ^str parse a word from the input stream, delimited by
character with ascii value n and return
the address of a counted string containing the word
CHAR -- n parse the next word, delimited by a space and return
the ascii value of its first character
[CHAR] -- n version of CHAR for use in compile state
.n -- display top item on the stack in the current base
.Rn m -- display n in the current base in m-wide field
U.u -- display unsigned single in current base
U.Ru m -- display u in the current base in m-wide field
D.d -- display signed double length number
PRECISION -- u return the number of significant digits output by FS.
SET-PRECISION u -- set the numer of significant digits output by FS.
FS. r -- display the floating point number using scientific
notation, with the number of significant digits
specified by PRECISION
F.r -- display the floating point number on top of the stack,
using an automatic format.
.Sn1 n2 ... -- n1 n2 ... non-destructive display of the stack
." -- display text message; the message is read from
the input stream and must be terminated by "
.( -- display text message from input stream; message
is terminated by ')'. The word is executed immediately.
CR -- output carriage return
SPACESn -- output n spaces
EMITn -- output character with ascii value n
TYPEa n -- display n characters from buffer at a
SOURCE -- a u return address and count of the input buffer
REFILL -- b attempt to read another line from the input source and return flag
>FILE -- change output stream from the console to a file.
The filename is the next word in the input stream
CONSOLE -- reset output stream to the console


The following standard terminal control words, and more, are provided in Forth source in ansi.4th:

PAGE -- clear the screen and put cursor at top left
AT-XYn1 n2 -- position cursor at column n1 and row n2, origin is (0,0)


File Access


OPEN ^name n1 -- n2 open file specified by counted string ^name
in mode n1, which can be the following:
0 read-only (R/O)
1 write-only (W/O)
2 read-write (R/W)
n2 is the file descriptor, a non-negative
integer if successful.
LSEEKn1 n2 n3 -- n4 change current position in opened file
n1 is the file descriptor
n2 is the offset, and
n3 is the mode with the following meaning:
0 offset is relative to start of file
1 offset is relative to current position
2 offset is relative to end of file
n4 is the resulting offset from the
beginning of the file, or -1 if error.
READn1 a n2 -- n3 read n2 bytes into buffer address a, from
file with descriptor n1.
n3 is the number of bytes actually read.
WRITEn1 a n2 -- n3 write n2 bytes from buffer address a to
file with descriptor n1.
n3 is the number of bytes actually written.
CLOSEn1 -- n2 close file with descriptor n1 and return
status n2 (0 if successful, -1 if error).
INCLUDE -- read and process the specified Forth source file
INCLUDEDa u -- ? set the input stream for the interpreter to the
specified file and process it line by line

The following ANS standard file access words are provided as Forth definitions in files.4th:

R/O -- n "read-only" file access method
W/O -- n "write-only" file access method
R/W -- n "read-write" file access method
CREATE-FILE a u n1 -- n2 n3 create a file with name specified by string address and count a u,
and access method n1. Return file descriptor n2 and result code n3
OPEN-FILE a u n1 -- n2 n3 open an existing file and return file descriptor n2 and result code n3
CLOSE-FILE n1 -- n2close the file with descriptor n1 and return result code n2
READ-FILE a u1 n1 -- u2 n2 read u1 bytes into buffer at address 'a' from file with descriptor n1
and return actual number of bytes read u2 and result code n2
WRITE-FILE a u n1 -- n2write u bytes from buffer 'a' to file with descriptor n1; return result code n2
FILE-POSITION n1 -- ud n2return the current file position ud and result code n2
REPOSITION-FILE ud n1 -- n2 set file position to ud for file with descriptor n1 and return result code n2
FILE-SIZE n1 -- ud n2 return the size of the file ud and the result code n2
FILE-EXISTS ^str -- b return TRUE if the specified file exists
DELETE-FILE a u -- n delete the file specified by string a u, and return result code n (not in Cygwin)
READ-LINE a u1 n1 -- u2 b n2 read a line of text, with at most u1 bytes, from file with descriptor n1 into the buffer 'a'; return actual bytes read u2, success flag, and result code n2
WRITE-LINE a u n1 -- n2 write a line of text having u bytes from buffer 'a' into file
with descriptor n1, and return result code n2


Operating System Interface


SYSTEM^str -- n execute a shell command; ^str is the command line passed to the shell.
Return code n is -1 on error, or the return value from the command.
SYSCALLn1 ... nm m ncall -- nerr perform system call ncall, with arguments n1 to nm, where 0<=m<=6 (not functional under Cygwin)
BYE -- close the Forth environment and exit to the system.
CHDIR^path -- n change the current directory to the one specified in
the counted string ^path; n is OS dependent return code
IOCTLn1 n2 a -- n3 send device control request n2 to file with descriptor n1. Additional parameters are passed through buffer at address a. n3 is the status (0 if successful, -1 if error).
TIME&DAY -- sec min hr day mo yr return the local time
MSu -- wait for at least u milliseconds
MS@ -- u return number of milliseconds elapsed since start of kForth
DLOPENazstr bflag -- nhandle load the dynamic library file
DLERROR -- azstr return address of null terminated error string
DLSYMnhandle azsym -- addr return address of symbol in library
DLCLOSEnhandle -- nerr close the dynamic library
FORTH-SIGNALa n -- aold install Forth word as handler for signal n
RAISEn -- ior assert signal n
SET-ITIMERn1 a1 a2 -- n2 set up timer signals
GET-ITIMERn a -- n2 get timer countdown count
USLEEPu -- wait for at least u microseconds
(For Windows version, resolution is 1000)

Numerous operating system functions are defined as Forth words in syscalls.4th.


Miscellaneous


CALLa -- call machine language subroutine at address a