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 the current arp-table entries as two-dimensional table.

@class function
@name net.arptable
@return	Table of table containing the current arp entries.
--			The following fields are defined for arp entry objects:
--			{ "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
]]

---[[
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
]]

---[[
Return information about available network interfaces.

@class function
@name net.deviceinfo
@return	Table containing all current interface names and their information
]]

---[[
Returns the current kernel routing table entries.

@class function
@name net.routes
@return	Table of tables with properties of the corresponding routes.
--			The following fields are defined for route entry tables:
--			{ "dest", "gateway", "metric", "refcount", "usecount", "irtt",
--			  "flags", "device" }
]]

---[[
Returns the current ipv6 kernel routing table entries.

@class function
@name net.routes6
@return	Table of tables with properties of the corresponding routes.
--			The following fields are defined for route entry tables:
--			{ "source", "dest", "nexthop", "metric", "refcount", "usecount",
--			  "flags", "device" }
]]

---[[
Tests whether the given host responds to ping probes.

@class function
@name net.pingtest
@param host	String containing a hostname or IPv4 address
@return		Number containing 0 on success and >= 1 on error
]]

---[[
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
]]

---[[
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
]]