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.

! #

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 element ( s - )

Example:

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

.cs #

clear stack ( - )

Example:

ok 1 2 3 
ok .s
 0 [1]
 1 [2]
 2 [3]
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
• Variables that represent compound words appear in green

Example:

ok 1 testvar ! 
ok "3 +" addthree !! 
ok .d
addthree                         3 +
version.rpcl                     1.58
testvar                          1
ok ▂ 

.exec-sp #

returns the execution stack pointer ( - execsp )

Example:

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

.f82 #

returns f82() result in hex ( u64x - result )

Example:

ok aaaa .f82 .
6BE6
ok ▂ 

.f82-4 #

returns XOR of 4 f82() results in hex ( h0 h1 h2 h3 - result )

ok aaaa aabb bbaa bbbb .f82-4 . 
0
ok ▂ 

.fflush #

fflush() stdout and stderr ( - )

Example:

ok .fflush 
ok ▂ 

.i #

prints built-in functions ( - )

• RPCL predefined / native built-in functions are shown in black
• Functions registered lateron by other components appear in blue

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 ▂ 

.i+ #

prints extended built-in functions only ( - )

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 .i+
ok ▂ 

Example with extended words from an RPCL controlled IXDP application:

ok .i+
drop.hash.insert                 add specific MAC address to drop ( mac - )
drop.hash.reset                  reset drop machash to 0 elements ( - )
drop.hash.show                   show user defined drop machash ( - )
fault.disable                    disable fault injection for interface ( interface - )
fault.enable                     enable fault injection for interface ( interface - )
fault.hash.dst.insert            add specific MAC address to fault injection DST machash ( mac - )
fault.hash.dst.reset             reset fault injection DST machash to 0 elements ( - )
fault.hash.dst.show              show fault injection DST machash ( - )
fault.hash.src.insert            add specific MAC address to fault injection SRC machash ( mac - )
fault.hash.src.reset             reset fault injection SRC machash to 0 elements ( - )
fault.hash.src.show              show fault injection SRC machash ( - )
if.drivers                       show interfaces and drivers ( - )
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 ( - )
tap.hash.insert                  add specific MAC address to TAP ( mac - )
tap.hash.reset                   reset TAP machash to 0 elements ( - )
tap.hash.show                    show TAP machash ( - )
tap.rx.disable                   disable RX TAP for interface ( interface - )
tap.rx.enable                    enable RX TAP for interface ( interface - )
tap.status                       show TAP packet queue status ( - )
tap.tx.disable                   disable TX TAP for interface ( interface - )
tap.tx.enable                    enable TX TAP for interface ( interface - )
ok ▂ 

.m #

prints internal memory allocations ( - )

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 ▂ 

.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)) ( - )

ok .random-seed 
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 ▂ 

@ #

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 ▂ 

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 ▂ 

delete #

delete variable from dictionary ( name - )

Example:

ok "hello" string !
ok string @ .
hello
ok "string" delete
ok string @ .
Unknown variable string
ERROR detected
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 ▂ 

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-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 ▂ 

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 plus-all .
Stack underflow
ERROR detected
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 ▂ 

if #

evaluate expr if pred returns true ( pred expr - )

Example:

ok "11:22:33:44:55:XX macaddr? 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?" "MA @ ." "\"not a mac address\" error" ifelse
11:22:33:44:55:66
ok 11:22:33:44:55:XX MA !
ok "MA @ macaddr?" "MA @ ." "\"not a mac address\" error" ifelse
not a mac address
ERROR detected
ok ▂ 

ipaddr-check #

raise error if TOS is not an IP address ( 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? #

returns false or the IP address ( s - result )

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

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 ▂ 

macaddr-check #

raise error if TOS is not a MAC address ( 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-random #

return unbiased random MAC address ( - 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 macaddr-random .
94:3e:27:bb:20:cb
ok macaddr-random manuf .

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

macaddr? #

returns false or the MAC address ( s - result )

Example:

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

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 ▂ 

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 ▂ 

stop #

EXIT immediately with all threads ( - )

ok stop 
test@u38: ▂ 

strcat #

concatenates two strings ( s1 s2 - result )

Example:

ok "hello, " "world" strcat .
hello, world
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 "😀" strlen . 
4
ok "" strlen . 
0
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 ▂ 

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 ▂ 

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 ▂