Module ffi.util

Module for various utility functions.

Functions

copyFile (from, to) Copies file.
joinPath (path1, path2) Joins paths.
purgeDir (dir) Purges directory.
execute (...) Executes child process.
runInSubProcess (func, with_pipe, double_fork) Run lua code (func) in a forked subprocess

With with_pipe=true, sets up a pipe for communication from children towards parent.
isSubProcessDone (pid, wait) Collect subprocess so it does not become a zombie.
terminateSubProcess (pid) Terminate subprocess pid by sending SIGKILL
getNonBlockingReadSize (fd_or_luafile) Returns the length of data that can be read immediately without blocking
writeToFD (fd, data, close_fd) Write data to file descriptor, and optionally close it when done

May block if data is large until the other end has read it.
writeToSysfs (val, file) Simple wrapper to write a string (will be coerced if not) to a file (mainly aimed at sysfs/procfs knobs).
readAllFromFD (fd) Read all data from file descriptor, and close it.
fsyncOpenedFile (fd_or_luafile, sync_metadata) Ensure content written to lua file or fd is flushed to the storage device.
fsyncDirectory (path) Ensure directory content updates are flushed to the storage device.
utf8charcode (charstring) Gets UTF-8 charcode.
multiByteToUTF8 (str, codepage) Converts multibyte string to utf-8 encoded string on Windows.
isAndroid () Returns true if Android.
loadSDL2 () Returns SDL2 library
idiv (a, b) Division with integer result.
template (str, ...) The util.template function allows for better translations through dynamic positioning of place markers.


Functions

copyFile (from, to)
Copies file.

Parameters:

  • from
  • to
joinPath (path1, path2)
Joins paths.

NOTE: If path2 is an absolute path, then this function ignores path1 and returns path2 directly.

Parameters:

  • path1
  • path2
purgeDir (dir)
Purges directory.

Parameters:

  • dir
execute (...)
Executes child process.

Parameters:

  • ...
runInSubProcess (func, with_pipe, double_fork)
Run lua code (func) in a forked subprocess

With withpipe=true, sets up a pipe for communication from children towards parent. func is called with the child pid as 1st argument, and, if withpipe: a fd for writting This function returns (to parent): the child pid, and, if withpipe: a fd for reading what the child wrote if doublefork: do a double fork so the child gets reparented to init,

             ensuring automatic reaping of zombies.
             NOTE: In this case, the pid returned will *already*
                   have been reaped, making it fairly useless.
                   This means you do NOT have to call isSubProcessDone on it.
                   It is safe to do so, though, it'll just immediately return success,
                   as waitpid will return -1 w/ an ECHILD errno.

NOTE: Assumes the target platform is POSIX compliant.

Parameters:

  • func
  • with_pipe
  • double_fork
isSubProcessDone (pid, wait)
Collect subprocess so it does not become a zombie. This does not block, unless wait is true. Returns true if process was collected or has already exited, false if process is still running.

Parameters:

  • pid
  • wait
terminateSubProcess (pid)
Terminate subprocess pid by sending SIGKILL

Parameters:

  • pid
getNonBlockingReadSize (fd_or_luafile)
Returns the length of data that can be read immediately without blocking Accepts a low-level file descriptor, or a higher level lua file object returns 0 if not readable yet, otherwise len of available data returns nil when unsupported: caller may read (with possible blocking)

Caveats with pipes: returns 0 too if other side of pipe has exited without writing anything

Parameters:

  • fd_or_luafile
writeToFD (fd, data, close_fd)
Write data to file descriptor, and optionally close it when done

May block if data is large until the other end has read it. If data fits into kernel pipe buffer, it can return before the other end has started reading it.

Parameters:

  • fd
  • data
  • close_fd
writeToSysfs (val, file)
Simple wrapper to write a string (will be coerced if not) to a file (mainly aimed at sysfs/procfs knobs).

Parameters:

  • val NOTE
  • file We do things by hand via ffi, because io.write uses fwrite, which isn't a great fit for procfs/sysfs (e.g., we lose failure cases like EBUSY, as it only reports failures to write to the stream, not to the disk/file!).
readAllFromFD (fd)
Read all data from file descriptor, and close it. This blocks until remote side has closed its side of the fd

Parameters:

  • fd
fsyncOpenedFile (fd_or_luafile, sync_metadata)
Ensure content written to lua file or fd is flushed to the storage device.

Accepts a low-level file descriptor, or a higher level lua file object, which must still be opened (call :close() only after having called this). If optional parameter sync_metadata is true, use fsync() to also flush file metadata (timestamps...), otherwise use fdatasync() to only flush file content and file size. Returns true if syscall successful See https://stackoverflow.com/questions/37288453/calling-fsync2-after-close2

Parameters:

  • fd_or_luafile
  • sync_metadata
fsyncDirectory (path)
Ensure directory content updates are flushed to the storage device.

Accepts the directory path as a string, or a file path (from which we can deduce the directory to sync). Returns true if syscall successful See http://blog.httrack.com/blog/2013/11/15/everything-you-always-wanted-to-know-about-fsync/

Parameters:

  • path
utf8charcode (charstring)
Gets UTF-8 charcode. See unicodeCodepointToUtf8 in frontend/util for an encoder.

Parameters:

  • charstring
multiByteToUTF8 (str, codepage)
Converts multibyte string to utf-8 encoded string on Windows.

Parameters:

  • str
  • codepage if codepage is not provided we will query the system codepage
isAndroid ()
Returns true if Android. For now, we just check if the "android" module can be loaded.
loadSDL2 ()
Returns SDL2 library
idiv (a, b)
Division with integer result.

Parameters:

  • a
  • b
template (str, ...)
The util.template function allows for better translations through dynamic positioning of place markers. The range of place markers runs from %1 to %99, but normally no more than two or three should be required. There are no provisions for escaping place markers.

Parameters:

  • str
  • ...

Usage:

        output = util.template(
        _("Hello %1, welcome to %2."),
        name,
        company
    )

This function was inspired by Qt:
<http://qt-project.org/doc/qt-4.8/internationalization.html#use-qstring-arg-for-dynamic-text>
generated by LDoc 1.5.0 Last updated 2025-01-24 21:45:56