lua_funcs.txt 6.22 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77
Lua injections
==============

We inject several functions into the lua global environment. Since
there's no good place to document them (like .h files for C code),
they are listed here

Logging
-------

log(level, msg, msg, msg, ...)::
  This is a low-level function used for logging. It should not be used
  directly by lua code. The messages are just strings that are
  concatenated together before outputting. The level is one of:
  - DIE
  - ERROR
  - WARN
  - DBG
ERROR(msg, msg, ...)::
WARN(msg, msg, ...)::
DBG(msg, msg, ...)::
  These output a message to the logs with a given level. The messages
  are concatenated together.
DIE(msg, msg, ...)::
  In addition to outputting the message on the ``DIE`` level, it also
  terminates the application with error exit code.

Asynchronous events
-------------------

Some of the functions from ``events.h`` are exposed to lua code, with
minor modifications.

Currently, it is possible to run external commands with the
`run_command` function. The code would look like this:

  function terminated(exit_code, killed, stdout, stderr)
    -- The command terminated
  end

  function postfork()
    -- Run after fork in the child ‒ set up the environment
  end

  local id = run_command(terminated, postfork, input, term_timeout, kill_timeout, command, param, param)

  events_wait(id)

The functionality is very similar to the C functions, with these
differences:

* It doesn't take the `events` parameter, one global `events`
  structure per interpreter is used.
* The callbacks don't take the `data` or `wait_id` parameters, since
  lua has closures and passing information into the callbacks is easy.
* Lua naturally supports strings with embedded zero bytes, therefore
  there are no lengths of the inputs or outputs.
* The `exit_code` in the callback is not the raw integer from the
  system call, but decoded to the exit code of the process or signal
  number that terminated it.
* `killed` is a string, one of:
  - `TERMINATED`
  - `TERMED`
  - `KILLED`
  - `SIGNAL_OTHER`
* The events_wait take any number of ip parameters instead of an
  array.

The `postfork` and `input` parameters may be nil. The `term_timeout`
and `kill_timeout` take -1 to mean no timeout.

There may be any number of the `param` parameters, which are passed to
the command.

Currently, there's no way to cancel running command from lua, since
that would make the wrapper code needlessly complex (while there seems
to be no need to cancel them currently).
78 79 80 81 82 83 84 85 86

Filesystem manipulation
-----------------------

mkdtemp([directory])::
  It creates a temporary directory. If directory is provided, it is
  created as a subdirectory of the given directory, otherwise it is
  created inside `/tmp`. It returns path to the new directory, or
  `nil` and an error message.
87 88 89 90 91 92

chdir(directory)::
  Change the current working directory to the one provided.

getcwd()::
  Get the current working directory.
93 94 95 96 97 98 99

mkdir(directory)::
  Create a directory. All the parent directories must already exist.
  The directory itself shall not exist. It throws on error.

move(old, new)::
  Move a file from the old location to the new. It tries to cope with
100
  paths on different devices.
101 102

ls(directory)::
103 104 105 106 107 108 109 110 111 112 113
  Return a table with file names under the given directory (acts like
  shell's `ls -a`, omitting the `.` and `..` entries). Value of
  each is the type of the file there, which may be:
  b;; A block device
  c;; A character device
  d;; A directory
  f;; A named pipe
  l;; A symbolic link
  r;; A regular file
  s;; A unix-domain socket
  ?;; Failed to determine the type
114 115

stat(path)::
116 117 118 119
  Statistics about the given file. If the file does not exist, it
  returns nothing. Otherwise, the file type is returned (see the types
  of `ls`). The second result is the permissions of the file, in the
  imitation of shell's `ls -l`, like `rwxr-x---`.
120

121 122 123 124
sync()::
  Writes everything to a permanent storage (equivalent to the shell's
  `sync` command).

125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
Journal manipulation
--------------------

All the journal manipulation is located in the `journal` module. This
is about the lua interface. For the on-disk format, look at the
`journal` document.

The location of the journal can be set by the `path` variable inside
the module (it exists mostly for testing purposes).

There are several constants for the journal record types:

 `START`:: Automatically inserted at the beginning of journal.
 `FINISH`:: Automatically inserted when the journal is closed.
 `UNPACKED`:: Packages are unpacked and ready to be installed.
 `CHECKED`:: Pre-installation checks (like collision checks) are
   successfully performed.
 `MOVED`:: The files are moved into place.
 `SCRIPTS`:: All the post/pre-* scripts were run.
 `CLEANED`:: Cleanup of temporary files is successful.

There are following functions:

  fresh():: Open a new journal. It fails if there's a journal file
    already.
  recover():: Open a previous journal. It returns table with the
    content of the journal. It fails in case there's no journal.
  finish([keep]):: Close the journal. If the keep is set to true,
    it keeps the journal in place, otherwise it is deleted. The idea
    is that the application would close the journal when it succeeds,
    but would leave it there in case of interrupted operation, so
    usually nothing is set, the flag is for testing purposes.
  write(type, ...):: Write a journal record of the given type (see
    above). Any other parameters are stored as parameters. Data
    structures must not contain meta tables and functions.
  opened():: Returns if the journal is opened. This is for testing
    purposes.

The format of journal returned by recover is a table with records.
Each record contains `type` ‒ one of the types above, and `params` ‒
table with all the parameters stored with the record.
166 167 168 169 170 171 172 173 174 175 176 177 178

Others
------

There are some other functions.

DataDumper(variable)::
  A function that converts (almost any) variable to a string
  containing a lua chunk. The chunk, when run, returns equivalent
  value as passed. Simply stated, this serializes data into lua code.
  It is a third-party code from
  `http://lua-users.org/wiki/DataDumper`. Note that some data
  (userdata, for example) can't be represented this way.
179 180 181 182

setenv(name, value)::
  Set the environment variable with the given name to the given value.
  Errors in case of failure, otherwise returns nothing.