Module luxio.simple

High-level bindings to POSIX functionality.

Tables

stat stat result table.

Class file

file.fd The file descriptor as a number.
file.name Helpful text representation of file handle.
file:close() Close an open file.
file:nogc() Disable garbage collection of a file.
file:nonblocking(blocking) Set the non-blocking flag on a file.
file:write(data[, offset=1]) Write data to a file.
file:writev(...) Write a list of strings to a file.
file:read(...) Read data from a file.
file:fstat() Get information on an option file.
file:seek(whence, offset) Change the position within a file.
file:lock(rw, whence, offset, len, wait, test) Apply or remove an advisory lock on an open file.
file:unlock(whence, offset, len) Unlock a region of an open file.

Helper functions

flags(...) Convert a string of comma-seperated flag names to a number.
tomode(f) Convert a string representing a permissions mode to a number.

Opening files

open(filename[, flags="r"[, number]]) Open a file.
pipe() Create an anonymous pipe.
pipe() Create an anonymous UNIX domain socket pair.


Tables

stat
stat result table. The table that all the stat family returns.

Fields:

  • dev ID of device containing file
  • ino inode number
  • mode protection mode
  • nlink number of hard links
  • uid user ID of owner
  • gid group ID of owner
  • rdev device ID (if special file)
  • size total size, in bytes
  • blksize blocksize for file system I/O
  • blocks number of 512 byte blocks allocated
  • atime time of last access
  • mtime time of last modification
  • ctime time of last status change

Class file

A file handle. The basic type used to expose file handles.
file.fd
The file descriptor as a number.
file.name
Helpful text representation of file handle.
file:close()
Close an open file.

Returns:

  1. bool or nil true on success, nil on failure
  2. string or nil string describing error
  3. errno or nil errno on error
file:nogc()
Disable garbage collection of a file.
file:nonblocking(blocking)
Set the non-blocking flag on a file.

Parameters:

  • blocking bool true for non-blocking, false or nil for blocking.
file:write(data[, offset=1])
Write data to a file.

Parameters:

  • data string
  • offset number into string to start write from (default 1)

Returns:

  1. number or nil bytes written, or nil on error
  2. string or nil string describing error if error
  3. errno or nil errno if error
file:writev(...)
Write a list of strings to a file.

Parameters:

  • ... string List of strings to write

Returns:

  1. number or nil Bytes written, or nil in case of error
  2. string or nil string describing error if error
  3. errno or nil errno if error
file:read(...)

Read data from a file. This function takes a list of patterns to read, based loosely on Lua’s own read function. They are:

  • “*a” - read all data until end of file.
  • “*l” - read a single line of data, or until end of file.
  • Or, a number describing the number of bytes to read.

Parameters:

  • ... string List of read patterns.

Returns:

  1. ... or nil List of return strings, or nil if error
  2. string or nil String describing error if error
  3. errno or nil errno if error
file:fstat()
Get information on an option file.

Returns:

  1. stat or nil stat table or nil if error
  2. string or nil string describing error if error
  3. errno or nil errno if error
file:seek(whence, offset)
Change the position within a file.

Parameters:

  • whence string one of “cur”, “set”, and “end”.
  • offset number signed number describing requested change.

Returns:

  1. number or nil resulting offset, as measured from beginning of file in bytes, or nil if error.
  2. string or nil string describing error if error
  3. errno or nil errno if error
file:lock(rw, whence, offset, len, wait, test)
Apply or remove an advisory lock on an open file.

Parameters:

  • rw string Lock type “r” for read, “w” for write, “” for unlock.
  • whence string one of “cur”, “set”, and “end”
  • offset number offset of start of lock/unlock location
  • len number length in bytes of lock/unlock locations
  • wait bool true if the call should block until region is unlocked
  • test bool true if you simply want to check if locked

Returns:

  1. true or nil nil if error
  2. string or nil string describing error if error
  3. errno or nil errno if error
file:unlock(whence, offset, len)
Unlock a region of an open file. Convienence function. Simply calls file:lock with an empty rw.

Parameters:

  • whence string
  • offset number
  • len number

Returns:

  1. true or nil nil if error
  2. string or nil string describing error if error
  3. errno or nil errno if error

Helper functions

flags(...)

Convert a string of comma-seperated flag names to a number. This function takes a list of strings, each with comma-seperated flag names and returns a number which is all of those flags ORed together. Flags can optionally be lower-case, and also if they begin with one of the common prefixes, such as O, S, F, AF, AI, SO, TCP_ and many others can be omitted. For example:

 myflags = sio.flags "rdwr,creat,excl"

Parameters:

Returns:

    number
tomode(f)

Convert a string representing a permissions mode to a number. This function converts a string into a mode flag. It supports many different forms. For example:

sio.tomode(0666) -- already a mode, it'll just return it
sio.tomode "666" -- converted directly to number, assumed octal
sio.tomode "-rw-r--r--" -- as emitted by ls
sio.tomode "o+rw,g+r" -- as used by chmod

Parameters:

  • f number or string mode description to convert

Returns:

    number

Opening files

open(filename[, flags="r"[, number]])

Open a file. The open type may contain the following characters;

  • r - open file for reading
  • w - open file for writing
  • + - append
  • e - open and create exclusively (O_EXCL and O_CREAT)
  • c - create file if it doesn’t exist. (O_CREAT)
  • n - do not modify access time (O_NOATIME)
  • d - open in non-blocking mode (O_NDELAY)
  • t - truncate file

Parameters:

  • filename string
  • flags string open type (default "r")
  • number mode permissions mode if creating. (optional)

Returns:

  1. file or nil File handle, or nil if error
  2. string or nil Error string if error
  3. errno or nil Error number if error
pipe()
Create an anonymous pipe. Returns two files, the first one can be used to read data written to the second.

Returns:

  1. file or nil Reading half of pipe, or nil on error
  2. file or string Writing half of pipe, or string describing error
  3. errno or nil Error number if error
pipe()
Create an anonymous UNIX domain socket pair. Returns two files, which can be considered as each end of a bi-directional pipe.

Returns:

  1. file or nil First socket of the pair, or nil on error
  2. file or string Second socket of the pair, or string describing error
  3. errno or nil Error number if error
generated by LDoc 1.4.3 Last updated 1475051115