path: root/modules/luci-base/luasrc/sys.luadoc

---[[
LuCI Linux and POSIX system utilities.
]]
module "luci.sys"

---[[
Execute a given shell command and return the error code

@class		function
@name		call
@param 		...		Command to call
@return		Error code of the command
]]

---[[
Execute a given shell command and capture its standard output

@class		function
@name		exec
@param command	Command to call
@return			String containing the return the output of the command
]]

---[[
Retrieve information about currently mounted file systems.

@class function
@name mounts
@return 	Table containing mount information
]]

---[[
Retrieve environment variables. If no variable is given then a table

containing the whole environment is returned otherwise this function returns
the corresponding string value for the given name or nil if no such variable
exists.
@class		function
@name		getenv
@param var	Name of the environment variable to retrieve (optional)
@return		String containing the value of the specified variable
@return		Table containing all variables if no variable name is given
]]

---[[
Get or set the current hostname.

@class function
@name hostname
@param		String containing a new hostname to set (optional)
@return		String containing the system hostname
]]

---[[
Returns the contents of a documented referred by an URL.

@class function
@name httpget
@param url	 The URL to retrieve
@param stream Return a stream instead of a buffer
@param target Directly write to target file name
@return		String containing the contents of given the URL
]]

---[[
Initiate a system reboot.

@class function
@name reboot
@return	Return value of os.execute()
]]

---[[
Retrieves the output of the "logread" command.

@class function
@name syslog
@return	String containing the current log buffer
]]

---[[
Retrieves the output of the "dmesg" command.

@class function
@name dmesg
@return	String containing the current log buffer
]]

---[[
Generates a random id with specified length.

@class function
@name uniqueid
@param bytes	Number of bytes for the unique id
@return		String containing hex encoded id
]]

---[[
Returns the current system uptime stats.

@class function
@name uptime
@return	String containing total uptime in seconds
]]

---[[
LuCI system utilities / network related functions.

@class	module
@name	luci.sys.net
]]

---[[
Returns a two-dimensional table of mac address hints.

@class function
@name net.mac_hints
@return  Table of table containing known hosts from various sources.
         Each entry contains the values in the following order:
         [ "mac", "name" ]
]]

---[[
Returns a two-dimensional table of IPv4 address hints.

@class function
@name net.ipv4_hints
@return  Table of table containing known hosts from various sources.
         Each entry contains the values in the following order:
         [ "ip", "name" ]
]]

---[[
Returns a two-dimensional table of IPv6 address hints.

@class function
@name net.ipv6_hints
@return  Table of table containing known hosts from various sources.
         Each entry contains the values in the following order:
         [ "ip", "name" ]
]]

---[[
Returns a two-dimensional table of host hints.

@class function
@name net.host_hints
@return  Table of table containing known hosts from various sources,
         indexed by mac address. Each subtable contains at least one
         of the fields "name", "ipv4" or "ipv6".
]]

---[[
Returns conntrack information

@class function
@name net.conntrack
@return	Table with the currently tracked IP connections
]]

---[[
Determine the names of available network interfaces.

@class function
@name net.devices
@return	Table containing all current interface names
]]

---[[
LuCI system utilities / process related functions.

@class	module
@name	luci.sys.process
]]

---[[
Get the current process id.

@class function
@name  process.info
@return	Number containing the current pid
]]

---[[
Retrieve information about currently running processes.

@class function
@name process.list
@return 	Table containing process information
]]

---[[
Set the gid of a process identified by given pid.

@class function
@name process.setgroup
@param gid	Number containing the Unix group id
@return		Boolean indicating successful operation
@return		String containing the error message if failed
@return		Number containing the error code if failed
]]

---[[
Set the uid of a process identified by given pid.

@class function
@name process.setuser
@param uid	Number containing the Unix user id
@return		Boolean indicating successful operation
@return		String containing the error message if failed
@return		Number containing the error code if failed
]]

---[[
Send a signal to a process identified by given pid.

@class function
@name  process.signal
@param pid	Number containing the process id
@param sig	Signal to send (default: 15 [SIGTERM])
@return		Boolean indicating successful operation
@return		Number containing the error code if failed
]]

---[[
Execute a process, optionally capturing stdio.

Executes the process specified by the given argv vector, e.g.
`{ "/bin/sh", "-c", "echo 1" }` and waits for it to terminate unless a true
value has been passed for the "nowait" parameter.

When a function value is passed for the stdout or stderr arguments, the passed
function is repeatedly called for each chunk read from the corresponding stdio
stream. The read data is passed as string containing at most 4096 bytes at a
time.

When a true, non-function value is passed for the stdout or stderr arguments,
the data of the corresponding stdio stream is read into an internal string
buffer and returned as "stdout" or "stderr" field respectively in the result
table.

When a true value is passed to the nowait parameter, the function does not
await process termination but returns as soon as all captured stdio streams
have been closed or - if no streams are captured - immediately after launching
the process.

@class function
@name  process.exec
@param commend	Table containing the argv vector to execute
@param stdout	Callback function or boolean to indicate capturing (optional)
@param stderr	Callback function or boolean to indicate capturing (optional)
@param nowait	Don't wait for process termination when true (optional)
@return		Table containing at least the fields "code" which holds the exit
            status of the invoked process or "-1" on error and "pid", which
            contains the process id assigned to the spawned process. When
            stdout and/or stderr capturing has been requested, it additionally
            contains "stdout" and "stderr" fields respectively, holding the
            captured stdio data as string.
]]

---[[
LuCI system utilities / user related functions.

@class	module
@name	luci.sys.user
]]

---[[
Retrieve user information for given uid.

@class		function
@name		getuser
@param uid	Number containing the Unix user id
@return		Table containing the following fields:
--				{ "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
]]

---[[
Retrieve the current user password hash.

@class function
@name user.getpasswd
@param username	String containing the username to retrieve the password for
@return			String containing the hash or nil if no password is set.
@return			Password database entry
]]

---[[
Test whether given string matches the password of a given system user.

@class function
@name user.checkpasswd
@param username	String containing the Unix user name
@param pass		String containing the password to compare
@return			Boolean indicating whether the passwords are equal
]]

---[[
Change the password of given user.

@class function
@name user.setpasswd
@param username	String containing the Unix user name
@param password	String containing the password to compare
@return			Number containing 0 on success and >= 1 on error
]]

---[[
LuCI system utilities / wifi related functions.

@class	module
@name	luci.sys.wifi
]]

---[[
Get wireless information for given interface.

@class function
@name wifi.getiwinfo
@param ifname        String containing the interface name
@return              A wrapped iwinfo object instance
]]

---[[
LuCI system utilities / init related functions.

@class	module
@name	luci.sys.init
]]

---[[
Get the names of all installed init scripts

@class function
@name init.names
@return	Table containing the names of all inistalled init scripts
]]

---[[
Get the index of he given init script

@class function
@name init.index
@param name	Name of the init script
@return		Numeric index value
]]

---[[
Test whether the given init script is enabled

@class function
@name init.enabled
@param name	Name of the init script
@return		Boolean indicating whether init is enabled
]]

---[[
Enable the given init script

@class function
@name init.enable
@param name	Name of the init script
@return		Boolean indicating success
]]

---[[
Disable the given init script

@class function
@name init.disable
@param name	Name of the init script
@return		Boolean indicating success
]]

---[[
Start the given init script

@class function
@name init.start
@param name	Name of the init script
@return		Boolean indicating success
]]

---[[
Stop the given init script

@class function
@name init.stop
@param name	Name of the init script
@return		Boolean indicating success
]]