From 3535f754ab82a0193d5a03a5a6df5f500d74a966 Mon Sep 17 00:00:00 2001
From: Lourival Vieira Neto <lourival.neto@ring-0.io>
Date: Tue, 4 Apr 2023 22:40:23 +0000
Subject: [PATCH] add README.md

* few adjustments to improve the documentation
* update lua/ submodule
---
 README.md       | 390 ++++++++++++++++++++++++++++++++++++++++++++++++
 lib/luadevice.c |  12 +-
 lib/lualinux.c  |  39 +++++
 lua             |   2 +-
 lunatik.h       |   4 +-
 lunatik_core.c  |  18 +--
 sbin/lunatik    |  17 ++-
 7 files changed, 453 insertions(+), 29 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..c15917df
--- /dev/null
+++ b/README.md
@@ -0,0 +1,390 @@
+# Lunatik
+
+Lunatik is a framework for scripting the Linux kernel with [Lua](https://www.lua.org/).
+It is composed by the Lua interpreter modified to run in the kernel;
+a [device driver](lunatik.lua) (written in Lua =)) and a [command line tool](sbin/lunatik)
+to load and run scripts and manage runtime environments from the user space;
+a [C API](#lunatik-c-api) to load and run scripts and manage runtime environments from the kernel;
+and [Lua APIs](#lunatik-lua-apis) for binding kernel facilities to Lua scripts. 
+Lunatik also offers a [shell script](sbin/lunatik.sh) as a helper for managing its kernel modules.
+
+Here is an example of a character device driver written in Lua using Lunatik
+to generate random ASCII printable characters:
+```Lua
+-- /lib/modules/lua/passwd.lua
+--
+-- implements /dev/passwd for generate passwords
+-- usage: $ sudo sbin/lunatik --run passwd
+--        $ head -c <width> /dev/passwd
+
+local device = require("device")
+local linux  = require("linux")
+
+local function nop() end -- do nothing
+
+local s = linux.stat
+local driver = {name = "passwd", open = nop, release = nop, mode = s.IRUGO}
+
+function driver:read() -- read(2) callback
+	-- generate random ASCII printable characters
+	return string.char(linux.random(32, 126))
+end
+
+-- creates a new character device
+device.new(driver)
+```
+
+## Usage
+
+```
+make
+sudo sbin/lunatik.sh install # copy lunatik.lua to /lib/modules/lua
+sudo sbin/lunatik.sh start   # load Lunatik kernel modules
+sudo sbin/lunatik.sh run     # execute sbin/lunatik REPL
+Lunatik 3.0  Copyright (C) 2023 ring-0 Ltda.
+> return 42 -- execute this line in the kernel
+42
+```
+
+### sbin/lunatik
+
+```Shell
+usage: sbin/lunatik [[--run] <script>] [--stop <script>]
+```
+
+* `--run`: create a new runtime environment to run the script `/lib/modules/lua/<script>.lua`
+* `--stop`: stop the runtime environment created to run the script `<script>`
+* `default`: start a _REPL (Read–Eval–Print Loop)_
+
+### sbin/lunatik.sh
+
+```
+usage: sbin/lunatik.sh {start|stop|restart|status|install|run}
+```
+
+* `start`: load Lunatik kernel modules
+* `stop`: remove Lunatik kernel modules
+* `restart`: reload Lunatik kernel modules
+* `status`: show what Lunatik kernel modules are currently loaded
+* `install`: copy `lunatik.lua` device driver to `/lib/modules/lua`
+* `run`: execute `sbin/lunatik` REPL
+
+## Lua Version
+
+Lunatik 3.0 is based on
+[Lua 5.4 adapted](https://github.com/luainkernel/lua)
+to run in the kernel.
+
+### Floating-point numbers
+
+Lunatik **does not** support floating-point arithmetic,
+thus it **does not** support `__div` nor `__pow`
+[metamethods](https://www.lua.org/manual/5.4/manual.html#2.4)
+and the type _number_ has only the subtype _integer_.
+
+### Lua API
+
+Lunatik **does not** support both [io](https://www.lua.org/manual/5.4/manual.html#6.8) and
+[os](https://www.lua.org/manual/5.4/manual.html#6.9) libraries,
+and the given identifiers from the following libraries:
+* [debug.debug](https://www.lua.org/manual/5.4/manual.html#pdf-debug.debug),
+[math.acos](https://www.lua.org/manual/5.4/manual.html#pdf-math.acos),
+[math.asin](https://www.lua.org/manual/5.4/manual.html#pdf-math.asin),
+[math.atan](https://www.lua.org/manual/5.4/manual.html#pdf-math.atan),
+[math.ceil](https://www.lua.org/manual/5.4/manual.html#pdf-math.ceil),
+[math.cos](https://www.lua.org/manual/5.4/manual.html#pdf-math.cos),
+[math.deg](https://www.lua.org/manual/5.4/manual.html#pdf-math.deg),
+[math.exp](https://www.lua.org/manual/5.4/manual.html#pdf-math.exp),
+[math.floor](https://www.lua.org/manual/5.4/manual.html#pdf-math.floor),
+[math.fmod](https://www.lua.org/manual/5.4/manual.html#pdf-math.fmod),
+[math.huge](https://www.lua.org/manual/5.4/manual.html#pdf-math.huge).
+[math.log](https://www.lua.org/manual/5.4/manual.html#pdf-math.log),
+[math.modf](https://www.lua.org/manual/5.4/manual.html#pdf-math.modf),
+[math.pi](https://www.lua.org/manual/5.4/manual.html#pdf-math.pi),
+[math.rad](https://www.lua.org/manual/5.4/manual.html#pdf-math.rad),
+[math.random](https://www.lua.org/manual/5.4/manual.html#pdf-math.random),
+[math.randomseed](https://www.lua.org/manual/5.4/manual.html#pdf-math.randomseed),
+[math.sin](https://www.lua.org/manual/5.4/manual.html#pdf-math.sin),
+[math.sqrt](https://www.lua.org/manual/5.4/manual.html#pdf-math.sqrt),
+[math.tan](https://www.lua.org/manual/5.4/manual.html#pdf-math.tan),
+[math.type](https://www.lua.org/manual/5.4/manual.html#pdf-math.type),
+[package.cpath](https://www.lua.org/manual/5.4/manual.html#pdf-package.cpath).
+
+Lunatik **modifies** the following identifiers:
+* [\_VERSION](https://www.lua.org/manual/5.4/manual.html#pdf-_VERSION): is defined as `"Lua 5.4-kernel"`.
+* [collectgarbage("count")](https://www.lua.org/manual/5.4/manual.html#pdf-collectgarbage): returns the total memory in use by Lua in **bytes**, instead of _Kbytes_.
+* [package.path](https://www.lua.org/manual/5.4/manual.html#pdf-package.path): is defined as `"/lib/modules/lua/?.lua;/lib/modules/lua/?/init.lua"`.
+* [require](https://www.lua.org/manual/5.4/manual.html#pdf-require): only supports built-in or already linked C modules, that is, Lunatik **cannot** load kernel modules dynamically.
+
+### C API
+
+Lunatik **does not** support
+[luaL\_Stream](https://www.lua.org/manual/5.4/manual.html#luaL_Stream),
+[luaL\_execresult](https://www.lua.org/manual/5.4/manual.html#luaL_execresult),
+[luaL\_fileresult](https://www.lua.org/manual/5.4/manual.html#luaL_fileresult),
+[luaopen\_io](https://www.lua.org/manual/5.4/manual.html#pdf-luaopen_io) and
+[luaopen\_os](https://www.lua.org/manual/5.4/manual.html#pdf-luaopen_os).
+
+Lunatik **modifies** [luaL\_openlibs](https://www.lua.org/manual/5.4/manual.html#luaL_openlibs) to remove [luaopen\_io](https://www.lua.org/manual/5.4/manual.html#pdf-luaopen_io) and [luaopen\_os](https://www.lua.org/manual/5.4/manual.html#pdf-luaopen_os).
+
+## Lunatik C API
+
+```C
+#include <lunatik.h>
+```
+
+#### lunatik\_runtime
+```C
+int lunatik_runtime(lunatik_runtime_t **pruntime, const char *script, bool sleep);
+```
+_lunatik\_runtime()_ creates a new `runtime` environment then loads and runs the script
+`/lib/modules/lua/<script>.lua` as the entry point for this environment.
+It _must_ only be called from _process context_.
+The `runtime` environment is composed by
+a [Lua state](https://www.lua.org/manual/5.4/manual.html#lua_State), 
+a [lock type](https://docs.kernel.org/locking/locktypes.html) and
+a [reference counter](https://www.kernel.org/doc/Documentation/kref.txt).
+If `sleep` is _true_, it will use a [mutex](https://docs.kernel.org/locking/mutex-design.html)
+for locking the `runtime` environment and the
+[GFP\_KERNEL](https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html)
+flag for allocating new memory later on on
+[lunatik\_run()](https://github.com/luainkernel/lunatik/tree/lneto_doc#lunatik_run) calls.
+Otherwise, it will use a [spinlock](https://docs.kernel.org/locking/locktypes.html#raw-spinlock-t-and-spinlock-t) and [GFP\_ATOMIC](https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html).
+_lunatik\_runtime()_ opens the Lua standard libraries
+[present on Lunatik](https://github.com/luainkernel/lunatik/tree/lneto_doc#c-api)
+and, if `sleep` is _true_, it also opens the
+[lunatik](https://github.com/luainkernel/lunatik/tree/lneto_doc#lunatik-1)
+library to make them available for the `script`.
+If successful, _lunatik\_runtime()_ sets the address pointed by `pruntime` and
+[Lua's extra space](https://www.lua.org/manual/5.4/manual.html#lua_getextraspace)
+with a pointer for the new created `runtime` environment,
+sets the _reference counter_ to `1` and then returns `0`. 
+Otherwise, it returns `-ENOMEM`, if insufficient memory is available; 
+or `-EINVAL`, if it fails to load or run the `script`.
+
+##### Example
+```Lua
+-- /lib/modules/lua/mydevice.lua
+function myread(len, off)
+	return "42"
+end
+```
+
+```C
+static lunatik_runtime_t *runtime;
+
+static int __init mydevice_init(void)
+{
+	return lunatik_runtime(&runtime, "mydevice", true);
+}
+
+```
+
+#### lunatik\_stop
+```C
+int lunatik_stop(lunatik_runtime_t *runtime);
+```
+_lunatik\_stop()_
+[closes](https://www.lua.org/manual/5.4/manual.html#lua_close)
+the
+[Lua state](https://www.lua.org/manual/5.4/manual.html#lua_State)
+created for this `runtime` environment and decrements the
+[reference counter](https://www.kernel.org/doc/Documentation/kref.txt).
+Once the reference counter is decremented to zero, the
+[lock type](https://docs.kernel.org/locking/locktypes.html)
+and the memory allocated for the `runtime` environment are released.
+If the `runtime` environment has been released, it returns `1`;
+otherwise, it returns `0`.
+
+#### lunatik\_run
+```C
+void lunatik_run(lunatik_runtime_t *runtime, <inttype> (*handler)(...), <inttype> &ret, ...);
+```
+_lunatik\_run()_ locks the `runtime` environment and calls the `handler`
+passing the associated Lua state as the first argument followed by the variadic arguments.
+If the Lua state has been closed, `ret` is set with `-ENXIO`;
+otherwise, `ret` is set with the result of `handler(L, ...)` call.
+Then, it restores the Lua stack and unlocks the `runtime` environment.
+It is defined as a macro.
+
+##### Example
+```C
+static int l_read(lua_State *L, char *buf, size_t len, loff_t *off)
+{
+	size_t llen;
+	const char *lbuf;
+
+	lua_getglobal(L, "myread");
+	lua_pushinteger(L, len);
+	lua_pushinteger(L, *off);
+	if (lua_pcall(L, 2, 2, 0) != LUA_OK) { /* calls myread(len, off) */
+		pr_err("%s\n", lua_tostring(L, -1));
+		return -ECANCELED;
+	}
+
+	lbuf = lua_tolstring(L, -2, &llen);
+	llen = min(len, llen);
+	if (copy_to_user(buf, lbuf, llen) != 0)
+		return -EFAULT;
+
+	*off = (loff_t)luaL_optinteger(L, -1, *off + llen);
+	return (ssize_t)llen;
+}
+
+static ssize_t mydevice_read(struct file *f, char *buf, size_t len, loff_t *off)
+{
+	ssize_t ret;
+	lunatik_runtime_t *runtime = (lunatik_runtime_t *)f->private_data;
+
+	lunatik_run(runtime, l_read, ret, buf, len, off);
+	return ret;
+}
+```
+
+#### lunatik\_get
+```C
+void lunatik_get(lunatik_runtime_t *runtime);
+```
+_lunatik\_get()_ increments the
+[reference counter](https://www.kernel.org/doc/Documentation/kref.txt)
+of this `runtime` environment.
+
+#### lunatik\_put
+```C
+int lunatik_put(lunatik_runtime_t *runtime);
+```
+_lunatik\_put()_ decrements the
+[reference counter](https://www.kernel.org/doc/Documentation/kref.txt)
+of this `runtime` environment.
+If the `runtime` environment has been released, it returns `1`;
+otherwise, it returns `0`.
+
+#### lunatik\_toruntime
+```C
+lunatik_runtime_t *lunatik_toruntime(lua_State *L);
+```
+_lunatik\_toruntime()_ returns the `runtime` environment referenced by the `L`'s
+[extra space](https://www.lua.org/manual/5.4/manual.html#lua_getextraspace).
+
+## Lunatik Lua APIs
+
+### lunatik
+
+The `lunatik` library provides support to load and run scripts and manage runtime environments from Lua. 
+
+#### `lunatik.runtime(script [, sleep])`
+
+_lunatik.runtime()_ creates a new
+[runtime environment](https://github.com/luainkernel/lunatik/tree/lneto_doc#lunatik_runtime)
+then loads and runs the script
+`/lib/modules/lua/<script>.lua` as the entry point for this environment.
+It returns a
+[userdata](https://www.lua.org/manual/5.4/manual.html#2.1)
+representing the `runtime` environment.
+If `sleep` is _true_ or omitted, it will use a [mutex](https://docs.kernel.org/locking/mutex-design.html)
+and
+[GFP\_KERNEL](https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html);
+otherwise, it will use a [spinlock](https://docs.kernel.org/locking/locktypes.html#raw-spinlock-t-and-spinlock-t) and [GFP\_ATOMIC](https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html).
+_lunatik.runtime()_ opens the Lua standard libraries
+[present on Lunatik](https://github.com/luainkernel/lunatik/tree/lneto_doc#c-api),
+but differently from
+[lunatik\_runtime()](https://github.com/luainkernel/lunatik/tree/lneto_doc#lunatik_runtime),
+it **does not** open the `lunatik` library.
+
+#### `lunatik.stop(runtime)`, `runtime:stop()`
+
+_lunatik.stop()_
+[stops](https://github.com/luainkernel/lunatik/tree/lneto_doc#lunatik_stop)
+the `runtime` environment and clear its reference from the runtime
+[userdata](https://www.lua.org/manual/5.4/manual.html#2.1).
+
+### device
+
+The `device` library provides support for writting
+[character device drivers](https://static.lwn.net/images/pdf/LDD3/ch03.pdf)
+in Lua.
+
+#### `device.new(driver)`
+
+_device.new()_ returns a new `device`
+[userdata](https://www.lua.org/manual/5.4/manual.html#2.1)
+and installs its `driver` in the system. 
+The `driver` **must** be defined as a table containing the following field:
+* `name`: string defining the device name; it is used for creating the device file (e.g., `/dev/<name>`).
+
+The `driver` table might optionally contain the following fields:
+* `read`: callback function to handle the
+[read operation](https://docs.kernel.org/filesystems/vfs.html#id2)
+on the device file.
+It receives the `driver` table as the first argument
+followed by two integers,
+the `length` to be read and the file `offset`.
+It should return a string and, optionally, the `updated offset`.
+If the length of the returned string is greater than the requested `length`,
+the string will be corrected to that `length`. 
+If the `updated offset` is not returned, the `offset` will be updated with `offset + length`.
+* `write`: callback function to handle the
+[write operation](https://docs.kernel.org/filesystems/vfs.html#id2)
+on the device file.
+It receives the `driver` table as the first argument
+followed by the string to be written and
+an integer as the file `offset`.
+It might return optionally the written `length` followed by the `updated offset`.
+If the returned length is greater than the requested `length`,
+the returned length will be corrected.
+If the `updated offset` is not returned, the `offset` will be updated with `offset + length`.
+* `open`: callback function to handle the
+[open operation](https://docs.kernel.org/filesystems/vfs.html#id2)
+on the device file.
+It receives the `driver` table and it is expected to return nothing.
+* `release`: callback function to handle the
+[release operation](https://docs.kernel.org/filesystems/vfs.html#id2)
+on the device file.
+It receives the `driver` table and it is expected to return nothing.
+* `mode`: an integer specifying the device
+[file mode](https://github.com/luainkernel/lunatik/tree/lneto_doc#linuxstat).
+
+If an operation callback is not defined, the `device` returns `-ENXIO` to VFS on its access.
+
+#### `device.delete(dev)`, `dev:delete()`
+
+_device.delete()_ removes a device `driver` specified by the `dev`
+[userdata](https://www.lua.org/manual/5.4/manual.html#2.1)
+from the system. 
+
+### linux
+
+The `linux` library provides support for some Linux kernel facilities.
+
+#### `linux.random([m [, n]])`
+
+_linux.random()_ mimics the behavior of
+[math.random](https://www.lua.org/manual/5.4/manual.html#pdf-math.random),
+but binding _<linux/random.h>_'s
+[get\_random\_u32()](https://elixir.bootlin.com/linux/latest/source/include/linux/random.h#L42)
+and
+[get\_random\_u64()](https://elixir.bootlin.com/linux/latest/source/include/linux/random.h#L43)
+APIs.
+
+When called without arguments,
+produces an integer with all bits (pseudo)random.
+When called with two integers `m` and `n`,
+_linux.random()_ returns a pseudo-random integer with uniform distribution in the range `[m, n]`.
+The call `math.random(n)`, for a positive `n`, is equivalent to `math.random(1, n)`.
+
+#### `linux.stat`
+
+_linux.stat_ is a table that exports
+[\<linux/stat.h\>](https://elixir.bootlin.com/linux/latest/source/include/linux/stat.h)
+integer flags to Lua.
+
+* `"IRWXUGO"`: permission to _read_, _write_ and _execute_ for _user_, _group_ and _other_.
+* `"IRUGO"`: permission only to _read_ for _user_, _group_ and _other_.
+* `"IWUGO"`: permission only to _write_ for _user_, _group_ and _other_.
+* `"IXUGO"`: permission only to _execute_ for _user_, _group_ and _other_.
+
+## References
+
+* [Scriptables Operating Systems with Lua](https://www.netbsd.org/~lneto/dls14.pdf)
+* [Linux Network Scripting with Lua](https://legacy.netdevconf.info/0x14/session.html?talk-linux-network-scripting-with-lua)
+
diff --git a/lib/luadevice.c b/lib/luadevice.c
index b3495895..770fb5bc 100644
--- a/lib/luadevice.c
+++ b/lib/luadevice.c
@@ -151,11 +151,7 @@ static int luadevice_fop(lua_State *L, int ud, const char *fop, int nargs, int n
 
 static int luadevice_doopen(lua_State *L, int ud)
 {
-	int ret;
-
-	if ((ret = luadevice_fop(L, ud, "open", 0, 1)) != 0)
-		return ret;
-	return (int)lua_tointeger(L, -1);
+	return luadevice_fop(L, ud, "open", 0, 0);
 }
 
 static ssize_t luadevice_doread(lua_State *L, int ud, char *buf, size_t len, loff_t *off)
@@ -205,11 +201,7 @@ static ssize_t luadevice_dowrite(lua_State *L, int ud, const char *buf, size_t l
 
 static int luadevice_dorelease(lua_State *L, int ud)
 {
-	int ret;
-
-	if ((ret = luadevice_fop(L, ud, "release", 0, 1)) != 0)
-		return ret;
-	return (int)lua_tointeger(L, -1);
+	return luadevice_fop(L, ud, "release", 0, 0);
 }
 
 #define luadevice_fromfile(f)	((luadevice_t *)f->private_data)
diff --git a/lib/lualinux.c b/lib/lualinux.c
index 1671fa8c..66a30fd3 100644
--- a/lib/lualinux.c
+++ b/lib/lualinux.c
@@ -23,6 +23,7 @@
 
 #include <linux/module.h>
 #include <linux/random.h>
+#include <linux/stat.h>
 
 #include <lua.h>
 #include <lualib.h>
@@ -65,14 +66,52 @@ static int lualinux_random(lua_State *L)
 	return 1;
 }
 
+typedef struct lualinux_stat_s {
+	const char *name;
+	lua_Integer flag;
+} lualinux_stat_t;
+
+static lualinux_stat_t lualinux_stat[] = {
+	/* user */
+	{"IRWXU", S_IRWXU},
+	{"IRUSR", S_IRUSR},
+	{"IWUSR", S_IWUSR},
+	{"IXUSR", S_IXUSR},
+	/* group */
+	{"IRWXG", S_IRWXG},
+	{"IRGRP", S_IRGRP},
+	{"IWGRP", S_IWGRP},
+	{"IXGRP", S_IXGRP},
+	/* other */
+	{"IRWXO", S_IRWXO},
+	{"IROTH", S_IROTH},
+	{"IWOTH", S_IWOTH},
+	{"IXOTH", S_IXOTH},
+	/* user, group, other */
+	{"IRWXUGO", (S_IRWXU|S_IRWXG|S_IRWXO)},
+	{"IALLUGO", (S_ISUID|S_ISGID|S_ISVTX|S_IRWXUGO)},
+	{"IRUGO", (S_IRUSR|S_IRGRP|S_IROTH)},
+	{"IWUGO", (S_IWUSR|S_IWGRP|S_IWOTH)},
+	{"IXUGO", (S_IXUSR|S_IXGRP|S_IXOTH)},
+	{NULL, 0}
+};
+
 static const luaL_Reg linux_lib[] = {
 	{"random", lualinux_random},
+	{"stat", NULL}, /* placeholder */
 	{NULL, NULL}
 };
 
 int luaopen_linux(lua_State *L)
 {
+	lualinux_stat_t *s;
 	luaL_newlib(L, linux_lib);
+	lua_newtable(L); /* stat = {} */
+	for (s = lualinux_stat; s->name; s++) {
+		lua_pushinteger(L, s->flag);
+		lua_setfield(L, -2, s->name); /* stat[name] = flag */
+	}
+	lua_setfield(L, -2, "stat"); /* lib.stat = stat */
 	return 1;
 }
 EXPORT_SYMBOL(luaopen_linux);
diff --git a/lua b/lua
index 22963a63..6dd6066d 160000
--- a/lua
+++ b/lua
@@ -1 +1 @@
-Subproject commit 22963a636d348a3a63e262cf509db72917c776f3
+Subproject commit 6dd6066d96ebcdc84af256638ab10c65a872f357
diff --git a/lunatik.h b/lunatik.h
index e0519ffc..ce488a5f 100644
--- a/lunatik.h
+++ b/lunatik.h
@@ -56,8 +56,8 @@ do {							\
 #define lunatik_unlock(runtime)	lunatik_locker(runtime, mutex_unlock, spin_unlock)
 #define lunatik_toruntime(L)	(*(lunatik_runtime_t **)lua_getextraspace(L))
 
-int lunatik_runtime(lunatik_runtime_t **pruntime, const char *entrypoint, bool sleep);
-void lunatik_stop(lunatik_runtime_t *runtime);
+int lunatik_runtime(lunatik_runtime_t **pruntime, const char *script, bool sleep);
+int lunatik_stop(lunatik_runtime_t *runtime);
 
 static inline void lunatik_release(struct kref *kref)
 {
diff --git a/lunatik_core.c b/lunatik_core.c
index 95f697ac..1470958e 100644
--- a/lunatik_core.c
+++ b/lunatik_core.c
@@ -84,7 +84,7 @@ static inline void lunatik_runerror(lua_State *L, lua_State *parent, const char
 
 int luaopen_lunatik(lua_State *L); /* used for luaL_requiref() */
 
-static int lunatik_newruntime(lunatik_runtime_t **pruntime, lua_State *parent, const char *entrypoint, bool sleep)
+static int lunatik_newruntime(lunatik_runtime_t **pruntime, lua_State *parent, const char *script, bool sleep)
 {
 	lunatik_runtime_t *runtime;
 	lua_State *L;
@@ -108,7 +108,7 @@ static int lunatik_newruntime(lunatik_runtime_t **pruntime, lua_State *parent, c
 	if (!parent) /* child runtimes cannot create new */
 		luaL_requiref(L, "lunatik", luaopen_lunatik, 1);
 
-	filename = lua_pushfstring(L, "%s%s.lua", LUA_ROOT, entrypoint);
+	filename = lua_pushfstring(L, "%s%s.lua", LUA_ROOT, script);
 	if (luaL_dofile(L, filename) != LUA_OK) {
 		lunatik_runerror(L, parent, lua_tostring(L, -1));
 		lua_close(L);
@@ -128,19 +128,19 @@ static int lunatik_newruntime(lunatik_runtime_t **pruntime, lua_State *parent, c
         return 0;
 }
 
-int lunatik_runtime(lunatik_runtime_t **pruntime, const char *entrypoint, bool sleep)
+int lunatik_runtime(lunatik_runtime_t **pruntime, const char *script, bool sleep)
 {
-	return lunatik_newruntime(pruntime, NULL, entrypoint, sleep);
+	return lunatik_newruntime(pruntime, NULL, script, sleep);
 }
 EXPORT_SYMBOL(lunatik_runtime);
 
-void lunatik_stop(lunatik_runtime_t *runtime)
+int lunatik_stop(lunatik_runtime_t *runtime)
 {
 	lunatik_lock(runtime);
 	lua_close(runtime->L);
 	runtime->L = NULL;
 	lunatik_unlock(runtime);
-	lunatik_put(runtime);
+	return lunatik_put(runtime);
 }
 EXPORT_SYMBOL(lunatik_stop);
 
@@ -148,14 +148,14 @@ EXPORT_SYMBOL(lunatik_stop);
 static int lunatik_lruntime(lua_State *L)
 {
 	lunatik_runtime_t **pruntime;
-	const char *entrypoint;
+	const char *script;
 	bool sleep;
 
-	entrypoint = luaL_checkstring(L, 1);
+	script = luaL_checkstring(L, 1);
 	sleep = (bool)(lua_gettop(L) >= 2 ? lua_toboolean(L, 2) : true);
 
 	pruntime = (lunatik_runtime_t **)lua_newuserdatauv(L, sizeof(lunatik_runtime_t *), 0);
-	if (lunatik_newruntime(pruntime, L, entrypoint, sleep) != 0)
+	if (lunatik_newruntime(pruntime, L, script, sleep) != 0)
 		lua_error(L);
 	luaL_setmetatable(L, LUNATIK_MT);
 	return 1;
diff --git a/sbin/lunatik b/sbin/lunatik
index d8c21c64..9a9d4549 100755
--- a/sbin/lunatik
+++ b/sbin/lunatik
@@ -58,20 +58,23 @@ function lunatik.dostring(chunk)
 	return lunatik.result()
 end
 
+function lunatik.usage()
+	print("usage: sbin/lunatik [[--run] <script>] [--stop <script>]")
+	os.exit(false)
+end
+
 lunatik.probe()
 
 local parser = {
-	['-c'] = 'return string.dump(loadfile("%s"))',
-	['-r'] = 'lunatik.__runtimes["%s"] = lunatik.runtime("%s")',
-	['-s'] = 'lunatik.__runtimes["%s"]:stop() lunatik.__runtimes["%s"] = nil',
-	['-f'] = 'dofile("%s")'
+	['--run'] = 'lunatik.__runtimes["%s"] = lunatik.runtime("%s")',
+	['--stop'] = 'lunatik.__runtimes["%s"]:stop() lunatik.__runtimes["%s"] = nil',
 }
-local default = '-f'
+local default = '--run'
 if #arg >= 1 then
 	local fmt = string.format
 	local chunk = #arg == 1 and
-		fmt(parser[default], arg[1]) or
-		fmt(parser[arg[1]], arg[2], arg[2])
+		fmt(parser[default], arg[1], arg[1]) or
+		fmt(parser[arg[1]] or lunatik.usage(), arg[2], arg[2])
 	print(lunatik.dostring(chunk))
 	os.exit()
 end