# 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` | string | 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` | string | 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(The){Promise.<number>}

fs.js, line 239

  Unlink the given file.

  Name | Type | Description
  --- | --- | ---
  `The` | string | 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