Lunatik
Lua API · Devices and events

notifierModule

Notifier chain mechanism.

This library allows Lua scripts to register callback functions that are invoked when specific kernel events occur, such as keyboard input, network device status changes, or virtual terminal events. A callback returns a linux.notify code. No value, a callback that raises, which is logged, and an event that reaches a runtime not ready to take it, or that the runtime’s own code raises from under its lock, count as notify.DONE, and so does any other value, which is logged as invalid notify code.

Class notifier

notifier:stop () Stops event delivery to the Lua callback.

notifier

keyboard (callback) Registers a keyboard-event notifier.
netdevice (callback) Registers a network-device notifier.
vt (callback) Registers a virtual-terminal notifier.

Class notifier in detail

Represents a kernel notifier object. This is a userdata object returned by functions like notifier.keyboard(), notifier.netdevice(), or notifier.vt(). It encapsulates a struct notifier_block and the associated Lua callback.
notifier:stop ()
Stops event delivery to the Lua callback. After stop(), the underlying notifier_block remains registered in the kernel chain until the owning runtime is torn down, but firings become silent no-ops. This keeps stop() safe in any context (including hardirq) since it performs no sleeping operations; the real unregistration happens in release, which always runs in process context. A to-be-closed variable holding the notifier stops it the same way.

Returns

    nil

Usage

my_notifier:stop()

notifier in detail

keyboard (callback)
Registers a keyboard-event notifier. Must be called from a hardirq runtime.

Parameters

  • callback function invoked as callback(event, down, shift, value) — event is a linux.kbd code, down is a boolean (key pressed), shift is a boolean (modifier held), and value is the keycode or keysym depending on event. Returns a linux.notify status code.

Returns

    notifier the notifier, which this call keeps for its runtime: dropping it stops nothing, and the callback runs until stop or the end of the runtime

Raises

EOPNOTSUPP on a kernel built without CONFIG_VT; if called from a percpu runtime; runtime context mismatch outside a hardirq runtime; not allowed while the runtime closes from a finalizer that runs at its close; the kernel’s errno when it refuses the registration
netdevice (callback)
Registers a network-device notifier. Must be called from a softirq runtime, lunatik run --context=softirq <script>: the callback runs under RTNL, where nothing it reaches may wait on RTNL, and a softirq runtime takes no call that sleeps once it is armed. The devices of every network namespace are reported, each with the inode number of its namespace: linux.ifindex resolves a name in the initial namespace only, so a script keeps the devices that name resolves by comparing that number with linux.netns().

Parameters

  • callback function invoked as callback(event, name, netns) — event is a linux.netdev.cmd code, name is the device name (e.g. "eth0") and netns the inode number of its network namespace, as linux.netns gives it. The registration itself delivers, inside this call, a REGISTER for each device every namespace already has, and an UP for each of those that is up; a script that means the devices appearing afterwards tells them apart with a flag it clears once this call returns, since no live event reaches the callback before the script body ends. Returns a linux.notify status code. notify.STOP and notify.BAD end the chain, so the kernel’s own blocks after this one never see the event: a callback returns them only for an event whose result the kernel reads to refuse a change, as it reads PRE_UP’s, and never for UNREGISTER, whose device then waits for good on what 8021q and the other blocks after it would have released.

Returns

    notifier the notifier, which this call keeps for its runtime: dropping it stops nothing, and the callback runs until stop or the end of the runtime

Raises

if called from a percpu runtime, or under RTNL: from a netdevice callback, the replay this call delivers included, and from any coroutine the callback runs; runtime context mismatch outside a softirq runtime; not allowed once the runtime is armed past the script body, since the registration sleeps; not allowed while the runtime closes from a finalizer that runs at its close; the kernel’s errno when it refuses the registration, EPERM when the callback returns notify.BAD for a replayed REGISTER
vt (callback)
Registers a virtual-terminal notifier. Must be called from a hardirq runtime.

Parameters

  • callback function invoked as callback(event, c, vc_num) — event is a linux.vt.event code, c is the character value a WRITE or PREWRITE carries and nil for any other event, and vc_num is the virtual console number. Returns a linux.notify status code.

Returns

    notifier the notifier, which this call keeps for its runtime: dropping it stops nothing, and the callback runs until stop or the end of the runtime

Raises

EOPNOTSUPP on a kernel built without CONFIG_VT; if called from a percpu runtime; runtime context mismatch outside a hardirq runtime; not allowed while the runtime closes from a finalizer that runs at its close; the kernel’s errno when it refuses the registration