Functions and statements available everywhere without load (section 1 of the official LSL
function reference), with notes where the tested 0.10.2 compiler differs. help("NAME")
inside a program and lsl help NAME print the built-in help text for most of them.
Output and input
Function
Description
print arg1, arg2, ...
print arguments separated by a space, end with a newline
printl "text {expr}"
print an interpolated string (expressions in {...} are replaced) and a newline
printr arg1, ...
print values exactly, no separators and no newline (0.9.1+)
l"text {expr}"
first-class interpolated String; can be assigned, returned and passed
input "prompt" / input("prompt")
print the prompt, read one line from stdin, return a String without the trailing LF
readable date and time String YYYY-MM-DD HH:MM:SS UTC (not for arithmetic)
monotonic()
monotonic seconds (Float) for intervals and timeouts
system(command)
alias of os.run(command) without load; command String or argv List, PATH lookup, no shell, returns exit status
Threads and atomics
Function
Description
cpu_count()
number of CPUs in the process affinity mask (respects taskset/cgroups); 1 on error
thread_spawn(function)
inside an unsafe: block, run a zero-argument function in a shared-memory worker thread; returns a thread id or -1 (max 127 workers, 8 MiB stack each)
thread_join(tid)
wait for the worker; returns 0, or 126 for an unknown tid
atomic_add(array, index, delta)
atomically add to an IntArray slot, return the previous value
atomic_xchg(array, index, value)
atomically exchange a slot, return the previous value
atomic_cas(array, index, expected, desired)
compare-and-swap, return the previous value
atomic_pause()
CPU pause hint for spin-wait loops
gc()
request garbage collection now (normally automatic); in a worker returns 0
Threads share memory (Linux clone with CLONE_VM|CLONE_THREAD). The worker's return value
is discarded; an uncaught error in a worker prints LSL worker error: .... Plain writes to
shared collections are not synchronized: use the atomics or a lock block over an IntArray
slot. Workers take work indexes from a global IntArray counter via atomic_add.
counter = IntArray()
counter.append(0)
function bump():
i = 0
while i < 1000:
call atomic_add(counter, 0, 1)
i += 1
end
return None
end
unsafe:
t = thread_spawn(bump)
u = thread_spawn(bump)
end
print thread_join(t), thread_join(u), counter[0] # 0 0 2000
Text files
Function
Description
readfile(path)
read the whole file as a UTF-8 String (bounded reads: fd.read_text_limit)
writefile(path, text)
write text, replacing the file
appendfile(path, text)
append text to the end
exists(path)
True if the path exists
Binary files
Function
Description
readbytes(path)
read the whole file as a ByteArray
writebytes(path, data)
write a ByteArray (an ELF output is made executable)
File system
Function
Description
mkdir(path)
create a directory
cwd()
absolute path of the working directory – Note (0.10.2): not available, compile error "unknown native function"
chdir(path)
change the working directory – Note (0.10.2): not available
remove_path(path)
delete a file or empty directory – Note (0.10.2): not available
In 0.10.2 use the os module instead, e.g. os.run(["rm", "-f", path]),
os.capture("pwd"), or system.remove_file(path) from the system module.
Process and arguments
Function
Description
arg(index)
program argument at a position (0 = program name, 1 = first user argument), or None
arg_count()
number of arguments including the program name
args
global List of all arguments – Note (0.10.2): not available (unknown variable); use arg() and arg_count()
run(program, arguments)
run a program with an argv List, no shell; returns the exit status
Status codes: exit code of the program, 128 + signal when killed by a signal, 126 when fork
or wait failed, 127 when exec failed. In 0.10.2 run/capture need a path to the
executable (capture("/usr/bin/echo", ["hi"])); capture("echo", ...) returned status 127.
Use system() or the os module for PATH lookup.
out = capture("/usr/bin/uname", ["-r"])
if capture_status() == 0:
print "kernel:", out.strip()
end
Errors
Function
Description
last_error()
text of the caught error; None before the first error and after a successful safe/try
length of a String (Unicode characters), list, dictionary or array
help() / help("TOPIC")
print the topic list / help for a command, construct or module; accepts a runtime String, returns None; unknown topic raises HelpError. For a library the output starts with the same short description as lsl about NAME and works for installed user libraries too. Full manual: lsl man
del(x)
delete a variable, collection element or instance member