Merge pull request #1502 from dibdot/adblock
[project/luci.git] / modules / luci-base / luasrc / sys.luadoc
1 ---[[
2 LuCI Linux and POSIX system utilities.
3 ]]
4 module "luci.sys"
5
6 ---[[
7 Execute a given shell command and return the error code
8
9 @class          function
10 @name           call
11 @param          ...             Command to call
12 @return         Error code of the command
13 ]]
14
15 ---[[
16 Execute a given shell command and capture its standard output
17
18 @class          function
19 @name           exec
20 @param command  Command to call
21 @return                 String containg the return the output of the command
22 ]]
23
24 ---[[
25 Retrieve information about currently mounted file systems.
26
27 @class function
28 @name mounts
29 @return         Table containing mount information
30 ]]
31
32 ---[[
33 Retrieve environment variables. If no variable is given then a table
34
35 containing the whole environment is returned otherwise this function returns
36 the corresponding string value for the given name or nil if no such variable
37 exists.
38 @class          function
39 @name           getenv
40 @param var      Name of the environment variable to retrieve (optional)
41 @return         String containg the value of the specified variable
42 @return         Table containing all variables if no variable name is given
43 ]]
44
45 ---[[
46 Get or set the current hostname.
47
48 @class function
49 @name hostname
50 @param          String containing a new hostname to set (optional)
51 @return         String containing the system hostname
52 ]]
53
54 ---[[
55 Returns the contents of a documented referred by an URL.
56
57 @class function
58 @name httpget
59 @param url       The URL to retrieve
60 @param stream Return a stream instead of a buffer
61 @param target Directly write to target file name
62 @return         String containing the contents of given the URL
63 ]]
64
65 ---[[
66 Initiate a system reboot.
67
68 @class function
69 @name reboot
70 @return Return value of os.execute()
71 ]]
72
73 ---[[
74 Retrieves the output of the "logread" command.
75
76 @class function
77 @name syslog
78 @return String containing the current log buffer
79 ]]
80
81 ---[[
82 Retrieves the output of the "dmesg" command.
83
84 @class function
85 @name dmesg
86 @return String containing the current log buffer
87 ]]
88
89 ---[[
90 Generates a random id with specified length.
91
92 @class function
93 @name uniqueid
94 @param bytes    Number of bytes for the unique id
95 @return         String containing hex encoded id
96 ]]
97
98 ---[[
99 Returns the current system uptime stats.
100
101 @class function
102 @name uptime
103 @return String containing total uptime in seconds
104 ]]
105
106 ---[[
107 LuCI system utilities / network related functions.
108
109 @class  module
110 @name   luci.sys.net
111 ]]
112
113 ---[[
114 Returns the current arp-table entries as two-dimensional table.
115
116 @class function
117 @name net.arptable
118 @return Table of table containing the current arp entries.
119 --                      The following fields are defined for arp entry objects:
120 --                      { "IP address", "HW address", "HW type", "Flags", "Mask", "Device" }
121 ]]
122
123 ---[[
124 Returns a two-dimensional table of mac address hints.
125
126 @class function
127 @name net.mac_hints
128 @return  Table of table containing known hosts from various sources.
129          Each entry contains the values in the following order:
130          [ "mac", "name" ]
131 ]]
132
133 ---[[
134 Returns a two-dimensional table of IPv4 address hints.
135
136 @class function
137 @name net.ipv4_hints
138 @return  Table of table containing known hosts from various sources.
139          Each entry contains the values in the following order:
140          [ "ip", "name" ]
141 ]]
142
143 ---[[
144 Returns a two-dimensional table of IPv6 address hints.
145
146 @class function
147 @name net.ipv6_hints
148 @return  Table of table containing known hosts from various sources.
149          Each entry contains the values in the following order:
150          [ "ip", "name" ]
151 ]]
152
153 ---[[
154 Returns a two-dimensional table of host hints.
155
156 @class function
157 @name net.host_hints
158 @return  Table of table containing known hosts from various sources,
159          indexed by mac address. Each subtable contains at least one
160          of the fields "name", "ipv4" or "ipv6".
161 ]]
162
163 ---[[
164 Returns conntrack information
165
166 @class function
167 @name net.conntrack
168 @return Table with the currently tracked IP connections
169 ]]
170
171 ---[[
172 Determine the names of available network interfaces.
173
174 @class function
175 @name net.devices
176 @return Table containing all current interface names
177 ]]
178
179 ---[[
180 Return information about available network interfaces.
181
182 @class function
183 @name net.deviceinfo
184 @return Table containing all current interface names and their information
185 ]]
186
187 ---[[
188 Returns the current kernel routing table entries.
189
190 @class function
191 @name net.routes
192 @return Table of tables with properties of the corresponding routes.
193 --                      The following fields are defined for route entry tables:
194 --                      { "dest", "gateway", "metric", "refcount", "usecount", "irtt",
195 --                        "flags", "device" }
196 ]]
197
198 ---[[
199 Returns the current ipv6 kernel routing table entries.
200
201 @class function
202 @name net.routes6
203 @return Table of tables with properties of the corresponding routes.
204 --                      The following fields are defined for route entry tables:
205 --                      { "source", "dest", "nexthop", "metric", "refcount", "usecount",
206 --                        "flags", "device" }
207 ]]
208
209 ---[[
210 Tests whether the given host responds to ping probes.
211
212 @class function
213 @name net.pingtest
214 @param host     String containing a hostname or IPv4 address
215 @return         Number containing 0 on success and >= 1 on error
216 ]]
217
218 ---[[
219 LuCI system utilities / process related functions.
220
221 @class  module
222 @name   luci.sys.process
223 ]]
224
225 ---[[
226 Get the current process id.
227
228 @class function
229 @name  process.info
230 @return Number containing the current pid
231 ]]
232
233 ---[[
234 Retrieve information about currently running processes.
235
236 @class function
237 @name process.list
238 @return         Table containing process information
239 ]]
240
241 ---[[
242 Set the gid of a process identified by given pid.
243
244 @class function
245 @name process.setgroup
246 @param gid      Number containing the Unix group id
247 @return         Boolean indicating successful operation
248 @return         String containing the error message if failed
249 @return         Number containing the error code if failed
250 ]]
251
252 ---[[
253 Set the uid of a process identified by given pid.
254
255 @class function
256 @name process.setuser
257 @param uid      Number containing the Unix user id
258 @return         Boolean indicating successful operation
259 @return         String containing the error message if failed
260 @return         Number containing the error code if failed
261 ]]
262
263 ---[[
264 Send a signal to a process identified by given pid.
265
266 @class function
267 @name  process.signal
268 @param pid      Number containing the process id
269 @param sig      Signal to send (default: 15 [SIGTERM])
270 @return         Boolean indicating successful operation
271 @return         Number containing the error code if failed
272 ]]
273
274 ---[[
275 LuCI system utilities / user related functions.
276
277 @class  module
278 @name   luci.sys.user
279 ]]
280
281 ---[[
282 Retrieve user informations for given uid.
283
284 @class          function
285 @name           getuser
286 @param uid      Number containing the Unix user id
287 @return         Table containing the following fields:
288 --                              { "uid", "gid", "name", "passwd", "dir", "shell", "gecos" }
289 ]]
290
291 ---[[
292 Retrieve the current user password hash.
293
294 @class function
295 @name user.getpasswd
296 @param username String containing the username to retrieve the password for
297 @return                 String containing the hash or nil if no password is set.
298 @return                 Password database entry
299 ]]
300
301 ---[[
302 Test whether given string matches the password of a given system user.
303
304 @class function
305 @name user.checkpasswd
306 @param username String containing the Unix user name
307 @param pass             String containing the password to compare
308 @return                 Boolean indicating wheather the passwords are equal
309 ]]
310
311 ---[[
312 Change the password of given user.
313
314 @class function
315 @name user.setpasswd
316 @param username String containing the Unix user name
317 @param password String containing the password to compare
318 @return                 Number containing 0 on success and >= 1 on error
319 ]]
320
321 ---[[
322 LuCI system utilities / wifi related functions.
323
324 @class  module
325 @name   luci.sys.wifi
326 ]]
327
328 ---[[
329 Get wireless information for given interface.
330
331 @class function
332 @name wifi.getiwinfo
333 @param ifname        String containing the interface name
334 @return              A wrapped iwinfo object instance
335 ]]
336
337 ---[[
338 LuCI system utilities / init related functions.
339
340 @class  module
341 @name   luci.sys.init
342 ]]
343
344 ---[[
345 Get the names of all installed init scripts
346
347 @class function
348 @name init.names
349 @return Table containing the names of all inistalled init scripts
350 ]]
351
352 ---[[
353 Get the index of he given init script
354
355 @class function
356 @name init.index
357 @param name     Name of the init script
358 @return         Numeric index value
359 ]]
360
361 ---[[
362 Test whether the given init script is enabled
363
364 @class function
365 @name init.enabled
366 @param name     Name of the init script
367 @return         Boolean indicating whether init is enabled
368 ]]
369
370 ---[[
371 Enable the given init script
372
373 @class function
374 @name init.enable
375 @param name     Name of the init script
376 @return         Boolean indicating success
377 ]]
378
379 ---[[
380 Disable the given init script
381
382 @class function
383 @name init.disable
384 @param name     Name of the init script
385 @return         Boolean indicating success
386 ]]
387
388 ---[[
389 Start the given init script
390
391 @class function
392 @name init.start
393 @param name     Name of the init script
394 @return         Boolean indicating success
395 ]]
396
397 ---[[
398 Stop the given init script
399
400 @class function
401 @name init.stop
402 @param name     Name of the init script
403 @return         Boolean indicating success
404 ]]
405