Built-in Words #

This is the list of built-in RPCL words before any application specific extensions. Built-in RPCL words (including any application specific extensions registered later) are immutable with respect of the RPCL dictionary, whereas a predefined compound word can be redefined or deleted.

! #

stores a variable ( value name - )

Example:

ok 3 three !
ok three @ .
3
ok ▂

!! #

define compound word ( line name - )

Example:

ok "3 +" addthree !! 
ok 2 addthree .
5
ok ▂

* #

product of two values ( [n1] n2 - result )

* may also be called with one single value in the current stack frame (n1 then defaults to 1 as the neutral element of multiplication).

Example:

ok 3 4 * .
12
ok { 4 * } .
4
ok ▂

+ #

sum of two values ( [n1] n2 - sum )

+ may also be called with one single value in the current stack frame (n1 then defaults to 0 as the neutral element of addition).

Example:

ok 3 4 + .
7
ok { 2 + } .
2
ok ▂

- #

difference of two values ( n1 n2 - result )

Example:

ok 3 4 - .
-1
ok ▂

. #

print item ( item - )

known data subtypes except generic_t are shown underlined after conversion.

generic_t data is shown in hexdump style (as with .x).

Example:

ok "hello, world" .
hello, world
ok "10.1.1.1" str->ip_t .
::ffff:10.1.1.1
ok random64 .
0x4bcb286cfd056aac
ok random32 random32 datacat .
0000  21 fe 86 d4 aa 91 2b fa                           |!.....+.        |
ok ▂

.cs #

clear stack ( - )

Example:

ok 1 2 3 
ok .s
 2     string    1  "3"
 1     string    1  "2"
 0     string    1  "1"
ok .cs
ok .s
ok ▂

.d #

prints dictionary variables ( - )

RPCL predefined / native variables are shown in black

Variables defined lateron by other components or interactively appear in blue

Example:

ok 1 testvar ! 
ok .d
rpcl.platform                    Debian12-amd64
rpcl.version                     1.177
testvar                          1
ok ▂

.exec-sp #

returns the execution stack pointer ( - execsp )

Example:

ok .exec-sp .
1
ok ".exec-sp ." test !! 
ok test 
2
ok ▂

.i #

prints built-in words ( [substring] - )

RPCL predefined / native built-in words are shown in black.

Words registered lateron by other components appear in blue.

An optional substring allows to restrict the output to lines with a match.

Example:

ok .i
!                                stores a variable ( value name - )
!!                               define compound word ( line name - )
*                                product of two values ( n1 n2 - result )
+                                sum of two values ( n1 n2 - sum )
-                                difference of two values ( n1 n2 - result )
... truncated ...
ok ip_t .i
ip_t->str                        convert ip_t to str ( ip_t - str )
ip_t-expand                      expand ip_t to DNSBL substring ( ip_t - str )
str->ip_t                        convert str to ip_t ( str - ip_t )
ok ▂

.ii #

prints extended built-in words ( [substring] - )

This shows only built-in words, that have been registered additionally by other components (which appear in blue at .i).

Example with no extended words:

ok .ii
ok ▂

Example with extended words from an RPCL controlled IXDP application:

ok if. .ii
if.drivers                       show interfaces and drivers ( - )
if.enqueue                       enqueue packet for TX on interface ( packet interface - )
if.etype.show                    show rx Ethertype and VLAN statistics for interface ( i - )
if.mac.show                      show rx mac statistics for interface ( i - )
if.qstats                        show detailed queue/interface statistics ( queue interface - )
if.stats                         show summary statistics of all interfaces ( - )
ok ▂

.m #

prints internal memory allocations ( - )

This shows memory allocations that are specifically tracked.

Example:

ok .m
total_allocated_areas = 59
total_allocated_bytes = 33840
sizeof(MEMAREA)       = 64
-> size=       544 reference_counter=         1 file=            rpclsl.c line=       130
-> size=       544 reference_counter=         1 file=            rpclsl.c line=       130
-> size=       560 reference_counter=         1 file=            rpclsl.c line=       130
... truncated ...
ok ▂

.raw #

raw print item ( item - )

Example:

ok "f09f9880" hex->str .raw
😀
ok ▂

.s #

prints stack ( - )

Example:

ok 1 2 3 .s 
 0 [1]
 1 [2]
 2 [3]
ok ▂

.x #

print element in hexadecimal ( s - )

Example:

ok "hello" .x
0000  68 65 6c 6c 6f                                    |hello           |
ok ▂

/ #

quotient of two values ( n1 n2 - result )

Example:

ok 15 3 / . 
5
ok ▂

2drop #

drops two elements ( s1 s2 - )

Example:

ok 1 2 3 2drop .s 
 0 [1]
ok ▂

; #

synonym for ! ( value name - )

Example:

ok 1 one ; 
ok one @ .
1
ok ▂

< #

return #true if n1 < n2 ( n1 n2 - result )

Example:

ok 1 2 < .
#true
ok 1 1 < .

ok ▂

<= #

return #true if n1 <= n2 ( n1 n2 - result )

Example:

ok 1 2 <= .
#true
ok 1 1 <= .
#true
ok 2 1 <= .

ok ▂

== #

return #true if n1 == n2 ( n1 n2 - result )

Example:

ok 1 2 == .

ok 1 1 == .
#true
ok ▂

> #

return #true if n1 > n2 ( n1 n2 - result )

Example:

ok 1 2 > .

ok 1 1 > .

ok 2 1 > .
#true
ok ▂

>= #

return #true if n1 >= n2 ( n1 n2 - result )

Example:

ok 1 2 >= .

ok 1 1 >= .
#true
ok 2 1 > .
#true
ok ▂

@ #

fetch a variable ( name - value )

Example:

ok 2 two ; 
ok two @ .
2
ok ▂

@ne #

ne stands for “no error” here.

fetch a variable, "" if unknown ( name - value )

Example:

ok unknown-variable @ . 
Unknown variable unknown-variable
ERROR detected
ok unknown-variable @ne . 

ok ▂

argc #

returns argc ( - n )

Example:

ok argc . 
1
ok ▂

argv #

returns argv ( n - result )

Example:

ok 0 argv . 
rpclsh
ok 1 argv .
invalid argv index
ERROR detected
ok ▂

assert #

raise error when x is false ( x - )

Example:

ok 1 1 + 3 == assert  
assertion failed
ERROR detected
ok ▂

chdir #

change current working directory ( path - )

Example:

ok "/tmp" chdir 
ok getcwd .
/tmp
ok ▂

chomp #

removes a trailing newline ( s - s )

Example:

ok fgets dup .x chomp .x 
hello
0000  68 65 6c 6c 6f 0a                                 |hello.          |
0000  68 65 6c 6c 6f                                    |hello           |
ok ▂

fibonacci #

“dup 1 <=” "" “dup 1 - &fibonacci swap 2 - &fibonacci +” ifelse

The compound word fibonacci implements the Fibonacci series recursively. This is mainly for illustration and testing purposes.

Example:

ok 0 fibonacci .
0
ok 1 fibonacci .
1
ok { 0 1 2 3 4 5 6 swap-all "fibonacci ." eval-all }
0
1
1
2
3
5
8
ok ▂

copyright #

show Copyright information ( - )

ok copyright 
Copyright © 2025 Inlab Networks GmbH, Grünwald, Germany. All rights reserved.
ok ▂

cycleburn #

burn cycles ( iterations - )

Example:

ok 4 setaffinity 
ok 1000000000 cycleburn
ok timer-start 1000 cycleburn timer-show
6 microseconds elapsed
ok ▂

data->hex #

converts data to hex ( data - result )

Example:

ok "001122334455" hex->data dup . data->hex . 
0000  00 11 22 33 44 55                                 |.."3DU          |
001122334455
ok ▂

data->str #

converts data to string ( data - result )

This conversion stops at a 0-byte in the originating data. The resulting string is 0 terminated.

Example:

ok "f09f9880" hex->data data->str . 
0000  f0 9f 98 80                                       |....            |
ok "f09f9880" hex->data data->str .raw
😀
ok ▂

data? #

returns false or data ( w - result )

Example:

ok "test" str->data data? . 
0000  74 65 73 74                                       |test            |
ok "test" data? .

ok "test" data? not .
#true
ok ▂

datacat #

concatenates data or strings ( [w1] w2 - data )

Example:

ok "" datacat .  
0000                                                    |                |
ok "Hello, " "world." datacat .
0000  48 65 6c 6c 6f 2c 20 77  6f 72 6c 64 2e           |Hello, world.   |
ok "00112233" hex->data "44556677" hex->data datacat .
0000  00 11 22 33 44 55 66 77                           |.."3DUfw        |
ok "00112233" hex->data "**TEST**" datacat .
0000  00 11 22 33 2a 2a 54 45  53 54 2a 2a              |.."3**TEST**    |
ok ▂

datalen #

returns length of data ( data - result )

Example:

ok "This is a test." str->data datalen .
15
ok ▂

delete #

delete variable from dictionary ( name - )

Example:

ok "hello" string !
ok string @ .
hello
ok "string" delete
ok string @ .
Unknown variable string
ERROR detected
ok ▂

dnsbl-expand #

expand IP address data to DNSBL substring ( data - result )

Example:

ok 2001:0DB8::1 str->ipaddr dnsbl-expand .
1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.
ok 127.0.0.2 str->ipaddr dnsbl-expand . 
2.0.0.127.
ok ▂

drop #

drops one element ( s - )

Example:

ok 1 2 3 drop + . 
3
ok .s 
ok ▂

dup #

duplicates top of stack ( s1 - s1 s1 )

Example:

ok 3 dup + . 
6
ok .s 
ok ▂

equal? #

equality predicate ( item1 item2 - result )

Example:

ok "" "" equal? . 
#true
ok "" "" str->data equal? . 

ok 1024 urandom dup equal? . 
#true
ok 1024 urandom 1024 urandom equal? . 

ok "1" " 1" equal? . 

ok "1" " 1" == .
#true
ok "10.1.1.1" str->ip4_t "0a010101" hex->data
ok .s
 1  generic_t    4
 0      ip4_t    4  10.1.1.1
ok equal? .
#true
ok ▂

errno #

returns errno ( - errno)

ok errno . 
0
ok ▂

error #

signal an error ( message - )

ok "this is a message" error 
this is a message
ERROR detected
ok ▂

eval #

evaluate a line ( line - )

Example:

ok "1 2 + . .exec-sp ." eval 
3
2
ok ▂

eval-all #

evaluate a line until current stack frame is empty ( s* line - )

Example:

ok "one" "two" "three" "." eval-all
three
two
one
ok "dup \" : \" strcat swap manuf strcat ." "mymanuf" !!
ok a0:36:9f:21:48:fc a0:36:9f:21:48:fe 80:ee:73:e3:6a:19 "mymanuf" eval-all
80:ee:73:e3:6a:19 : Shuttle Inc.
a0:36:9f:21:48:fe : Intel Corporate
a0:36:9f:21:48:fc : Intel Corporate
ok ▂

eval-all-result #

evaluate a line as long there is more than 1 element ( s* line - result )

Example:

ok "\"&+\" &eval-all-result" "plus-all" !!
ok { 1 2 3 4 5 &plus-all } .
15
ok 4 plus-all .
4
ok { 1 2 3 4 5 6 "+" eval-all-result } .
21
ok plus-all .
Stack underflow
ERROR detected
ok ▂

eval-catch #

evaluate a line, return false at error ( line - result )

Example:

ok "1 2 + 3 ." eval-catch . 
3
#noerror
ok "1 missing @  + 3 ." eval-catch .
Unknown variable "missing"

ok ▂

eval-n #

evaluate a line n times ( line n - )

Example:

ok "uptime-hr . 1 sleep" 5 eval-n 
0d 4h 38m 54s
0d 4h 38m 55s
0d 4h 38m 56s
0d 4h 38m 57s
0d 4h 38m 58s
ok ▂

f2568 #

returns f2568() result ( generic_t - uint64_t )

Example:

ok "" str->data f2568 .
0xdc6cd513e996ae54
ok ▂

f2568resume #

returns f2568resume() result ( generic_t offset uint64_t - uint64_t )

Example:

ok "cd" str->data 2 0x7e7a27a682632a2c hex->uint64_t f2568resume  
0xb3f66d62bcf674a4
ok ▂

f2568test #

show f2568() and f2568resume() test vectors ( - )

Example:

ok f2568test 
f2568("", 0)                                   0xdc6cd513e996ae54
f2568("a", 1)                                  0x733057f5184fd8e8
f2568("ab", 2)                                 0x7e7a27a682632a2c
f2568("abc", 3)                                0x033ba573649a3044
f2568("abcd", 4)                               0xb3f66d62bcf674a4
f2568resume("cd", 2, 2, 0x7e7a27a682632a2c)    0xb3f66d62bcf674a4
f2568("abcde", 5)                              0xa6141edba1c60acd
f2568("abcdef", 6)                             0x430e40daa722a64b
f2568("abcdefg", 7)                            0x3111e6b33be5be6c
f2568("abcdefgh", 8)                           0x302ce90427347152
f2568resume("efgh", 4, 4, 0xb3f66d62bcf674a4)  0x302ce90427347152
ok ▂

fflush #

fflush() stdout and stderr ( - )

Example:

ok fflush 
ok ▂

fgets #

reads a line from stdin ( - result )

Example:

ok fgets .
hello
hello

ok ▂

getcwd #

returns current working directory ( - result )

Example:

ok getcwd . 
/home/test
ok ▂

getenv #

returns getenv() result ( name - value )

Example:

ok LANG getenv . 
en_US.UTF-8
ok ▂

geteuid #

returns the effective user ID ( - euid )

Example:

ok geteuid . 
1000
ok ▂

gethostname #

returns hostname ( - hostname )

Example:

ok gethostname . 
test34
ok ▂

getpid #

returns the process ID (PID) ( - pid )

Example:

ok getpid . 
4338
ok ▂

getuid #

returns the real user ID ( - uid )

Example:

ok getuid . 
1000
ok ▂

hex->data #

converts hex to data ( w - result )

Example:

ok "" hex->data .
0000                                                    |                |
ok "00112233445566778899aabbCCddeefF" hex->data .
0000  00 11 22 33 44 55 66 77  88 99 aa bb cc dd ee ff  |.."3DUfw........|
ok ▂

hex->str #

&hex->data &data->str

Example:

ok "445566" hex->str . 
DUf
ok ▂

if #

evaluate expr if pred returns true ( pred expr - )

Example:

ok "11:22:33:44:55:XX macaddr-str? not" "\"this is not a MAC address\" ." if 
this is not a MAC address
ok ▂

ifelse #

evaluate expr1 if pred returns true, otherwise expr2 ( pred expr1 expr2 - )

Example:

ok "11:22:33:44:55:66" MA ! 
ok "MA @ macaddr-str?" "MA @ ." "\"not a mac address\" error" ifelse
11:22:33:44:55:66
ok 11:22:33:44:55:XX MA !
ok "MA @ macaddr-str?" "MA @ ." "\"not a mac address\" error" ifelse
not a mac address
ERROR detected
ok ▂

ipaddr->str #

convert IP address data to string ( data - s )

Example:

ok 10.1.1.1 str->ipaddr dup . ipaddr->str .
0000  00 00 00 00 00 00 00 00  00 00 ff ff 0a 01 01 01  |................|
10.1.1.1
ok 2001:0DB8::1 str->ipaddr dup . ipaddr->str .
0000  20 01 0d b8 00 00 00 00  00 00 00 00 00 00 00 01  | ...............|
2001:db8::1
ok ▂

ipaddr-check #

raise error if TOS is not an IP address string ( s - s )

Example:

ok 10.1.1.1 ipaddr-check .
10.1.1.1
ok 2001:0DB8::1 ipaddr-check .
2001:0DB8::1
ok "hello" ipaddr-check .
not an IP address "hello" 
ERROR detected
ok ▂

ipaddr-str? #

returns false or the IP address string ( s - result )

Example:

ok 10.1.1.1 ipaddr-str? .
10.1.1.1
ok 2001:0DB8::1 ipaddr-str? .
2001:0DB8::1
ok "hello" ipaddr-str? .

ok ▂

ip4_t->str #

convert ip4_t to str ( data - s )

Example:

ok 10.1.1.1 str->ip4_t dup . 
10.1.1.1
ok ip4_t->str . 
10.1.1.1
ok ▂

isatty #

returns #true if stdin is a TTY ( - result )

Example:

$ rpclsh 
ok isatty .
#true
ok ▂

load #

load a RPCL file ( filename - )

Example:

ok "test.rpcl" load 
ok "missing.rpcl" load
cannot open missing.rpcl - No such file or directory
ERROR detected
ok "test-with-error.rpcl" load
My Error Message
ERROR detected test-with-error.rpcl line 3
ERROR detected
ok ▂

load-if-present #

load a RPCL file if accessible ( filename - )

Example:

ok "test.rpcl" load-if-present
ok "missing.rpcl" load-if-present
ok "test-with-error.rpcl" load-if-present
My Error Message
ERROR detected test-with-error.rpcl line 3
ERROR detected
ok ▂

load-verbose #

load a RPCL file showing progress ( filename - )

Example:

ok "test.rpcl" load-verbose
   1 #
   2
   3 "😀" utf-test !
ok .d
rpcl.platform                    Debian12-amd64
rpcl.version                     1.198
utf-test                         😀
ok ▂

locate #

“curl api.ip2location.io/?ip=” &swap &strcat &system “echo” &system

locate is a predefined compound word useful to determine the location of an IP address. It calls the API available at api.ip2location.io which is limited to 1,000 queries per day without registration. curl needs to be installed on the Linux host.

Example:

ok 10.0.0.1 locate 
{"ip":"10.0.0.1","country_code":null,"country_name":null,"region_name":null,"city_name":null,"latitude":null,"longitude":null,"zip_code":null,"time_zone":null,"asn":null,"as":null,"is_proxy":false,"message":"Limit to 1,000 queries per day. Sign up for a Free plan at https://www.ip2location.io to get 30K queries per month."}
ok 2001:db8::1 locate
{"ip":"2001:db8::1","country_code":null,"country_name":null,"region_name":null,"city_name":null,"latitude":null,"longitude":null,"zip_code":null,"time_zone":null,"asn":null,"as":null,"is_proxy":false,"message":"Limit to 1,000 queries per day. Sign up for a Free plan at https://www.ip2location.io to get 30K queries per month."}
ok ▂

macaddr-check #

raise error if TOS is not a MAC address string ( s - s )

Example:

ok 11:22:33:44:55:66 macaddr-check .
11:22:33:44:55:66
ok "hello" macaddr-check .
not a MAC address "hello"
ERROR detected
ok ▂

macaddr-str? #

returns false or the MAC address string ( s - result )

Example:

ok 11:22:33:44:55:66 macaddr-str? .
11:22:33:44:55:66
ok "hello" macaddr-str? .

ok ▂

machine-id #

return machine-id ( - generic_t )

ok machine-id .s
 0  generic_t   16
ok .
0000  3d ae e5 dc bb 9b a1 8f  1b 18 ca 32 98 ed 67 3b  |=..........2..g;|
ok ▂

manuf #

returns the MAC address manufacturer ( macaddr - manuf )

Example:

ok 24:d7:9c:e4:3e:e9 manuf . 
Cisco Systems, Inc
ok 34:38:AF:46:b7:32 manuf .
Inlab Networks GmbH
ok ▂

not #

logical not ( s - result )

Example:

ok "hello" macaddr? not . 
#true
ok ▂

random-mac_t #

return unbiased random mac_t ( - mac_t )

Example:

ok random-mac_t . 
58:99:d5:3b:ac:7b
ok ▂

random-macstr #

return unbiased random MAC address string ( - result )

This returns an unbiased random MAC address as suggested in RFC4814 - Hash and Stuffing: Overlooked Factors in Network Device Benchmarking for test traffic generation:

The bitwise ANDing of the high-order byte in the MAC address with 0xFC sets the low-order two bits of that byte to 0, guaranteeing a non-multicast address and a non locally administered address. Note that the resulting addresses may violate IEEE 802 standards by using organizationally unique identifiers (OUIs) not assigned to the test port manufacturer. However, since these addresses will be used only on isolated test networks there should be no possibility of mistaken identity.

Example:

ok random-macstr .
94:3e:27:bb:20:cb
ok random-macstr manuf .

ok random-macstr macaddr-check .
28:be:13:f3:0d:85
ok ▂

random-range #

returns random int within a range ( min max - result )

Example:

ok 2 4 random-range . 
3
ok ▂

random-seed #

calls srandom(time(NULL)) ( - )

Example:

ok random-seed 
ok ▂

random16 #

get random uint16_t ( - uint16_t )

Example:

ok random16
ok .s
 0   uint16_t    2  0x591a
ok .x
0000  1a 59                                             |.Y              |
ok ▂

random32 #

get random uint32_t ( - uint32_t )

Example:

ok random32
ok .s
 0   uint32_t    4  0x6a55aaa2
ok .x
0000  a2 aa 55 6a                                       |..Uj            |
ok ▂

random64 #

get random uint64_t ( - uint64_t )

Example:

ok random64
ok .s
 0   uint64_t    8  0x8dbeec7021b5e373
ok .x
0000  73 e3 b5 21 70 ec be 8d                           |s..!p...        |
ok ▂

random8 #

get random uint8_t ( - uint8_t )

Example:

ok random8
ok .s
 0    uint8_t    1  0x3b
ok .x
0000  3b                                                |;               |
ok ▂

setaffinity #

set CPU affinity of RPCL interpreter ( cpu - )

Example:

ok 4 setaffinity 
ok ▂

sha256 #

returns SHA-256 hash ( generic_t - generic_t )

Example:

ok "" str->data sha256 .
0000  e3 b0 c4 42 98 fc 1c 14  9a fb f4 c8 99 6f b9 24  |...B.........o.$|
0010  27 ae 41 e4 64 9b 93 4c  a4 95 99 1b 78 52 b8 55  |'.A.d..L....xR.U|
ok "abc" str->data sha256 .
0000  ba 78 16 bf 8f 01 cf ea  41 41 40 de 5d ae 22 23  |.x......AA@.]."#|
0010  b0 03 61 a3 96 17 7a 9c  b4 10 ff 61 f2 00 15 ad  |..a...z....a....|
ok "abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq" str->data sha256 .
0000  24 8d 6a 61 d2 06 38 b8  e5 c0 26 93 0c 3e 60 39  |$.ja..8...&..>`9|
0010  a3 3c e4 59 64 ff 21 67  f6 ec ed d4 19 db 06 c1  |.<.Yd.!g........|
ok 1024 urandom sha256 .
0000  ad 68 dc ac 41 5f fe a1  4d 5e 3b 9b 53 88 fa 5e  |.h..A_..M^;.S..^|
0010  b7 1c 63 24 cf 2e a0 d6  7f 80 dd ab 11 79 fc 4f  |..c$.........y.O|
ok ▂

sleep #

sleep n seconds ( n - )

Example:

ok "uptime-hr . 1 sleep" 5 eval-n 
0d 4h 38m 54s
0d 4h 38m 55s
0d 4h 38m 56s
0d 4h 38m 57s
0d 4h 38m 58s
ok ▂

split #

split item ( item n - left right )

Example:

ok "1234567890" 5 split 
ok .s
 1     string    5  "67890"
 0     string    5  "12345"
ok strcat .
1234567890
ok "1234567890" str->data 5 split
ok .s
 1  generic_t    5  
 0  generic_t    5  
ok datacat .
0000  31 32 33 34 35 36 37 38  39 30                    |1234567890      |
ok ▂

stop #

EXIT immediately with all threads ( - )

ok stop 
test@u38: ▂

str->data #

convert string to data ( s - data )

When the word is already adata object, it is left untouched.

Example:

ok "Hello" str->data . 
0000  48 65 6c 6c 6f                                    |Hello           |
ok "" str->data .
0000                                                    |                |
ok "" str->data str->data .
0000                                                    |                |
ok ▂

str->hex #

&str->data &data->hex

Example:

ok "445566" hex->str .
DUf
ok "DUf" str->hex .
445566
ok ▂

str->ipaddr #

convert string to IP address data ( s - data )

The successful conversion result is a struct in6_addr data with the size of 16 bytes.

Example:

ok 10.0.0.1 str->ipaddr .
0000  00 00 00 00 00 00 00 00  00 00 ff ff 0a 00 00 01  |................|
ok 2001:0DB8::1 str->ipaddr .
0000  20 01 0d b8 00 00 00 00  00 00 00 00 00 00 00 01  | ...............|
ok "hello" str->ipaddr .
not an IP address "hello"
ERROR detected
ok ▂

str->ip4_t #

convert str to ip4_t ( s - ip4_t )

Example:

ok 10.1.1.1 str->ip4_t .s . 
 0      ip4_t    4  10.1.1.1
10.1.1.1
ok ::ffff:1.2.3.4 str->ip4_t . 
1.2.3.4
ok ::ffff:aaaa:bbbb str->ip4_t . 
170.170.187.187
ok 2001:0DB8::1 str->ip4_t .
not an IPv4 address "2001:0DB8::1"
ERROR detected
ok "hello" str->ip4_t.
not an IPv4 address "hello"
ERROR detected
ok ▂

str->mac_t #

convert str to mac_t ( s - mac_t )

Example:

ok 11:22:33:44:55:66 str->mac_t .s .
 0      mac_t    6  11:22:33:44:55:66
11:22:33:44:55:66
ok random-macstr str->mac_t .
f0:73:56:d9:6f:00
ok "hello" str->mac_t
not a MAC address "hello"
ERROR detected
ok ▂

strcat #

concatenates two strings ( [s1] s2 - result )

strcat may also be called with one single value in the current stack frame (s1 then defaults to "" as the neutral element of string concatenation).

Example:

ok "hello, " "world" strcat .
hello, world
ok "hello" strcat .
hello
ok ▂

strerror #

returns error description ( errnum - description )

Example:

ok errno strerror .
Success
ok 2 strerror .
No such file or directory
ok ▂

strlen #

returns length of string ( s - n )

Example:

ok "hello" strlen .
5
ok "f09f9880" hex->data data->str dup . strlen . 
😀
4
ok "" strlen . 
0
ok ▂

strtoull #

convert hex to uint64_t data ( hex - uint64_t )

ok 0011223344556677 strtoull .
0000  77 66 55 44 33 22 11 00                           |wfUD3"..        |
ok 0011223344556677 hex->data .
0000  00 11 22 33 44 55 66 77                           |.."3DUfw        |
ok ▂

swap #

swap two elements ( s1 s2 - s2 s1)

Example:

ok one two .s 
 0 [one]
 1 [two]
ok swap .s
 0 [two]
 1 [one]
ok ▂

swap-all #

swap all elements ( s* - inverted* )

ok { 1 2 3 "." eval-all } 
3
2
1
ok { 1 2 3 swap-all "." eval-all } 
1
2
3
ok ▂

system #

execute command with system() ( command - )

Calling system with commands, which require stdin/stdout/stderr to be connected to a pseudo terminal may behave strangely when the RPCL interpreter communicates from the background through named pipes.

Example:

ok "uname -r" system
6.1.0-32-amd64
ok "exit 1" system
ERROR detected
ok ▂

timer-push #

return elapsed microseconds ( - us )

Example:

ok timer-start timer-push .
0 
ok timer-start 10 usleep timer-push .
65
ok ▂

timer-show #

show elapsed microseconds ( - )

Example:

ok timer-start timer-show 
0 microseconds elapsed
ok timer-start 1000 .cycleburn timer-show
12 microseconds elapsed
ok ▂

timer-start #

start microsecond timer ( - )

Example:

ok timer-start 1 sleep timer-show 
1000064 microseconds elapsed
ok ▂

uptime #

return interpreter uptime in seconds ( - s )

Example:

ok uptime . 
30237
ok ▂

uptime-hr #

hr stands for “human readable” here.

return uptime as d/h/m/s ( - result )

Example:

ok uptime-hr . 
0d 8h 24m 19s
ok ▂

urandom #

get random data ( length - generic_t )

Example:

ok 128 urandom . 
0000  ea cf d3 fb ec b4 77 9b  2d be b7 11 d3 b3 83 0b  |......w.-.......|
0010  26 cc 1c ee 23 ee c4 3e  90 c7 b6 97 de 12 17 3d  |&...#..>.......=|
0020  66 1e c4 4d 0b cf fc 80  8b 66 fb c0 ab fa 67 d9  |f..M.....f....g.|
0030  38 3d 24 75 b0 b0 e2 38  10 15 42 ac b8 2a cd aa  |8=$u...8..B..*..|
0040  dc 63 f5 d7 7b 9d 9a 2e  31 70 46 6e db f3 23 60  |.c..{...1pFn..#`|
0050  c4 62 b7 17 1b 4b 21 53  78 1c 55 e7 73 e5 cc b1  |.b...K!Sx.U.s...|
0060  b7 51 64 26 9d 59 5c ab  b0 45 29 39 a9 75 92 cc  |.Qd&.Y\..E)9.u..|
0070  fa e2 62 58 0c 30 06 22  49 30 4c a4 d4 83 26 8c  |..bX.0."I0L...&.|
ok ▂

usleep #

sleep n microseconds ( n - )

Example:

ok "uptime-hr . 500 usleep" 5 eval-n 
0d 8h 26m 31s
0d 8h 26m 31s
0d 8h 26m 31s
0d 8h 26m 31s
0d 8h 26m 31s
ok ▂

{ #

push stack frame delimiter ( - SFD )

Example:

ok 1 2 { "test" "." eval-all } + .
test
3
ok ▂

{n} #

return number of elements in current stack frame ( SFD s* - SFD s* n )

ok { 1 2 {n} "." swap eval-n }
2
1
ok ▂

} #

clear current stack frame ( SFD s* - )

} saves top of stack, if there is one and pushes it back.

Example:

ok 1 2 { 3 4 5 + . } + + . 
9
6
ok 1 2 3 4 5 } .
5
ok { { "hello" } } . 
hello
ok { { "one" "two" "three" } } . 
three
ok ▂