Description: Creating bootloader graphics with gfxboot for syslinux/isolinux, lilo, and grub.

## gfxboot reference

Abstract

Creating bootloader graphics with gfxboot for syslinux/isolinux, lilo, and grub.

## Overview

To make a graphical boot screen you'll have to write a small script. Optionally you might want font files, graphics files and sound files.

The script is written in a Postscript-like language. You must program everything related to graphics output in it. That does include e.g. drawing the background picture and in particular handling all kind of user input.

Font files have a special format. Create them using gfxboot-font. Maximum font file size is 512kB.

If you have written a script, convert it into byte code using gfxboot-compile.

Debugging this script is rather tedious. For this, gfxboot-compile -l will give you debug information that is useful together with the `dtrace` command.

## Utilities

Tools needed to build a boot graphics file.

- gfxboot-compile

  Compile source into byte code. The result (together with any other files you might need) has to be put into a cpio archive. If you are using isolinux or syslinux, this is not required, as you can read files directly from the filesystem. The compiled byte code, however, always has to be put into the cpio archive.

  Example 1.

        # compile 'foo.ps' to 'foo', writing log to foo.log
        # Note: '-O' turns on the optimizer. You'll always want to do this.
        gfxboot-compile -O -v -l foo.log -c foo.ps foo

        # put it into a cpio archive
        # we'll assume you need a picture 'foo.jpg' and are using font 'foo.fnt'
        echo -e "foo\nfoo.jpg\nfoo.fnt" | cpio -o >bootlogo

        # 'bootlogo' is ready to use, e.g.
        # as 'gfxboot bootlogo' in isolinux.cfg

- gfxboot-font

  Build font file using the freetype rendering engine.

- help2txt

  Convert html files into the internal online-help format.

## Reference

Comments start with '%' and extend to the end of line.

To include some other source file, do:

    %% include file

Numbers are always 32 bit signed integer. Numerical and string constants are given in a C-like way (not as in Postscript).

Example 2.

        123, -456
        0x4567
        "Hi there\n"
        '\033', '\x1b', '\u20ac'

But: chars have values in the range 0 .. 0x1fffff.

Strings are interpreted as utf8-sequences. Alternatively you can use '\uXXXX' or '\UXXXXXXXX' to include Unicode characters.

Example 3.

         "1 Euro = 1 €\n"
         "1 Euro = 1 \u20ac\n"
         "1 Euro = 1 \xe2\x82\xac\n"

Logical operations return values of type 'bool'. They are not identical with integers. There are no pre-defined constants 'true' and 'false'. But you can define them yourself if you need them, e.g.:

    /true 0 0 eq def

Strings and arrays are effectively pointers. So duplicating them on the stack does duplicate the pointer, not the object.

In addition, there is a unspecific pointer data type. You can use it to construct arbitrary memory references.

Variable/constants/function names can consist of everything except whitespace.

### Initialisation

During initialization the config file in run. It must leave either an empty stack or a boolean 'true' value at the TOS (top of stack) to indicate the boot loader that everything worked fine. Otherwise the boot loader will assume that some error occured and not continue in graphics mode.

If you want to handle input (as you probably do) you must define at least the callback function KeyEvent.

### Callbacks

Communication with the boot loader is done via callback functions. You are responsible to assign useful actions to them. See config file examples for more documentation.

- `KeyEvent`

  Called if a key is pressed.

- `MenuInit`

  Should draw boot menu.

- `InfoBoxInit`

  Show message box (e.g. error messages).

- `InfoBoxDone`

  Hide message box.

- `ProgressInit`

  Initialize kernel load progress bar (syslinux/isolinux only).

- `ProgressDone`

  Hide progress bar.

- `ProgressUpdate`

  Advance progress bar.

- `PasswordInit`

  Show password dialog.

- `PasswordDone`

  Hide password dialog.

- `Timeout`

  Timeout counter; called every 18.3th second until timeout occurs.

- `Timer`

  Called every 18.3th second regardless of timeout.

### Primary words

- `{` – start code definition

  ( — `code1` )

  `code1`: code start marker

  After `{`, no code is executed until a matching `}` is found.

  See also: `def`, `}`

  Example 4.

        /++ { 1 add } def       % define increment function '++'

- `}` – complete code definition

  ( — )

  Note: `{` and `}` are taken care of already during conversion into bytecode. This means that redefining them does not work as you would expect.

  See also: `def`, `{`

  Example 5.

        /dec { 1 sub } def      % define decrement function 'dec'

- `64bit` – test if we run on a 64-bit machine

  ( — `int1` )

  `int1` = 1: 64-bit architecture

  See also: `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `[` – start array

  ( — `mark1` )

  `mark1`: array start marker

  See also: `]`

  Example 6.

        [ 1 2 3 ]       % array with 3 elements

- `]` – complete array definition

  ( `mark1` `obj1` ... `objN` — `array1` )

  `mark1`: array start marker

  `obj1` ... `objN`: some objects

  `array1`: N-dimensional array with `obj1` ... `objN`

  Note: The array uses dynamically allocated memory which must be released using `free`

  See also: `[`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 7.

        /foo [ "some" "text" ] def      % array with 2 elements
        foo free                        % free memory

- `_readsector` – read sector

  ( `int1` — `ptr1` )

  `int1`: sector number

  `ptr1`: sector data

  Note: internal function. Returns pointer to static buffer. Does not return on error. Returns .undef if function is not implemented.

  See also: `64bit`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `abs` – absolute value

  ( `int1` — `int2` )

  `int2`: |`int1`|

  See also: `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 8.

        -6 abs          % 6

- `add` – addition

  ( `int1` `int2` — `int3` )

  ( `string1` `int4` — `string2` )

  ( `ptr1` `int5` — `ptr2` )

  `int3`: `int1` + `int2`

  `string2`: substring of `string1` at offset `int4`

  Note: Strings are treated as byte sequences, not Unicode chars. Sizes of `string1` and `ptr1` are not checked.

  See also: `abs`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 9.

        1 2 add         % 3

        "abc" 1 add     % "bc"

- `and` – logical or arithmetical 'and'

  ( `int1` `int2` — `int3` )

  ( `bool1` `bool2` — `bool3` )

  `int3`: `int1` & `int2`

  `bool3`: `bool1` && `bool2`

  Note: Mixing boolean and integer argument types is possible, in this case integers are converted to boolean first.

  See also: `abs`, `add`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 10.

        true false and          % false

        3 6 and                 % 2

        10 true and             % gives true, but please avoid this

- `array` – create an empty array

  ( `int1` — `array1` )

  `int1`: array dimension

  `array1`: new array

  Note: Use `free` to free `array1`.

  See also: `]`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 11.

        /foo 10 array def       % create array with 10 elements
        foo 4 123 put           % foo[4] = 123
        foo free                % free foo

- `blend` – - blend image with alpha channel

  ( `obj1` `obj2` `ptr3` — )

  `obj1`: pointer to source image or color value

  `obj2`: pointer to alpha channel or transparency value

  `ptr3`: destination

  An image section of `obj1` is copied to `ptr3` using `obj2` as alpha channel. `obj1` may be a color value or an unpacked image (`unpackimage`, `savescreen`). `obj2` may be a transparency value (0..255) or an unpacked image used as alpha channel. The current cursor position is used as offset into `obj1` and `obj2` if they are images. If both `obj1` and `obj2` are images, they must have the same dimensions.

  Note: 16/32-bit modes only.

  See also: `currentimage`, `image`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

- `chdir` – set current working directory

  ( `str1` — )

  `str1`: file name

  See also: `]`, `array`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 12.

        "/foo/bar" chdir        % set working directory

- `colorbits` – current pixel size

  ( — `int1` )

  `int1`: pixel size in bits

  See also: `currentmode`, `monitorsize`, `screen.size`, `setmode`, `sysinfo`, `videomodeinfo`, `videomodes`, `vscreen.size`

- `currentcolor` – current drawing color

  ( — `int1` )

  `int1`: palette index (8-bit mode) or 24-bit RGB-value (16/32-bit modes).

  See also: `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 13.

        currentcolor not setcolor       % inverse color

- `currenteotchar` – current alternative end-of-text char

  ( — `int1` )

  `int1`: eot char

  See also: `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `currentfont` – get current font

  ( — `ptr1` )

  `ptr1`: current font

  See also: `fontheight`, `lineheight`, `setfont`

  Example 14.

        currentfont                             % save font
        "16x16_bold.fnt" findfile setfont       % set bold font
        "bold text" show                        % write something in bold font
        setfont                                 % back to normal font

- `currentimage` – currently used image

  ( — `ptr1` )

  See also: `blend`, `image`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

- `currentlink` – currently selected link

  ( — `int1` )

  `int1`: selected link

  See also: `currenteotchar`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `currentmaxrows` – - current maxium number of text rows to display

  ( — `int1` )

  `int1`: maxium number of text rows to display in a single `show` command.

  See also: `currenteotchar`, `currentlink`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `currentmode` – current video mode

  ( — `int1` )

  `int1`: current video mode number

  See also: `colorbits`, `monitorsize`, `screen.size`, `setmode`, `sysinfo`, `videomodeinfo`, `videomodes`, `vscreen.size`

- `currentpoint` – current cursor position

  ( — `int1` `int2` )

  `int1`, `int2`: x, y (upper left: 0, 0)

  See also: `currentcolor`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

- `currenttextcolors` – current text markup colors

  ( — `int1` `int2` `int3` `int4` )

  `int1`: normal color

  `int2`: highlight color

  `int3`: link color

  `int4`: selected link color

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `currenttextwrap` – current text wrap column

  ( — `int1` )

  `int1`: text wrap column

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `currenttitle` – current page title

  ( — `str1` )

  `str1`: page title

  Note: available after running `formattext`

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `currenttransparency` – current transparency

  ( — `int1` )

  See also: `currentcolor`, `currentpoint`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

- `date` – get current date

  ( — `int1` )

  `int1`: date (bit 0-7: day, bit 8-15: month, bit 16-31: year)

  See also: `64bit`, `_readsector`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `def` – define new word

  ( `dict1` `obj1` — )

  `dict1`: is defined as `obj1`

  See also: `{`, `}`

  Example 15.

        /x 100 def              % define constant x as 100

        /neg { -1 mul } def     % define 'neg' function

- `div` – division

  ( `int1` `int2` — `int3` )

  `int3`: `int1` / `int2`

  See also: `abs`, `add`, `and`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 16.

        17 3 div        % 5

- `dtrace` – single step with debug window

  ( — )

  Turn on `trace` mode and show debug info in upper left screen corner.

  See also: `trace`

- `dumpmem` – dump memory usage to console

  ( — )

  Note: useful only for debugging.

  See also: `]`, `array`, `chdir`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

- `dup` – duplicate TOS

  ( `obj1` — `obj1` `obj1` )

  See also: `exch`, `index`, `over`, `pop`, `roll`, `rot`

  Example 17.

        key                             % key: some input value
        dup 'a' eq { do_a } if          % if key = 'a'
        dup 'b' eq { do_b } if          % if key = 'b'
        dup 'c' eq { do_c } if          % if key = 'c'
        pop

- `edit.done` – restore input field background

  ( `array1` — )

  `array1`: see `edit.init`

  Note: does not free any data associated with `array1`.

  See also: `edit.hidecursor`, `edit.init`, `edit.input`, `edit.redraw`, `edit.showcursor`

  Example 18.

        ed edit.done    % delete input field

- `edit.hidecursor` – hide input field cursor

  ( `array1` — )

  `array1`: see `edit.init`

  See also: `edit.done`, `edit.init`, `edit.input`, `edit.redraw`, `edit.showcursor`

- `edit.init` – - setup and show an editable input field

  ( `array1` `str1` — )

  `str1`: initial input string value

  `array1`: (at least) 6-dimensional array: [ x y bg buf buf_size .undef ]. x, y: input field position; bg: background pixmap (created with `savescreen`) - this determines the input field dimensions, too; buf: string buffer, large enough for a string of length buf_size. The last element is used internally.

  See also: `edit.done`, `edit.hidecursor`, `edit.input`, `edit.redraw`, `edit.showcursor`

  Example 19.

        50 100 moveto 200 20 savescreen /bg exch def
        /buf 100 string def
        /ed [ 50 100 bg buf 100 .undef ] def
        ed "foo" edit.init

- `edit.input` – edit field input processing

  ( `array1` `int1` — )

  `array1`: see `edit.init`

  `int1`: key (bits 0-23 Unicode char, bits 24-31 scan code)

  See also: `edit.done`, `edit.hidecursor`, `edit.init`, `edit.redraw`, `edit.showcursor`

  Example 20.

        /keyLeft 0x4b000000 def         % move cursor left
        ed 'a' edit.input
        ed keyLeft edit.input

- `edit.redraw` – redraw input field

  ( `array1` — )

  `array1`: see `edit.init`

  See also: `edit.done`, `edit.hidecursor`, `edit.init`, `edit.input`, `edit.showcursor`

  Example 21.

        ed edit.redraw          % redraw input field

- `edit.showcursor` – show input field cursor

  ( `array1` — )

  `array1`: see `edit.init`

  See also: `edit.done`, `edit.hidecursor`, `edit.init`, `edit.input`, `edit.redraw`

- `eject` – eject CD-ROM

  ( `int1` — `int2` )

  `int1`: BIOS drive id

  `int2`: BIOS error code

  Note: does not work with all BIOSes. (With very few, actually.)

  See also: `64bit`, `_readsector`, `date`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `eq` – equal

  ( `int1` `int2` — `bool1` )

  ( `str1` `str2` — `bool2` )

  ( `obj1` `obj2` — `bool3` )

  `bool1`: true if `int1` == `int2`

  `bool2`: true if `str1` == `str2`

  `bool3`: true if `obj1` and `obj2` are identical

  See also: `ge`, `gt`, `le`, `lt`, `ne`

  Example 22.

        1 3 eq                  % false
        "abc" "abc" eq          % true
        /a [ 1 2 ] def
        /b a def
        a [ 1 2 ] eq            % false (not the same array)
        a b eq                  % true

- `exch` – exchange TOS with TOS-1

  ( `obj1` `obj2` — `obj2` `obj1` )

  See also: `dup`, `index`, `over`, `pop`, `roll`, `rot`

  Example 23.

        8
        /a exch def     % a = 8

- `exec` – evaluate object

  ( `dict1` — )

  ( `obj1` — `obj1` )

  If `obj1` is a dictionary entry, it is looked up and evaluated. If not, the stack is left unchanged.

  Note: Unlike Postscript, no cvx is necessary. And it works only with dictionary references.

  See also: `exit`, `for`, `forall`, `if`, `ifelse`, `loop`, `repeat`, `return`

  Example 24.

        /foo [ /bar 100 "abc" ] def
        foo 0 get                       % /bar
        exec                            % run bar
        foo 2 get                       % "abc"
        exec                            % still "abc"

- `exit` – leave loop/repeat/for/forall loop.

  ( — )

  See also: `exec`, `for`, `forall`, `if`, `ifelse`, `loop`, `repeat`, `return`

  Example 25.

        0 1 100 { 56 eq { exit } if } for       % leave if counter == 56

- `filesize` – get file size

  ( `str1` — `int1` )

  `str1`: file name

  `int1`: file length (or .undef if not found)

  Note: Unlike `findfile`, it doesn't load the file.

  See also: `]`, `array`, `chdir`, `dumpmem`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 26.

        "xxx.jpg" filesize      % file size of "xxx.jpg"

- `fillrect` – fill rectangular area

  ( `int1` `int2` — )

  `int1`, `int2`: width, height

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 27.

        0 0 moveto
        blue setcolor
        300 200 fillrect        % 300x200 blue rectangle

- `findfile` – load file

  ( `str1` — `ptr1` )

  `str1`: file name

  `ptr1`: buffer with file data

  Note: `ptr1` may or may not have to be free'd using `free`, depending on whether it is actually loaded from file system or is part of the bootlogo archive. To be on the safe side, always free it.

  To get the file length, use `length` on `ptr1`.

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 28.

        "xxx.jpg" findfile length       % file size of "xxx.jpg"

- `fontheight` – font height

  ( — `int1` )

  `int1`: font height

  See also: `currentfont`, `lineheight`, `setfont`

  Example 29.

        currentpoint
        "Hello" show                    % print "Hello"
        moveto 0 fontheight rmoveto
        "world!"                        % print "world!" below "Hello"

- `for` – - typical 'for' loop

  ( `int1` `int2` `int3` `code1` — )

  `int1`: start value

  `int2`: step size

  `int3`: final value (inclusive)

  Run `code1` and put the current counter value onto the stack for every iteration.

  See also: `exec`, `exit`, `forall`, `if`, `ifelse`, `loop`, `repeat`, `return`

  Example 30.

        0 1 4 { } for           % leave 0 1 2 3 4 on the stack

- `forall` – loop over all array elements

  ( `array1` `code` `1` — )

  ( `str1` `code` `1` — )

  ( `ptr1` `code` `1` — )

  Run code1 for every element of `array1`, `str1` or `ptr1` putting each element on the stack in turn.

  Note: `str1` is treated as a sequence of bytes, not utf8 chars.

  See also: `exec`, `exit`, `for`, `if`, `ifelse`, `loop`, `repeat`, `return`

  Example 31.

        [ 1 2 3 ] { } forall    % leave 1 2 3 on the stack

- `formattext` – - format text

  ( `str1` — )

  `str1`: text

  Preprocess text to find (and remember) line breaks, links and stuff.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `free` – free memory

  ( `obj1` — )

  `obj1`: object to free, either array, string or pointer

  Note: There is no garbage collector implemented. You have to keep track of memory usage yourself. If `obj1` does not refer to some dynamically allocated object, `free` does nothing.

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 32.

        2 array                 % create array with 2 elements...
        free                    % and free it

        100 malloc              % allocate 100 bytes...
        free                    % and free it

        "Some Text" free        % free nothing

- `ge` – greater or equal

  ( `int1` `int2` — `bool1` )

  ( `str1` `str2` — `bool2` )

  ( `ptr1` `ptr2` — `bool3` )

  `bool1`: true if `int1` >= `int2`

  `bool2`: true if `str1` >= `str2`

  `bool3`: true if `ptr1` >= `ptr2`

  See also: `eq`, `gt`, `le`, `lt`, `ne`

  Example 33.

        7 4 ge                  % true
        "abc" "abc" ge          % true
        /a 10 malloc def
        /b a + 2 def
        b a ge                  % true

- `get` – get array, string or memory element

  ( `array1` `int1` — `obj1` )

  ( `string1` `int2` — `int3` )

  ( `ptr1` `int4` — `int5` )

  `obj1`: `int1`-th element of `array1`

  `int3`: `int2`-th byte of `string1`

  `int5`: `int4`-th byte of `ptr1`

  Note: Returns the n-th byte of `string1`, not the n-th utf8 char. Sizes of `string1` or `ptr1` are not checked.

  See also: `put`

  Example 34.

        "abc" 1 get             % 'b'

        [ 10 20 30 ] 2 get      % 30

- `getbyte` – get byte from memory

  ( `ptr1` — `int1` )

  `int1`: byte at `ptr1`

  See also: `64bit`, `_readsector`, `date`, `eject`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `getcwd` – get current working directory

  ( — `str1` )

  `str1`: file name

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `length`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 35.

        getcwd show     % print working directory

- `getdword` – get dword from memory

  ( `ptr1` — `int1` )

  `int1`: dword at `ptr1`

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `getkey` – get keyboard input

  ( — `int1` )

  `int1`: key (bit 0-7: ASCII, bit 8-15: scan code, bit 16-31: kbd status bits)

  Note: the function does not block. If there is no key pressed, bits 0-15 will be 0.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `getlink` – - get link information

  ( `int1` — `str1` `str2` `int2` `int3` )

  `int1`: link number

  `str1`: link label

  `str2`: link text

  `int1`: link text x-offset

  `int2`: link text row

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `getlinks` – - number of links in text

  ( — `int1` )

  `int1`: number of links in text.

  Note: available after running `formattext`

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `getpalette` – get palette entry

  ( `int1` — `int2` )

  `int1`: palette index

  `int2`: RGB value

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 36.

        11 dup getpalette not setpalette        % invert color 11

- `getpixel` – read pixel from graphics memory

  ( — `int1` )

  `int1`: color; either 8-bit palette index or 24-bit RGB-value, depending on graphics mode.

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 37.

        getpixel not setcolor putpixel          % invert pixel color

- `gettextrows` – number of text rows

  ( — `int1` )

  `int1`: total number of text rows.

  Note: available after running `formattext`

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `gettype` – get object type

  ( `obj1` — `int1` )

  Returns the object type.

  See also: `settype`

  Example 38.

        "abc" gettype           % 4 (= string)

- `getword` – get word from memory

  ( `ptr1` — `int1` )

  `int1`: word at `ptr1`

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `gt` – greater than

  ( `int1` `int2` — `bool1` )

  ( `str1` `str2` — `bool2` )

  ( `ptr1` `ptr2` — `bool3` )

  `bool1`: true if `int1` > `int2`

  `bool2`: true if `str1` > `str2`

  `bool3`: true if `ptr1` > `ptr2`

  See also: `eq`, `ge`, `le`, `lt`, `ne`

  Example 39.

        7 4 gt                  % true
        "abc" "abd" gt          % false
        /a 10 malloc def
        /b a + 2 def
        b a gt                  % true

- `idle` – run stuff when idle

  ( `ptr1` `int1` — )

  `ptr1`: 'kroete' data

  `int1`: direction (0 or 1)

  Run 'kroete' animation while we're waiting for keyboard input.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `if` – typical 'if'

  ( `bool1` `code1` — )

  ( `int1` `code1` — )

  ( `undef1` `code1` — )

  ( `obj1` `code1` — )

  `bool1`: contition

  `code1`: code start marker (see `{`)

  `int1`: integer are automatically converted to boolean

  `undef1`: the undefined value is treated as 'false'

  `obj1`: strings, arrays, pointer are considered 'true'

  See also: `exec`, `exit`, `for`, `forall`, `ifelse`, `loop`, `repeat`, `return`

  Example 40.

        10 4 gt { "10 > 4" show } if

        "" { "is always true" show } if         % strings are always 'true'

- `ifelse` – typical 'if' / 'else'

  ( `bool1` `code1` `code2` — )

  ( `int1` `code1` `code2` — )

  ( `undef1` `code1` `code2` — )

  ( `obj1` `code1` `code2` — )

  `bool1`: contition

  `code1`: code start marker (see `{`) for 'true' branch

  `code2`: code start marker (see `{`) for 'false' branch

  `int1`: integer are automatically converted to boolean

  `undef1`: the undefined value is treated as 'false'

  `obj1`: strings, arrays, pointer are considered 'true'

  See also: `exec`, `exit`, `for`, `forall`, `if`, `loop`, `repeat`, `return`

  Example 41.

        x1 x2 gt { "x1 > x2" } { "x1 <= x2" } ifelse show

- `image` – show image region

  ( `int1` `int2` `int3` `int4` — )

  `int1`, `int2`: x, y position in image

  `int3`, `int4`: width, height of image region

  See also: `blend`, `currentimage`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

  Example 42.

        "xxx.jpg" findfile setimage     % load and activate "xxx.jpg"
        0 0 image.size image            % draw whole image

- `image.colors` – image palette entries

  ( — `int1` )

  `int1`: number of colors in 8-bit PCX image.

  8-bit modes use a color palette. An image uses the first `image.colors` entries. If you want to define your own colors, use `image.colors` to get the first free palette entry. For 16/32-bit modes, 0 is returned.

  See also: `blend`, `currentimage`, `image`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

- `image.size` – graphics image size

  ( — `int1` `int2` )

  `int1`, `int2`: image width and height. The image is specified with `setimage`

  See also: `blend`, `currentimage`, `image`, `image.colors`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

  Example 43.

        image.size screen.size
        exch 4 -1 roll sub 2 div 3 1 roll exch sub 2 div        % center image
        moveto 0 0 image.size image                             % draw it

- `inbyte` – get byte from i/o port

  ( `int1` — `int2` )

  `int2`: byte from port `int1`

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `index` – copy stack element

  ( `objN` ... `obj1` `int1` — `objN` ... `obj1` `objM` )

  `objM`: M = `int1` + 1

  See also: `dup`, `exch`, `over`, `pop`, `roll`, `rot`

  Example 44.

        /dup { 0 index } def
        /over { 1 index } def

- `keepmode` – keep video mode

  ( `int1` — )

  `int1` = 1: keep video mode when starting kernel.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `le` – less or equal

  ( `int1` `int2` — `bool1` )

  ( `str1` `str2` — `bool2` )

  ( `ptr1` `ptr2` — `bool3` )

  `bool1`: true if `int1` <= `int2`

  `bool2`: true if `str1` <= `str2`

  `bool3`: true if `ptr1` <= `ptr2`

  See also: `eq`, `ge`, `gt`, `lt`, `ne`

  Example 45.

        7 7 le                  % true
        "abc" "abd" le          % true
        /a 10 malloc def
        /b a + 2 def
        b a le                  % false

- `length` – array, string or memory size

  ( `array1` — `int1` )

  ( `string1` — `int1` )

  ( `ptr1` — `int1` )

  `int1`: size of `array1` or `string1` or `ptr1`

  Returns the length of `string1` in bytes, not the number of Unicode chars. If `ptr1` doesn't point at the start of a memory area, `length` returns the number of remaining bytes.

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `malloc`, `memcpy`, `memsize`, `snprintf`

  Example 46.

        "abc" length            % 3

        [ 0 1 ] length          % 2

        /foo 10 malloc def
        foo length              % 10
        foo 3 add length        % 7

- `lineheight` – current line height

  ( — `int1` )

  `int1`: line height

  See also: `currentfont`, `fontheight`, `setfont`

- `lineto` – draw line

  ( `int1` `int2` — )

  `int1`, `int2`: line end

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 47.

        0 0 moveto screen.size lineto           % draw diagonal

- `loadpalette` – load current palette

  ( — )

  Activates current palette in 8-bit modes.

  See also: `blend`, `currentimage`, `image`, `image.colors`, `image.size`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

- `loop` – endless loop

  ( `code1` — )

  See also: `exec`, `exit`, `for`, `forall`, `if`, `ifelse`, `repeat`, `return`

  Example 48.

        /x 0 def { /x x 1 add def x 56 eq { exit } if } loop    % loop until x == 56

- `lt` – less than

  ( `int1` `int2` — `bool1` )

  ( `str1` `str2` — `bool2` )

  ( `ptr1` `ptr2` — `bool3` )

  `bool1`: true if `int1` < `int2`

  `bool2`: true if `str1` < `str2`

  `bool3`: true if `ptr1` < `ptr2`

  See also: `eq`, `ge`, `gt`, `le`, `ne`

  Example 49.

        7 4 lt                  % false
        "abc" "abd" lt          % true
        /a 10 malloc def
        /b a + 2 def
        b a lt                  % false

- `malloc` – allocate memory

  ( `int1` — `ptr1` )

  `int1`: memory size

  `ptr1`: pointer to memory area

  Note: Use `free` to free `ptr1`.

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `memcpy`, `memsize`, `snprintf`

  Example 50.

        /foo 256 malloc def     % allocate 256 bytes...
        foo free                % and free it

- `max` – maximum

  ( `int1` `int2` — `int3` )

  `int3`: max(`int1`, `int2`)

  See also: `abs`, `add`, `and`, `div`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 51.

        4 11 max        % 11

- `memcpy` – copy memory

  ( `ptr1` `ptr2` `int1` — )

  `ptr1`: destination

  `ptr2`: source

  `int1`: size

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memsize`, `snprintf`

  Example 52.

        /a 10 malloc def
        /b 10 malloc def
        a 1 100 put             % a[1] = 100
        b a 10 memcpy           % copy a to b

- `memsize` – report available memory size

  ( `int1` — `int2` `int3` )

  `int1`: memory region (0 ... 3)

  `int2`: total free memory

  `int3`: size of largest free block

  Region 0 is memory in the low 640kB range. Region >= 1 are typically 1 MB extended memory per region.

  Note: available memory depends on the boot loader.

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `snprintf`

  Example 53.

        0 memsize pop 1024 lt { "less than 1kB left" show } if

- `min` – minimum

  ( `int1` `int2` — `int3` )

  `int3`: min(`int1`, `int2`)

  See also: `abs`, `add`, `and`, `div`, `max`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 54.

        4 11 min        % 4

- `mod` – remainder

  ( `int1` `int2` — `int3` )

  `int3`: `int1` % `int2`

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 55.

        17 3 mod        % 2

- `mod.load` – assign mod file to player

  ( `int1` `ptr1` — )

  `int1`: player

  `ptr1`: mod file

  See also: `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `mod.play` – play mod file

  ( `int1` `int2` — )

  `int1`: player

  `int2`: song start

  Note: sounds are played using the PC speaker.

  See also: `mod.load`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `mod.playsample` – play mod sample

  ( `int1` `int2` `int3` `int4` — )

  `int1`: player

  `int2`: channel

  `int3`: sample number

  `int4`: pitch

  See also: `mod.load`, `mod.play`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `monitorsize` – monitor size

  ( — `int1` `int2` )

  `int1`, `int2`: width and height

  See also: `colorbits`, `currentmode`, `screen.size`, `setmode`, `sysinfo`, `videomodeinfo`, `videomodes`, `vscreen.size`

- `moveto` – set cursor position

  ( `int1` `int2` — )

  `int1`, `int2`: x, y (upper left: 0, 0).

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 56.

        200 100 moveto "Hello" show     % print "Hello" at (200, 100)

- `mul` – multiplication

  ( `int1` `int2` — `int3` )

  `int3`: `int1` * `int2`

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `neg`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 57.

        2 3 mul         % 6

- `ne` – not equal

  ( `int1` `int2` — `bool1` )

  ( `str1` `str2` — `bool2` )

  ( `obj1` `obj2` — `bool3` )

  `bool1`: false if `int1` == `int2`

  `bool2`: false if `str1` == `str2`

  `bool3`: false if `obj1` and `obj2` are identical

  See also: `eq`, `ge`, `gt`, `le`, `lt`

  Example 58.

        1 3 ne                  % true
        "abc" "abc" ne          % false
        /a [ 1 2 ] def
        /b a def
        a [ 1 2 ] ne            % true (not the same array)
        a b ne                  % false

- `neg` – negation

  ( `int1` — `int2` )

  `int2`: -`int1`

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `not`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 59.

        5 neg           % -5

- `not` – logical or arithmetical 'not'

  ( `int1` — `int2` )

  ( `bool1` — `bool2` )

  `int2`: -`int1` - 1

  `bool2`: !`bool1`

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `or`, `shl`, `shr`, `sub`, `xor`

  Example 60.

        true not        % false

        0 not           % -1

- `notimeout` – turn off initial boot loader timeout

  ( — )

  Turns off any automatic booting.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `or` – logical or arithmetical 'or'

  ( `int1` `int2` — `int3` )

  ( `bool1` `bool2` — `bool3` )

  `int3`: `int1` | `int2`

  `bool3`: bool || `bool2`

  Note: Mixing boolean and integer argument types is possible, in this case integers are converted to boolean first.

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `shl`, `shr`, `sub`, `xor`

  Example 61.

        true false or           % true

        3 6 or                  % 7

        10 true or              % gives true, but please avoid this

- `outbyte` – write byte to i/o port

  ( `int1` `int2` — )

  Write byte `int2` to port `int1`.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `over` – copy TOS-1

  ( `obj1` `obj2` — `obj1` `obj2` `obj1` )

  See also: `dup`, `exch`, `index`, `pop`, `roll`, `rot`

- `pop` – remove TOS

  ( `obj1` — )

  See also: `dup`, `exch`, `index`, `over`, `roll`, `rot`

  Example 62.

                                        % status: true or false
        "bad" status { pop "ok" } if    % "bad" or "ok"

- `poweroff` – switch computer off

  ( — )

  Note: uses APM, not ACPI.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `put` – set an array, string or memory element

  ( `array1` `int1` `obj1` — )

  ( `string1` `int2` `int3` — )

  ( `ptr1` `int4` `int5` — )

  `int1`-th element of `array1` = `obj1`

  `int2`-th byte of `string1` = `int3`

  `int4`-th byte of `ptr1` = `int5`

  Note: Sets the n-th byte of `string1`, not the n-th utf8 char. Sizes of `string1` or `ptr1` are not checked.

  See also: `get`

  Example 63.

        /foo [ 10 20 30 ] def
        foo 2 77 put                    % foo = [ 10 20 77 ]

        /foo 10 string def
        foo 0 'a' put
        foo 1 'b' put                   % foo = "ab"

        But don't do this:
        "abc" 1 'X' put                 % modifies string constant "abc" to "aXc"!

- `putbyte` – write byte to memory

  ( `ptr1` `int1` — )

  Write byte `int1` at `ptr1`.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `putdword` – write dword to memory

  ( `ptr1` `int1` — )

  Write dword `int1` at `ptr1`.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `putpixel` – draw single pixel

  ( — )

  Draw pixel in current color at current cursor position.

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `rmoveto`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 64.

        blue setcolor
        0 0 moveto putpixel     % blue dot at upper left corner

- `putword` – write word to memory

  ( `ptr1` `int1` — )

  Write word `int1` at `ptr1`.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `reboot`, `sysconfig`, `test1`, `time`, `usleep`

- `reboot` – reboot computer

  ( — )

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `sysconfig`, `test1`, `time`, `usleep`

- `repeat` – repeat code

  ( `int1` `code1` — )

  Repeat `code1` `int1` times.

  See also: `exec`, `exit`, `for`, `forall`, `if`, `ifelse`, `loop`, `return`

  Example 65.

        3 { "X" show } repeat           % print "XXX"

- `restorescreen` – restore screen area

  ( `ptr1` — )

  `ptr1`: buffer with image data; use `free` to free the buffer

  Note: width and height are taken from buffer. Does not actually free `ptr1` - use `free` explicitly.

  See also: `blend`, `currentimage`, `image`, `image.colors`, `image.size`, `loadpalette`, `savescreen`, `setimage`, `settransparentcolor`, `unpackimage`

  Example 66.

        0 0 moveto 100 100 savescreen           % save upper left 100x100 section...
        300 200 moveto dup restorescreen        % and copy it to 300x200
        free                                    % free memory

- `return` – leave current function

  ( — )

  See also: `exec`, `exit`, `for`, `forall`, `if`, `ifelse`, `loop`, `repeat`

  Example 67.

        /x {                                    % expects key on TOS
        dup 'a' eq { pop do_a return } if
        dup 'b' eq { pop do_b return } if
        dup 'c' eq { pop do_c return } if
        pop
        } def

- `rmoveto` – set relative cursor position

  ( `int1` `int2` — )

  `int1`, `int2`: x-ofs, y-ofs.

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `setcolor`, `setpalette`, `settransparency`, `show`

  Example 68.

        200 100 moveto
        "Hello" show
        30 0 rmoveto "world!"           % "Hello    world!" (approx.)

- `roll` – rotate stack elements

  ( `obj1` ... `objN` `int1` `int2` — `objX` ... `objY` )

  `int1`: number of elements to rotate

  `int2`: amount

  `objX`: X = (1 - `int2`) mod `int1`

  `objY`: Y = (N - `int2`) mod `int1`

  See also: `dup`, `exch`, `index`, `over`, `pop`, `rot`

  Example 69.

        /rot { 3 -1 roll } def
        1 2 3 4 5 5 2 roll              % leaves: 4 5 1 2 3

- `rot` – rotate TOS, TOS-1, TOS-2

  ( `obj1` `obj2` `obj3` — `obj2` `obj3` `obj1` )

  See also: `dup`, `exch`, `index`, `over`, `pop`, `roll`

  Example 70.

        /a 4 array def
        8
        a 1 rot put             % a[1] = 8

- `savescreen` – save screen area

  ( `int1` `int2` — `ptr1` )

  `int1`, `int2`: width, height of screen area

  `ptr1`: buffer with image data; use `free` to free the buffer

  Note: width and height are stored in buffer.

  See also: `blend`, `currentimage`, `image`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `setimage`, `settransparentcolor`, `unpackimage`

  Example 71.

        0 0 moveto screen.size savescreen       % save entire screen

- `screen.size` – screen size in pixel

  ( — `int1` `int2` )

  `int1`, `int2`: width, height

  See also: `colorbits`, `currentmode`, `monitorsize`, `setmode`, `sysinfo`, `videomodeinfo`, `videomodes`, `vscreen.size`

  Example 72.

        blue setcolor
        0 0 moveto screen.size fillrect         % draw blue screen

- `setcolor` – set active drawing color

  ( `int1` — )

  `int1`: palette index (8-bit mode) or 24-bit RGB-value (16/32-bit modes).

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setpalette`, `settransparency`, `show`

  Example 73.

        0xff0000 setcolor       % continue in red...
        0xff00 setcolor         % or green...
        0xff setcolor           % or blue

- `seteotchar` – set alternative end-of-text char

  ( `int1` — )

  `int1`: eot char

  Normally strings are 0 terminated. `seteotchar` lets you define an additional char text functions recognize.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `setfont` – set font

  ( `ptr1` — )

  `ptr1`: font data (e.g. font file).

  Note: If bit 31 in `ptr1` is set, font is in 'password-mode' - it prints only '*'s.

  See also: `currentfont`, `fontheight`, `lineheight`

  Example 74.

        "16x16.fnt" findfile setfont                            % set 16x16 font

        /pwmode { 1 settype 0x80000000 or 12 settype } def
        currentfont pwmode setfont                              % now in password mode
        "abc" show                                              % print "***"

- `setimage` – set active image

  ( `ptr1` — )

  `ptr1`: image data. Either JPG or PCX file.

  Note: JPG is only supported in 16/32-bit modes.

  See also: `blend`, `currentimage`, `image`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `settransparentcolor`, `unpackimage`

  Example 75.

        "foo.jpg" findfile setimage     % load and use "foo.jpg"

- `setlink` – select link

  ( `int1` — )

  `int1`: link number

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `setmaxrows` – maximum number of text rows to display

  ( `int1` — )

  `int1`: maximum number of text rows to display in a single `show` command.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setstartrow`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `setmode` – set video mode

  ( `int1` — `bool1` )

  `int1`: VESA or VGA mode number

  `bool1`: true = mode is set, false = failed

  Note: if video mode setting fails, the old mode is restored, but the screen contents is undefined.

  See also: `colorbits`, `currentmode`, `monitorsize`, `screen.size`, `sysinfo`, `videomodeinfo`, `videomodes`, `vscreen.size`

- `setpalette` – set palette entry

  ( `int1` `int2` — )

  `int1`: palette index

  `int2`: RGB value

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `settransparency`, `show`

  Example 76.

        /red 11 0xff0000 def            % color 11 = red
        /yellow 12 0xffff00 def         % color 12 = yellow

- `setstartrow` – set start row

  ( `int1` — )

  `int1`: start row for next `show` command.

  Note: if a start row > 0 is set, the argument to `show` is irrelevant. Instead the internal data built during the last `formattext` is used.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `settextcolors`, `settextwrap`, `show`, `strsize`

- `settextcolors` – - set text markup colors

  ( `int1` `int2` `int3` `int4` — )

  `int1`: normal color

  `int2`: highlight color

  `int3`: link color

  `int4`: selected link color

  Note: `int1` can be changed using `setcolor`, too.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextwrap`, `show`, `strsize`

- `settextmodecolor` – set color to be used in text mode

  ( `int1` — )

  `int1`: text mode color

  Note: You only need this in case you're running in text mode (practically never).

- `settextwrap` – set text wrap column

  ( `int1` — )

  `int1`: text wrap column; set to 0 to turn text wrapping off.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `show`, `strsize`

- `settransparency` – set transparency

  ( `int1` — )

  `int1`: transparency for `fillrect` operations; valid values are 0 - 256.

  See also: `currentcolor`, `currentpoint`, `currenttransparency`, `fillrect`, `getpalette`, `getpixel`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `setpalette`, `show`

- `settransparentcolor` – set color used for transparency

  ( `int1` — )

  When doing an `image` operation, pixels with this color are not copied. Something like an alpha channel, actually. Works only with PCX images. Not at all related to `settransparency`

  See also: `blend`, `currentimage`, `image`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `unpackimage`

- `settype` – set object type

  ( `obj1` `int1` — `obj2` )

  `obj2`: `obj1` with type changed to `int1`.

  See also: `gettype`

  Example 77.

                                                        % PS-like 'string' function
        /string { 1 add malloc 4 settype } def          % 4 = string type
        10 string                                       % new empty string of length 10

- `shl` – shift left

  ( `int1` `int2` — `int3` )

  `int3`: `int1` << `int2`

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shr`, `sub`, `xor`

  Example 78.

        5 2 shl         % 20

- `show` – print text

  ( `str1` — )

  Print `str1` in current color using current font.

  See also: `currentcolor`, `currenteotchar`, `currentlink`, `currentmaxrows`, `currentpoint`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `currenttransparency`, `fillrect`, `formattext`, `getlink`, `getlinks`, `getpalette`, `getpixel`, `gettextrows`, `lineto`, `moveto`, `putpixel`, `rmoveto`, `setcolor`, `seteotchar`, `setlink`, `setmaxrows`, `setpalette`, `setstartrow`, `settextcolors`, `settextwrap`, `settransparency`, `strsize`

  Example 79.

        "Hello world!" show     % print "Hello world!"

- `shr` – shift right

  ( `int1` `int2` — `int3` )

  `int3`: `int1` >> `int2`

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `sub`, `xor`

  Example 80.

        15 2 shr        % 3

- `snprintf` – C-style snprintf

  ( `obj1` ... `objN` `str1` `int1` `ptr1` — )

  `ptr1`: buffer

  `int1`: buffer size

  `str1`: format string

  `obj1` ... `objN`: printf arguments

  Note: reversed argument order!

  See also: `]`, `array`, `chdir`, `dumpmem`, `filesize`, `findfile`, `free`, `getcwd`, `length`, `malloc`, `memcpy`, `memsize`

  Example 81.

        /sprintf {
        dup 12 settype length exch snprintf                     % 12 = pointer type
        } def

        /buf 100 string def
        "bar" "foo" 3 "%d %s %s" buf sprintf
        buf show                                                % print "3 foo bar"

- `sound.done` – turn off sound subsystem

  ( — )

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `sound.getsamplerate` – current sample rate

  ( — `int1` )

  `int1`: sample rate

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `sound.getvolume` – current sound volume

  ( — `int1` )

  `int1`: volume (0 .. 100)

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `sound.play` – play sound

  ( — )

  Note: obsolete. Sounds are played using the PC speaker.

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `sound.setsamplerate` – set sample rate

  ( `int1` — )

  `int1`: sample rate

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setvolume`, `wav.play`, `wav.playlater`

- `sound.setvolume` – set sound volume

  ( `int1` — )

  `int1`: volume (0 .. 100)

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `wav.play`, `wav.playlater`

- `strsize` – text dimensions

  ( `str1` — `int1` `int2` )

  `int1`, `int2`: width, height of `str1`.

  See also: `currenteotchar`, `currentlink`, `currentmaxrows`, `currenttextcolors`, `currenttextwrap`, `currenttitle`, `formattext`, `getlink`, `getlinks`, `gettextrows`, `seteotchar`, `setlink`, `setmaxrows`, `setstartrow`, `settextcolors`, `settextwrap`, `show`

  Example 82.

        "Hi there!"
        dup strsize pop neg 0 rmoveto show      % print "Hi there!" right aligned

- `strstr` – find string in string

  ( `str1` `str2` — `int1` )

  Search for `str2` in `str1`.

  `int1`: offset of `str2` in `str1` + 1 if found; otherwise 0.

  Note: a bit strange, I know.

  Example 83.

        "abcd" "c" strstr       % 3 (not 2)

- `sub` – subtraction

  ( `int1` `int2` — `int3` )

  ( `string1` `int4` — `string2` )

  ( `ptr1` `int5` — `ptr2` )

  ( `string3` `string4` — `int6` )

  ( `ptr2` `ptr3` — `int7` )

  `int3`: `int1` - `int2`

  `string2`: substring of `string1` at offset -`int4`

  `int6`: `string3` - `string4`

  `int7`: `ptr2` - `ptr3`

  Note: Strings are treated as byte sequences, not Unicode chars. Boundaries of `string1` and `ptr1` are not checked.

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `xor`

  Example 84.

        3 1 sub         % 2

        "abcd" 3 add    % "d"
        2 sub           % "bcd"

- `sysconfig` – get pointer to boot loader config data

  ( — `ptr1` )

  `ptr1`: boot loader config data (32 bytes)

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `test1`, `time`, `usleep`

- `sysinfo` – return system info

  ( `int1` — `obj1` )

  `int1`: info type

  `obj1`: info (or .undef)

  See also: `colorbits`, `currentmode`, `monitorsize`, `screen.size`, `setmode`, `videomodeinfo`, `videomodes`, `vscreen.size`

  Example 85.

        0 sysinfo       % video mem size in kb
        1 sysinfo       % gfx card oem string
        2 sysinfo       % gfx card vendor string
        3 sysinfo       % gfx card product string
        4 sysinfo       % gfx card revision string

- `test1` – for internal testing

  ( `ptr1` — )

  `ptr1`: some value with obscure meaning

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `time`, `usleep`

  Example 86.

        0x123 test1

- `time` – get current time

  ( — `int1` )

  `int1`: time in seconds since midnight.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `usleep`

- `trace` – single step

  ( — )

  Enter single step mode. Waits for a keypress after every instruction. Tab sets a temporary breakpoint after the current instruction and continues until it reaches it. Leave this mode by pressing Esc.

  See also: `dtrace`

- `unpackimage` – unpack image region into buffer

  ( `int1` `int2` `int3` `int4` — `ptr1` )

  `int1`, `int2`: x, y position in image

  `int3`, `int4`: width, height of image region

  `ptr1`: buffer with image data; use `free` to free the buffer

  See also: `blend`, `currentimage`, `image`, `image.colors`, `image.size`, `loadpalette`, `restorescreen`, `savescreen`, `setimage`, `settransparentcolor`

  Example 87.

        "xxx.jpg" findfile setimage     % load and activate "xxx.jpg"
        0 0 10 10 unpackimage           % unpack upper left 10x10 region
        /img exch def                   % img = buffer

        0 10 100 {
        0 exch moveto
        img restorescreen
        } for                           % repeat image section horizontally 10 times

        img free                        % free it

- `usleep` – sleep micro seconds

  ( `int1` — )

  `int1`: micro seconds to sleep.

  Note: the actual granularity is 18Hz, so don't make up too sophisticated timings.

  See also: `64bit`, `_readsector`, `date`, `eject`, `getbyte`, `getdword`, `getkey`, `getword`, `idle`, `inbyte`, `keepmode`, `notimeout`, `outbyte`, `poweroff`, `putbyte`, `putdword`, `putword`, `reboot`, `sysconfig`, `test1`, `time`

- `videomodeinfo` – return video mode info

  ( `int1` — `int2` `int3` `int4` `int5` )

  `int1`: mode index `int2`, `int3`: width, height

  `int4`: color bits

  `int5`: mode number (bit 14: framebuffer mode) or .undef

  See also: `colorbits`, `currentmode`, `monitorsize`, `screen.size`, `setmode`, `sysinfo`, `videomodes`, `vscreen.size`

  Example 88.

        2 videomodeinfo

- `videomodes` – video mode list length

  ( — `int1` )

  `int1`: video mode list length (always >= 1)

  See also: `colorbits`, `currentmode`, `monitorsize`, `screen.size`, `setmode`, `sysinfo`, `videomodeinfo`, `vscreen.size`

- `vscreen.size` – virtual screen size

  ( — `int1` `int2` )

  `int1`, `int2`: virtual width and height

  You normally can expect the virtual height to be larger than the visible height returned by `screen.size` That area is available e.g. for hidden drawing. Some kind of scrolling is not implemented, however.

  See also: `colorbits`, `currentmode`, `monitorsize`, `screen.size`, `setmode`, `sysinfo`, `videomodeinfo`, `videomodes`

- `wav.play` – play wav file

  ( `ptr1` — )

  `ptr1`: wav file

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.playlater`

- `wav.playlater` – play wav file after current one

  ( `ptr1` — )

  `ptr1`: wav file

  See also: `mod.load`, `mod.play`, `mod.playsample`, `sound.done`, `sound.getsamplerate`, `sound.getvolume`, `sound.play`, `sound.setsamplerate`, `sound.setvolume`, `wav.play`

- `xor` – logical or arithmetical exclusive 'or'

  ( `int1` `int2` — `int3` )

  ( `bool1` `bool2` — `bool3` )

  `int3`: `int1` ^ `int2`

  `bool3`: bool ^^ `bool2`

  Note: Mixing boolean and integer argument types is possible, in this case integers are converted to boolean first.

  See also: `abs`, `add`, `and`, `div`, `max`, `min`, `mod`, `mul`, `neg`, `not`, `or`, `shl`, `shr`, `sub`

  Example 89.

        true false xor          % true

        3 6 xor                 % 5

        10 true xor             % gives false, but please avoid this