Module `syscalls`

This page contains all the system calls available under Cynosure 2.

Wrapper functions with identical functionality are provided by the syscalls library. All system calls return nil and an errno value on failure. System calls are made using coroutine.yield like this: coroutine.yield("syscall", "isatty", 2).

Functions

open (file, mode)	Open a file with the given mode.
request (path)	Request a given network path.
ioctl (fd, operation, ...)	Perform some operation on a file descriptor.
read (fd, fmt)	Read some data from a file descriptor.
write (fd, data)	Write some data to a file descriptor.
seek (fd, whence, number)	Seek to some position in a given file relative to the start position.
flush (fd)	Flush read and write buffers.
opendir (file)	Open a directory.
readdir (fd)	Read from a directory.
close (fd)	Close a file or directory descriptor.
isatty (fd)	Check if a file descriptor refers to a TTY.
dup (fd)	Duplicate a file descriptor.
dup2 (fd, nfd)	Duplicate a file descriptor to the given new one.
mkdir (path, mode)	Create a directory.
stat (path)	Returns some information about a file.
link (source, dest)	Create a hard link.
unlink (path)	Remove a link.
chmod (path, mode)	Change file permissions.
chown (path, uid, gid)	Change a file's owner.
chroot (path)	Change the process's root directory.
mount (node, path)	Mount a filesystem.
fork (func)	Create a new process.
execve (path, args[, env])	Replace the current process.
wait (pid[, nohang[, untraced]])	Wait for a process.
k.syscalls.waitany ([block[, untraced]])	Wait for any child process.
exit (status)	Terminate the current process.
getcwd ()	Get the current working directory.
chdir (path)	Set the current process's working directory.
setuid (uid)	Modify the current process's identity.
seteuid (uid)	Modify the current process's identity.
getuid ()	Get the current process's user ID.
geteuid ()	Get the current process's effective user ID.
setgid (uid)	Modify the current process's identity.
setegid (uid)	Modify the current process's identity.
getgid ()	Get the current process's group ID.
getegid ()	Get the current process's effective group ID.
getpid ()	Get the ID of the current process.
getpid ()	Get the parent PID of the current process.
setsid ()	Set the session ID of the current process.
getsid ([pid])	Get the session ID of a process.
setpgrp (pid, pg)	Set a process's process group.
getpgrp ([pid])	Get the process group of a process.
sigaction (name[, function])	Set a handler for some POSIX signal.
kill (pid, name)	Signal a process.
gethostname ()	Get the system hostname.
sethostname (name)	Set the system hostname.
environ ()	Get the process environment.
umask (num)	Set the umask.
pipe ()	Create a pipe.
reboot (cmd)	Restart the system.
uname ()	Return some system information.
uptime ()	Return the system uptime.
klogctl (action, second[, format])	Perform some action on the system log.

Tables

dirent	Returned by readdir.
statx	The information returned by stat.
unameinfo	Table containing system information.

Functions

open (file, mode)

Open a file with the given mode. Returns a file descriptor.

Parameters:

file string The file to open
mode string The mode, similar to those given to io

Returns:

number

request (path)

Request a given network path. Uses any protocol supported by the kernel. Returns a file descriptor. Paths must be standard URLs, i.e. https://example.com/404.html or mtel://upm/packages/list

Parameters:

path string The path to request

Returns:

number

ioctl (fd, operation, ...)

Perform some operation on a file descriptor. Not all file descriptors support all ioctls.

Parameters:

fd number The file descriptor
operation string The operation to perform
... any Any remaining arguments

read (fd, fmt)

Read some data from a file descriptor. Returns the data that was read. Any format valid for io is valid when passed to this function.

Parameters:

fd number The file descriptor
fmt string or number The format to use when reading

Returns:

string

write (fd, data)

Write some data to a file descriptor.

Parameters:

fd number The file descriptor
data string The data to write

Returns:

boolean

seek (fd, whence, number)

Seek to some position in a given file relative to the start position. Returns the new position. Not all file descriptors support this.

Parameters:

fd number The file descriptor
whence string Where to start
number offset |nil The offset to seek

Returns:

number

flush (fd)

Flush read and write buffers. Only does something on some file descriptors, and then only if the file descriptor is buffered.

Parameters:

fd number The file descriptor

opendir (file)

Open a directory. Opens the given directory for reading and returns a directory descriptor.

Parameters:

file string The directory to open

Returns:

number

readdir (fd)

Read from a directory.

Parameters:

fd number The directory descriptor

Returns:

table

dirent

close (fd)

Close a file or directory descriptor.

Parameters:

fd number The file descriptor

isatty (fd)

Check if a file descriptor refers to a TTY.

Parameters:

fd number The file descriptor

Returns:

boolean

dup (fd)

Duplicate a file descriptor. Returns the new file descriptor.

Parameters:

fd number The descriptor to duplicate

Returns:

number

dup2 (fd, nfd)

Duplicate a file descriptor to the given new one. Returns the new file descriptor. If the provided new file descriptor exists and is open, it will be silently closed.

Parameters:

fd number The file descriptor to duplicate
nfd number The new file descriptor

Returns:

number

mkdir (path, mode)

Create a directory.

Parameters:

path string The directory to create
mode number The permissions to set on it

stat (path)

Returns some information about a file.

Parameters:

path string The file to query

Returns:

The information

link (source, dest)

Create a hard link. Not supported by any filesystems at this time.

Parameters:

source string The source file
dest string The location of the new link

unlink (path)

Remove a link. Removes the file when its link count reaches 0.

Parameters:

path string The file to unlink

chmod (path, mode)

Change file permissions. Takes a standard POSIX file mode and applies the permissions to the given file.

Parameters:

path string The file to modify
mode number The mode to set

chown (path, uid, gid)

Change a file's owner. Changes the uid and gid fields for the given file.

Parameters:

path string The file to modify
uid number The new owning UID
gid number The new owning GID

chroot (path)

Change the process's root directory. This behaves very similarly to chroot(2). Only root may do this.

Parameters:

path string The new root path.

mount (node, path)

Mount a filesystem. The given directory must exist or the operation will fail.

Parameters:

node table or string The filesystem node
path string The path at which to mount it

fork (func)

Create a new process. This function creates a new process from the given function. Its behavior is nonstandard due to Lua limitations.

Parameters:

func function The function to use

Returns:

number

execve (path, args[, env])

Replace the current process. Takes the path to an executable file and loads it as a replacement for the current process.

Parameters:

path string The executable to load
args table Any arguments to pass
env table Environment variables, if any (optional)

wait (pid[, nohang[, untraced]])

Wait for a process. If a process has exited, it will not be removed until wait is called on it.

Parameters:

pid number The process ID for which to wait
nohang boolean Whether to block while waiting (optional)
untraced boolean Whether to report stopped children (optional)

Returns:

string The exit reason
number The exit status

k.syscalls.waitany ([block[, untraced]])

Wait for any child process. Optionally blocks. Otherwise returns immediately if there are no child processes that have not been waited for.

Parameters:

block boolean Whether to block indefinitely while waiting (optional)
untraced boolean Whether to report stopped children (optional)

Returns:

number The PID of the process that was waited for
string The exit reason
number The exit status

exit (status)

Terminate the current process. Takes an exit status, which is returned to the parent from a call to wait.

Parameters:

status number The exit status to use

getcwd ()

Get the current working directory.

Returns:

string

chdir (path)

Set the current process's working directory. Does nothing if the given path does not exist. The given path may be relative.

Parameters:

path string The new working directory

setuid (uid)

Modify the current process's identity.

Parameters:

uid number The new user ID

Parameters:

uid number The new user ID

Returns:

number

geteuid ()

Get the current process's effective user ID.

Returns:

number

setgid (uid)

Modify the current process's identity.

Parameters:

uid number The new group ID

Parameters:

uid number The new group ID

Returns:

number

getegid ()

Get the current process's effective group ID.

Returns:

number

getpid ()

Get the ID of the current process.

Returns:

number

getpid ()

Get the parent PID of the current process.

Returns:

number

setsid ()

Set the session ID of the current process. Does not work if the current process is the leader of its process group.

Returns:

number

getsid ([pid])

Get the session ID of a process.

Parameters:

pid number The process to query (optional)

Returns:

number

setpgrp (pid, pg)

Set a process's process group. A PID of 0 will affect the current process. A process group ID of 0 will use the current process's ID.

Parameters:

pid number The process to modify
pg number The process group ID

getpgrp ([pid])

Get the process group of a process.

Parameters:

pid number The process ID to query (optional)

Returns:

number

sigaction (name[, function])

Set a handler for some POSIX signal. Signals are represented by their constant names rather than by numbers. If handler is not provided the signal handler will be reset.

Parameters:

name string The signal name
function handler The handler function to set (optional)

kill (pid, name)

Signal a process. Differs from the standard slightly: SIGEXIST, rather than 0, is used to check if a process exists - since signals don't have numeric IDs under Cynosure 2. If pid is positive, the given signal is sent to that process. If pid is 0, the signal is sent to every process in the process group of the current process. If pid is -1, the signal is sent to every process the calling process has permission to signal. If pid is negative, the signal is sent to every process in the process group whose id is abs(pid).

Parameters:

pid number What to kill
name string The signal to send

gethostname ()

Get the system hostname.

Returns:

string

sethostname (name)

Set the system hostname.

Parameters:

name string The new hostname

environ ()

Get the process environment. Returns the current process's environment table.

Returns:

table

umask (num)

Set the umask. Only uses the permissions bits. Returns the previous umask.

Parameters:

num number The new umask

Returns:

number

pipe ()

Create a pipe. Returns a pair of file descriptors.

Returns:

number The read end
number The write end

reboot (cmd)

Restart the system. Does not function unless the effective user ID is 0 (root). The given action must be one of: halt, poweroff, reboot

Parameters:

cmd string The action to perform

uname ()

Return some system information.

Returns:

The system information

uptime ()

Return the system uptime.

Returns:

number

klogctl (action, second[, format])

Perform some action on the system log. All actions except read_all and log require root. Valid actions are:

read: Wait until there are messages in the kernel log buffer, then read up to second of them and clear the read ones.
read_all: Read all messages currently in the log buffer.
read_clear: Read and clear all messages currently in the log buffer.
clear: Clear all messages currently in the log buffer.
console_off: Saves the current loglevel, then sets the loglevel to 1.
console_on: Either restores the saved loglevel, or sets the loglevel to 7.
console_level: Sets the console loglevel to anywhere between 1 and 8, inclusive. second will be silently constrained to this range.
log: Write a message to the system log using second as the loglevel and format + any remaining arguments as arguments to printk

Parameters:

action string What to do
second string or number The second argument
format string Format to use for log (optional)

Returns:

table

Or

boolean

Tables

dirent

Returned by readdir.

Fields:

inode number The inode on which the file is stored
name string The name of the file

statx

The information returned by stat.

Fields:

ino number The inode on which the file is located
mode number The POSIX file mode (type and permissions)
nlink number How many times the file's inode is referenced (hard linked)
uid number The user ID of the file's owner
gid number The group ID of the file's owner
size number The file size in bytes
blksize number The block size used for file I/O
atime number File access time
ctime number File creation time
mtime number File modification time

unameinfo

Table containing system information.

Fields:

sysname string The system name
nodename string The nodename (hostname)
release string The kernel release
version string The day this kernel was built
machine string The machine the kernel is running on

ULOS 2

Contents

Libraries

Examples

Module syscalls

Functions

Tables

Functions

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

See also:

Parameters:

See also:

Returns:

Returns:

Parameters:

See also:

Parameters:

See also:

Returns:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Module `syscalls`