Portable low-level filesystem and OS interface for Lua.
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Lorenzo Cogotti d2e35dce50 [examples/cat] Fix exit status. 3 months ago
examples [examples/cat] Fix exit status. 3 months ago
.gitignore [.gitignore] Cleanup .gitignore, exclude doc folder. 6 months ago
LICENSE [LICENSE] Improve formatting 6 months ago
Makefile [Makefile] Also update uninstall target. 6 months ago
README.md [README] Typo fix. 6 months ago
config.ld [osx,config.ld] Add LDoc documentation. 6 months ago
config.macosx [*] First commit. 6 months ago
config.mk [config.mk] Add -f flag to RM. 6 months ago
config.unix [*] First commit. 6 months ago
config.win [*] First commit. 6 months ago
dir_unix.c [*] First commit. 6 months ago
dir_win32.c [*] First commit. 6 months ago
luacompat.h [luacompat] luaL_pushfail() was actually introduced with Lua 5.3. 6 months ago
osx-scm-1.rockspec [rockspec] Add LuaRocks rock file. 6 months ago
osx.c [osx] Document isatty(). 6 months ago
osx.h [*] First commit. 6 months ago
osx_dir.h [*] First commit. 6 months ago
xconf.h [*] First commit. 6 months ago


Operating System eXtensions for Lua

A C module to provide a few fundamental system-specific facilities to the Lua language.

This library provides means to:

  • traverse and filter directory contents;
  • retrieve basic file information (type, size, modification time, ...);
  • create directories;
  • advanced file interaction (change size and mode, lock files, advise kernel on file access pattern, ...).


Mainline Lua only exposes functionality when directly available through the standard C library (with the notable exception of popen()). This is justified by the embeddable nature of Lua.

Yet, a minimum degree of system-specific interaction is needed to complete basic to advanced general purpose scripting and programmatic tasks. lua-osx attempts to fill this gap.


The library adheres the following guidelines:

  • only provide essential and reasonably portable functionality;
  • integrate seamlessly with the official Lua library (e.g. support Lua files as arguments, behave consistently with the Lua standard library);
  • avoid functionality only available in one system (e.g. providing a Linux-only function).

These are intended to be general principles, exceptions may apply when justified.


lua-osx is portable with most relevant Lua implementations, specifically it is tested on PUC Rio Lua and LuaJIT. Code is known to work on Linux and Windows, and it should be portable to any POSIX system (BSD and Mac).

Build and install

lua-osx comes with a Makefile and a LuaRocks file.

Windows users should note that lua-osx does not support MSVC and never will. It requires a fairly modern C compiler with C11 support and minimal Unix-style shell tools. On Windows you may use MSYS with either MinGW or clang.

Using LuaRocks

You can build and install lua-osx locally on for your user, by opening a shell in the project's root directory and issuing the following command:

$ luarocks build --local

Or alternatively build and install it system-wide with:

# luarocks build --global

Building using Makefile

lua-osx rock uses the project Makefile to do build the module.

The Makefile may also be used stand-alone, and support a number of configurations to adapt to the different supported systems. These may be picked with the CONFIG variable.

  • Building on GNU/Linux and regular Unix-like systems

    The regular Unix configuration is used by default, thus you may simply run:

    $ make

    Or use the extended (equivalent) form:

    $ make CONFIG=config.unix
  • Building on Windows

    You may build lua-osx using any fairly recent C compiler with C11 support (e.g. MinGW or clang), and Unix-style shell utilities and make (e.g. MSYS and GNU make).

    $ make CONFIG=config.win
  • Building on Mac

    To build lua-osx on Mac select the config.macosx configuration:

    $ make CONFIG=config.macosx

Installing using Makefiles

lua-osx Makefile supports your average clean, doc, install and uninstall targets, thus you can install lua-osx system wide by running:

# make install


lua-osx uses LDoc for documentation.

You can generate documentation using ldoc directly, running the following command:

$ ldoc .

Or using the doc Makefile target:

$ make doc

Both methods generate a doc directory, open doc/index.html with your favorite browser to read the API documentation.

Similar Projects


lua-osx is free software. You can redistribute and/or modify it under the terms of the GNU Lesser General Public License. See LICENSE file for details.