Module linux

Various Linux kernel facilities.

This library includes functions for random number generation, task scheduling, time retrieval, kernel symbol lookup, network interface information, byte order conversion, and access to kernel constants like file modes, task states, and error numbers.

Functions

difftime (t2, t1) Calculates the difference between two timestamps.
ifindex (interface_name) Gets the interface index for a network device name.
kill (pid[, sig]) Kills a process by sending a signal.
lookup (symbol_name) Looks up a kernel symbol by name.
random ([m[, n]]) Generates pseudo-random integers.
schedule ([timeout[, state]]) Puts the current task to sleep.
time () Gets the current real time.
tracing ([enable]) Controls kernel tracing.

Tables

errno Table of error number constants.
signal Table of signal constants for use with linux.kill.
stat Table of file mode constants.
task Table of task state constants.

Byte Order Conversion

be16toh (num) Converts a 16-bit integer from big-endian byte order to host byte order.
be32toh (num) Converts a 32-bit integer from big-endian byte order to host byte order.
be64toh (num) Converts a 64-bit integer from big-endian byte order to host byte order.
htobe16 (num) Converts a 16-bit integer from host byte order to big-endian byte order.
htobe32 (num) Converts a 32-bit integer from host byte order to big-endian byte order.
htobe64 (num) Converts a 64-bit integer from host byte order to big-endian byte order.
htole16 (num) Converts a 16-bit integer from host byte order to little-endian byte order.
htole32 (num) Converts a 32-bit integer from host byte order to little-endian byte order.
htole64 (num) Converts a 64-bit integer from host byte order to little-endian byte order.
hton16 (num) Converts a 16-bit integer from host byte order to network (big-endian) byte order.
hton32 (num) Converts a 32-bit integer from host byte order to network (big-endian) byte order.
hton64 (num) Converts a 64-bit integer from host byte order to network (big-endian) byte order.
le16toh (num) Converts a 16-bit integer from little-endian byte order to host byte order.
le32toh (num) Converts a 32-bit integer from little-endian byte order to host byte order.
le64toh (num) Converts a 64-bit integer from little-endian byte order to host byte order.
ntoh16 (num) Converts a 16-bit integer from network (big-endian) byte order to host byte order.
ntoh32 (num) Converts a 32-bit integer from network (big-endian) byte order to host byte order.
ntoh64 (num) Converts a 64-bit integer from network (big-endian) byte order to host byte order.


Functions

difftime (t2, t1)
Calculates the difference between two timestamps.

Parameters:

  • t2 integer The later timestamp (e.g., from linux.time()).
  • t1 integer The earlier timestamp (e.g., from linux.time()).

Returns:

    integer The difference t2 - t1 in nanoseconds.
ifindex (interface_name)
Gets the interface index for a network device name.

Parameters:

  • interface_name string The name of the network interface (e.g., "eth0").

Returns:

    integer The interface index.

Raises:

Error if the device is not found.

Usage:

    local index = linux.ifindex("lo")
print("Index of lo:", index)
kill (pid[, sig])
Kills a process by sending a signal. By default, sends SIGKILL. An optional second argument can specify a different signal (either by number or by using the constants from linux.signal).

Parameters:

  • pid integer Process ID to kill.
  • sig integer Signal number to send (default: linux.signal.KILL). (optional)

Returns:

  1. boolean true if the signal was sent successfully.
  2. boolean false followed by an error number if the operation fails.

Raises:

Errors: - (3): The specified PID doesn't exist - other errno values depending on the failure cause (e.g., EPERM, EINVAL, etc.)

Usage:

    linux.kill(1234)  -- Kill process 1234 with SIGKILL (default)
linux.kill(1234, linux.signal.TERM)  -- Kill process 1234 with SIGTERM
lookup (symbol_name)
Looks up a kernel symbol by name. Uses kallsyms_lookup_name (potentially via kprobes) to find the address of a kernel symbol.

Parameters:

  • symbol_name string The name of the kernel symbol to look up.

Returns:

    lightuserdata The address of the symbol if found, otherwise nil (represented as a NULL lightuserdata).

Usage:

    local addr = linux.lookup("jiffies")
if addr then print("Address of jiffies:", addr) end
random ([m[, n]])
Generates pseudo-random integers. Mimics the behavior of Lua's math.random but uses kernel's random number generation facilities (get_random_u32 or get_random_u64).

Parameters:

  • m integer Lower bound of the range. If only one argument n is provided, m defaults to 1. (optional)
  • n integer Upper bound of the range. (optional)

Returns:

    integer A pseudo-random integer. - If called without arguments, returns an integer with all bits pseudo-random. - If called with one integer n, returns a pseudo-random integer in the range [1, n]. - If called with two integers m and n, returns a pseudo-random integer in the range [m, n].

Raises:

Error if m > n or if the interval is too large.

Usage:

    local r1 = linux.random()       -- Full range random integer
local r2 = linux.random(100)    -- Random integer between 1 and 100
local r3 = linux.random(50, 60) -- Random integer between 50 and 60
schedule ([timeout[, state]])
Puts the current task to sleep. Sets the current task's state and schedules it out until a timeout occurs or it is woken up.

Parameters:

  • timeout integer Duration in milliseconds to sleep. Defaults to MAX_SCHEDULE_TIMEOUT (effectively indefinite sleep until woken). (optional)
  • state integer The task state to set before sleeping. See linux.task for possible values. Defaults to linux.task.INTERRUPTIBLE. (optional)

Returns:

    integer The remaining time in milliseconds if the sleep was interrupted before the full timeout, or 0 if the full timeout elapsed.

Raises:

Error if an invalid task state is provided.

See also:

Usage:

    linux.schedule(1000) -- Sleep for 1 second (interruptible)
linux.schedule(500, linux.task.UNINTERRUPTIBLE) -- Sleep for 0.5 seconds (uninterruptible)
time ()
Gets the current real time.

Returns:

    integer The current time in nanoseconds since the epoch (from ktime_get_real_ns).
tracing ([enable])
Controls kernel tracing. Turns kernel tracing on or off via tracing_on() and tracing_off().

Parameters:

  • enable boolean If true, turns tracing on. If false, turns tracing off. If omitted, does not change the state. (optional)

Returns:

    boolean The current state of kernel tracing (true if on, false if off) after any change.

Usage:

    local was_tracing = linux.tracing(true) -- Enable tracing
if was_tracing then print("Tracing is now on") end
local current_state = linux.tracing()   -- Get current state
linux.tracing(false)                    -- Disable tracing

Tables

errno
Table of error number constants. Exports common errno values from <uapi/asm-generic/errno-base.h>.
signal
Table of signal constants for use with linux.kill. This table provides named constants for the standard Linux signals. For example, linux.signal.TERM corresponds to SIGTERM (15).

Fields:

  • HUP integer SIGHUP (1) - Hangup
  • INT integer SIGINT (2) - Interrupt (Ctrl-C)
  • QUIT integer SIGQUIT (3) - Quit
  • ILL integer SIGILL (4) - Illegal instruction
  • TRAP integer SIGTRAP (5) - Trace trap
  • ABRT integer SIGABRT (6) - Abort
  • BUS integer SIGBUS (7) - Bus error
  • FPE integer SIGFPE (8) - Floating point exception
  • KILL integer SIGKILL (9) - Kill (cannot be caught/ignored)
  • USR1 integer SIGUSR1 (10) - User-defined signal 1
  • SEGV integer SIGSEGV (11) - Segmentation violation
  • USR2 integer SIGUSR2 (12) - User-defined signal 2
  • PIPE integer SIGPIPE (13) - Broken pipe
  • ALRM integer SIGALRM (14) - Alarm clock
  • TERM integer SIGTERM (15) - Termination (default for kill command)
  • STKFLT integer SIGSTKFLT (16) - Stack fault
  • CHLD integer SIGCHLD (17) - Child status changed
  • CONT integer SIGCONT (18) - Continue if stopped
  • STOP integer SIGSTOP (19) - Stop (cannot be caught/ignored)
  • TSTP integer SIGTSTP (20) - Terminal stop
  • TTIN integer SIGTTIN (21) - Background read from tty
  • TTOU integer SIGTTOU (22) - Background write to tty
  • URG integer SIGURG (23) - Urgent condition on socket
  • XCPU integer SIGXCPU (24) - CPU limit exceeded
  • XFSZ integer SIGXFSZ (25) - File size limit exceeded
  • VTALRM integer SIGVTALRM (26) - Virtual alarm clock
  • PROF integer SIGPROF (27) - Profiling alarm clock
  • WINCH integer SIGWINCH (28) - Window size change
  • IO integer SIGIO (29) - I/O now possible
  • PWR integer SIGPWR (30) - Power failure
  • SYS integer SIGSYS (31) - Bad system call
stat
Table of file mode constants. Exports file permission flags from <linux/stat.h>. These can be used, for example, with device.new() to set the mode of a character device.

Fields:

  • IRWXU integer Read, write, execute for owner. (S_IRWXU)
  • IRUSR integer Read for owner. (S_IRUSR)
  • IWUSR integer Write for owner. (S_IWUSR)
  • IXUSR integer Execute for owner. (S_IXUSR)
  • IRWXG integer Read, write, execute for group. (S_IRWXG)
  • IRGRP integer Read for group. (S_IRGRP)
  • IWGRP integer Write for group. (S_IWGRP)
  • IXGRP integer Execute for group. (S_IXGRP)
  • IRWXO integer Read, write, execute for others. (S_IRWXO)
  • IROTH integer Read for others. (S_IROTH)
  • IWOTH integer Write for others. (S_IWOTH)
  • IXOTH integer Execute for others. (S_IXOTH)
  • IRWXUGO integer Read, write, execute for user, group, and others. (SIRWXU|SIRWXG|S_IRWXO)
  • IALLUGO integer All permissions for user, group, and others, including SUID, SGID, SVTX. (SISUID|SISGID|SISVTX|SIRWXUGO)
  • IRUGO integer Read for user, group, and others. (SIRUSR|SIRGRP|S_IROTH)
  • IWUGO integer Write for user, group, and others. (SIWUSR|SIWGRP|S_IWOTH)
  • IXUGO integer Execute for user, group, and others. (SIXUSR|SIXGRP|S_IXOTH)

See also:

task
Table of task state constants. Exports task state flags from <linux/sched.h>. These are used with linux.schedule().

Fields:

  • INTERRUPTIBLE integer Task is waiting for a signal or a resource (sleeping), can be interrupted.
  • UNINTERRUPTIBLE integer Task is waiting (sleeping), cannot be interrupted by signals (except fatal ones if KILLABLE is also implied by context).
  • KILLABLE integer Task is waiting (sleeping) like UNINTERRUPTIBLE, but can be interrupted by fatal signals.
  • IDLE integer Task is idle, similar to UNINTERRUPTIBLE but avoids loadavg accounting.

See also:

Byte Order Conversion

be16toh (num)
Converts a 16-bit integer from big-endian byte order to host byte order.

Parameters:

  • num integer The 16-bit integer in big-endian byte order.

Returns:

    integer The integer in host byte order.
be32toh (num)
Converts a 32-bit integer from big-endian byte order to host byte order.

Parameters:

  • num integer The 32-bit integer in big-endian byte order.

Returns:

    integer The integer in host byte order.
be64toh (num)
Converts a 64-bit integer from big-endian byte order to host byte order.

Parameters:

  • num integer The 64-bit integer in big-endian byte order.

Returns:

    integer The integer in host byte order.
htobe16 (num)
Converts a 16-bit integer from host byte order to big-endian byte order.

Parameters:

  • num integer The 16-bit integer in host byte order.

Returns:

    integer The integer in big-endian byte order.
htobe32 (num)
Converts a 32-bit integer from host byte order to big-endian byte order.

Parameters:

  • num integer The 32-bit integer in host byte order.

Returns:

    integer The integer in big-endian byte order.
htobe64 (num)
Converts a 64-bit integer from host byte order to big-endian byte order.

Parameters:

  • num integer The 64-bit integer in host byte order.

Returns:

    integer The integer in big-endian byte order.
htole16 (num)
Converts a 16-bit integer from host byte order to little-endian byte order.

Parameters:

  • num integer The 16-bit integer in host byte order.

Returns:

    integer The integer in little-endian byte order.
htole32 (num)
Converts a 32-bit integer from host byte order to little-endian byte order.

Parameters:

  • num integer The 32-bit integer in host byte order.

Returns:

    integer The integer in little-endian byte order.
htole64 (num)
Converts a 64-bit integer from host byte order to little-endian byte order.

Parameters:

  • num integer The 64-bit integer in host byte order.

Returns:

    integer The integer in little-endian byte order.
hton16 (num)
Converts a 16-bit integer from host byte order to network (big-endian) byte order.

Parameters:

  • num integer The 16-bit integer in host byte order.

Returns:

    integer The integer in network byte order.
hton32 (num)
Converts a 32-bit integer from host byte order to network (big-endian) byte order.

Parameters:

  • num integer The 32-bit integer in host byte order.

Returns:

    integer The integer in network byte order.
hton64 (num)
Converts a 64-bit integer from host byte order to network (big-endian) byte order.

Parameters:

  • num integer The 64-bit integer in host byte order.

Returns:

    integer The integer in network byte order.
le16toh (num)
Converts a 16-bit integer from little-endian byte order to host byte order.

Parameters:

  • num integer The 16-bit integer in little-endian byte order.

Returns:

    integer The integer in host byte order.
le32toh (num)
Converts a 32-bit integer from little-endian byte order to host byte order.

Parameters:

  • num integer The 32-bit integer in little-endian byte order.

Returns:

    integer The integer in host byte order.
le64toh (num)
Converts a 64-bit integer from little-endian byte order to host byte order.

Parameters:

  • num integer The 64-bit integer in little-endian byte order.

Returns:

    integer The integer in host byte order.
ntoh16 (num)
Converts a 16-bit integer from network (big-endian) byte order to host byte order.

Parameters:

  • num integer The 16-bit integer in network byte order.

Returns:

    integer The integer in host byte order.
ntoh32 (num)
Converts a 32-bit integer from network (big-endian) byte order to host byte order.

Parameters:

  • num integer The 32-bit integer in network byte order.

Returns:

    integer The integer in host byte order.
ntoh64 (num)
Converts a 64-bit integer from network (big-endian) byte order to host byte order.

Parameters:

  • num integer The 64-bit integer in network byte order.

Returns:

    integer The integer in host byte order.
generated by LDoc 1.5.0 Last updated 2025-08-04 15:54:20