Class: fs

LuCI. fs

Provides high level utilities to wrap file system related RPC calls. To import the class in views, use 'require fs', to import it in external JavaScript, use L.require("fs").then(...).

new LuCI.fs()

fs.js, line 147

Methods

exec(command, params, env){Promise.<LuCI.fs.FileExecResult>}

fs.js, line 268

Execute the specified command, optionally passing params and environment variables.

Note: The command must be either the path to an executable, or a basename without arguments in which case it will be searched in $PATH. If specified, the values given in params will be passed as arguments to the command.

The key/value pairs in the optional env table are translated to setenv() calls prior to running the command.

Name Type Description
command string

The command to invoke.
params Array.<string> optional

The arguments to pass to the command.
env Object.<string, string> optional

Environment variables to set.
Returns:
Type Description
Promise.<LuCI.fs.FileExecResult> Returns a promise resolving to an object describing the execution results or rejecting with an error stating the failure reason.

exec_direct(command, params, type, latin1){Promise.<*>}

fs.js, line 405

Execute the specified command, bypassing ubus.

Note: The command must be either the path to an executable, or a basename without arguments in which case it will be searched in $PATH. If specified, the values given in params will be passed as arguments to the command.

This function will invoke the requested commands through the cgi-io helper applet at /cgi-bin/cgi-exec which bypasses the ubus rpc transport. This is useful to fetch large command outputs which might exceed the ubus message size limits or which contain binary data.

The cgi-io helper will enforce the same access permission rules as the ubus based exec call.

Name Type Default Description
command string

The command to invoke.
params Array.<string> optional

The arguments to pass to the command.
type "blob" | "text" | "json" text optional

The expected output type of the invoked program. Valid values are text to interpret the output as string, json to parse the output as JSON or blob to return the output as Blob instance.
latin1 boolean false optional

Whether to encode the command line as Latin1 instead of UTF-8. This is usually not needed but can be useful for programs that cannot handle UTF-8 input.
Returns:
Type Description
Promise.<*> Returns a promise resolving with the command stdout output interpreted according to the specified type or rejecting with an error stating the failure reason.

lines(path){Promise.<Array.<string>>}

fs.js, line 317

Read the contents of the given file, split it into lines, trim leading and trailing white space of each line and return the resulting array.

This function is guaranteed to not reject its promises, on failure, an empty array will be returned.

Name Type Description
path string

The file path to read.
Returns:
Type Description
Promise.<Array.<string>> Returns a promise resolving to an array containing the stripped lines of the given file or [] on failure.

list(path){Promise.<Array.<LuCI.fs.FileStatEntry>>}

fs.js, line 168

Obtains a listing of the specified directory.

Name Type Description
path string

The directory path to list.
Returns:
Type Description
Promise.<Array.<LuCI.fs.FileStatEntry>> Returns a promise resolving to an array of stat detail objects or rejecting with an error stating the failure reason.

read(path){Promise.<string>}

fs.js, line 197

Read the contents of the given file and return them. Note: this function is unsuitable for obtaining binary data.

Name Type Description
path string

The file path to read.
Returns:
Type Description
Promise.<string> Returns a promise resolving to a string containing the file contents or rejecting with an error stating the failure reason.

read_direct(path, type){Promise.<*>}

fs.js, line 358

Read the contents of the given file and return them, bypassing ubus.

This function will read the requested file through the cgi-io helper applet at /cgi-bin/cgi-download which bypasses the ubus rpc transport. This is useful to fetch large file contents which might exceed the ubus message size limits or which contain binary data.

The cgi-io helper will enforce the same access permission rules as the ubus based read call.

Name Type Default Description
path string

The file path to read.
type "blob" | "text" | "json" text optional

The expected type of read file contents. Valid values are text to interpret the contents as string, json to parse the contents as JSON or blob to return the contents as Blob instance.
Returns:
Type Description
Promise.<*> Returns a promise resolving with the file contents interpreted according to the specified type or rejecting with an error stating the failure reason.

remove(path){Promise.<number>}

fs.js, line 239

Unlink the given file.

Name Type Description
path string

The file path to remove.
Returns:
Type Description
Promise.<number> Returns a promise resolving to 0 or rejecting with an error stating the failure reason.

stat(path){Promise.<LuCI.fs.FileStatEntry>}

fs.js, line 182

Return file stat information on the specified path.

Name Type Description
path string

The filesystem path to stat.
Returns:
Type Description
Promise.<LuCI.fs.FileStatEntry> Returns a promise resolving to a stat detail object or rejecting with an error stating the failure reason.

trimmed(path){Promise.<string>}

fs.js, line 296

Read the contents of the given file, trim leading and trailing white space and return the trimmed result. In case of errors, return an empty string instead.

Note: this function is useful to read single-value files in /sys or /proc.

This function is guaranteed to not reject its promises, on failure, an empty string will be returned.

Name Type Description
path string

The file path to read.
Returns:
Type Description
Promise.<string> Returns a promise resolving to the file contents or the empty string on failure.

write(path, data, mode){Promise.<number>}

fs.js, line 223

Write the given data to the specified file path. If the specified file path does not exist, it will be created, given sufficient permissions.

Note: data will be converted to a string using String(data) or to '' when it is null.

Name Type Description
path string

The file path to write to.
data * optional

The file data to write. If it is null, it will be set to an empty string.
mode number optional

The permissions to use on file creation. Default is 420 (0644).
Returns:
Type Description
Promise.<number> Returns a promise resolving to 0 or rejecting with an error stating the failure reason.

Type Definitions

LuCI.fs.FileExecResultObject

Properties:
Name Type Argument Description
code number

The exit code of the invoked command
stdout string <optional>

The stdout produced by the command, if any
stderr string <optional>

The stderr produced by the command, if any

LuCI.fs.FileStatEntryObject

Properties:
Name Type Description
name string

Name of the directory entry
type string

Type of the entry, one of block, char, directory, fifo, symlink, file, socket or unknown
size number

Size in bytes
mode number

Access permissions
atime number

Last access time in seconds since epoch
mtime number

Last modification time in seconds since epoch
ctime number

Last change time in seconds since epoch
inode number

Inode number
uid number

Numeric owner id
gid number

Numeric group id