Lunatik

• Index

Contents

• Class device

Modules

• completion
• data
• device
• fib
• fifo
• linux
• lunatik
• lunatik.runner
• mailbox
• net
• netfilter
• notifier
• probe
• rcu
• socket
• socket.inet
• syscall
• syscall.table
• thread
• xdp
• xtable

Topics

• README

Module device

Low-level Lua interface for creating Linux character device drivers.

This module allows Lua scripts to implement character device drivers by providing callback functions for standard file operations like open, read, write, and release.

Class device

Class device

device:new (driver)

Creates and installs a new character device driver in the system. This function binds a Lua table (the driver table) to a new character device file (/dev/<name>), allowing Lua functions to handle file operations on that device.

Parameters:

• driver table

  A table defining the device driver's properties and callbacks. It must contain the field:

  • name (string): The name of the device. This name will be used to create the device file /dev/<name>.

  It might optionally contain the following fields (callback functions):

  • open (function): Callback for the open(2) system call. Signature: function(driver_table). Expected to return nothing.
  • read (function): Callback for the read(2) system call. Signature: function(driver_table, length, offset) -> string [, updated_offset]. Receives the driver table, the requested read length (integer), and the current file offset (integer). Should return the data as a string and optionally the updated file offset (integer). If updated_offset is not returned, the offset is advanced by the length of the returned string (or the requested length if the string is longer).
  • write (function): Callback for the write(2) system call. Signature: function(driver_table, buffer_string, offset) -> [written_length] [, updated_offset]. Receives the driver table, the data to write as a string, and the current file offset (integer). May return the number of bytes successfully written (integer) and optionally the updated file offset (integer). If written_length is not returned, it's assumed all provided data was written. If updated_offset is not returned, the offset is advanced by the written_length.
  • release (function): Callback for the release(2) system call (called when the last file descriptor is closed). Signature: function(driver_table). Expected to return nothing.
  • mode (integer): Optional file mode flags (e.g., permissions) for the device file. Use constants from the linux.stat table (e.g., linux.stat.IRUGO).

Returns:

userdata A Lunatik object representing the newly created device. This object can be used to explicitly stop the device using the :stop() method.

Raises:

Error if the device cannot be allocated or registered in the kernel, or if the name field is missing or not a string.

See also:

linux.stat

Usage:

local device = require("device")
local linux = require("linux")

local my_driver = {
  name = "my_lua_device",
  mode = linux.stat.IRUGO, -- Read-only for all
  read = function(drv, len, off)
    local data = "Hello from " .. drv.name .. " at offset " .. tostring(off) .. "!"
    return data:sub(1, len), off + #data
  end
}
local dev_obj = device.new(my_driver)
-- To clean up: dev_obj:stop() or let it be garbage collected.

device:stop ()

Stops and releases a character device driver from the system. This method is called on a device object returned by device.new(). Once stopped, the device file (/dev/<name>) will be removed and the associated resources released.

This method provides an explicit way to release the device. The device is also released when close is called (e.g., via Lua 5.4's to-be-closed mechanism if __close is defined and triggered for the object, which typically calls this same underlying function) or eventually when the device object is garbage collected (via __gc). The stop and close methods offer more deterministic cleanup than relying solely on garbage collection.

Returns:

nil Does not return any value to Lua.

Raises:

Error May raise an error if the underlying C function encounters a critical issue during cleanup and calls lua_error.

See also:

device.new

Usage:

-- Assuming 'dev' is a device object:
dev:stop()