diff options
Diffstat (limited to 'luxio/simple.lua')
| -rw-r--r-- | luxio/simple.lua | 93 |
1 files changed, 92 insertions, 1 deletions
diff --git a/luxio/simple.lua b/luxio/simple.lua index b5d99bd..09c6074 100644 --- a/luxio/simple.lua +++ b/luxio/simple.lua @@ -5,7 +5,10 @@ -- -- A wrapper around the rather raw interface luxio normally provides to -- make things simpler. -------------------------------------------------------------------------------- + +--- High-level bindings to POSIX functionality. +--- @module luxio.simple + -- -- sio = require "luxio.simple" -- @@ -198,6 +201,12 @@ -- For example, flags("rdrw,creat,excl") would be the same as ORing -- together O_RDWR, O_CREAT, and O_EXCL. +--- A file handle. +--- All files, be they ones in a file system, a pipe, or a socket, are +--- accessed though this type. +--- @type file +--- @field number file descriptor + local l = require "luxio" assert(l._ABI == 0, "luxio ABI mismatch") @@ -320,6 +329,21 @@ end local flag_cache = { } +--- Helper functions. +--- @section helper + +--- 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" +--- @tparam string ... +--- @treturn number +--- @function flags local function flags(...) local r = 0 local f = table.concat({ ... }, ",") @@ -363,6 +387,17 @@ local S_IWALL = l_bit_bor(l.S_IWUSR, l.S_IWGRP, l.S_IWOTH) local S_IXALL = l_bit_bor(l.S_IXUSR, l.S_IXGRP, l.S_IXOTH) local S_ISUIDGID = l_bit_bor(l.S_ISUID, l.S_ISGID) +--- 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 +--- @tparam number|string f mode description to convert +--- @treturn number +--- @function tomode local function sio_mode_flags(f) if type(f) == "number" then -- is already a suitable mode @@ -438,6 +473,27 @@ local function sio_open_flags(flags) return l_bit_bor(unpack(r)) end +--- Opening files. +--- @section open + +--- 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 +--- @tparam string filename +--- @tparam[opt="r"] string flags open type +--- @tparam[opt] mode number permissions mode if creating. +--- @treturn file|nil File handle, or nil if error +--- @treturn string|nil Error string if error +--- @treturn errno|nil Error number if error +--- @function open local function open(filename, flags, mode) mode = mode or tonumber("666", 8) assert(type(filename) == "string", "filename string expected at #1") @@ -453,6 +509,13 @@ end local pipe_count = 0 +--- Create an anonymous pipe. +--- Returns two files, the first one can be used to read data written +--- to the second. +--- @treturn file|nil Reading half of pipe, or nil on error +--- @treturn file|string Writing half of pipe, or string describing error +--- @treturn errno|nil Error number if error +--- @function pipe local function pipe() local fds = { } local r, errno = l_pipe(fds) @@ -471,6 +534,13 @@ end local socketpair_count = 0 +--- Create an anonymous UNIX domain socket pair. +--- Returns two files, which can be considered as each end of a bi-directional +-- pipe. +--- @treturn file|nil First socket of the pair, or nil on error +--- @treturn file|string Second socket of the pair, or string describing error +--- @treturn errno|nil Error number if error +--- @function pipe local function socketpair(type) type = type or l.SOCK_STREAM local typen = type == l.SOCK_STREAM and "stream" or "datagram" @@ -488,6 +558,12 @@ local function socketpair(type) return sio_wrap_mt(sv[1], false, spname1), sio_wrap_mt(sv[2], false, spname2) end +--- Close an open file. +--- @function file:close +--- @within file +--- @treturn bool|nil true on success, nil on failure +--- @treturn string|nil string describing error +--- @treturn errno|nil errno on error local function close(o) sio_check_mt(o) @@ -502,12 +578,19 @@ local function close(o) return true end +--- Disable garbage collection of a file. +--- @function file:nogc +--- @within file local function nogc(o) sio_check_mt(o) o.nogcfd = true end +--- Set the non-blocking flag on a file. +--- @function file:nonblocking +--- @within file +--- @tparam bool blocking true for non-blocking, false or nil for blocking. local function nonblocking(o, b) sio_check_mt(o) @@ -537,6 +620,14 @@ local function nonblocking(o, b) end end +--- Write data to a file. +--- @function file:write +--- @within file +--- @tparam string data +--- @tparam[opt=1] number offset into string to start write from +--- @treturn number|nil bytes written, or nil on error +--- @treturn string|nil string describing error if error +--- @treturn errno|nil errno if error local function write(o, d, i) sio_check_mt(o) assert(type(d) == "string", "string expected at #2") |