Difuse/luci
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
luci/documentation/jsapi/LuCI.fs.html

2143 lines
27 KiB
HTML
Raw Normal View History

documentation: add JS api docs Signed-off-by: Jo-Philipp Wich <jo@mein.io> (cherry picked from commit d9452d1157aef6b8752fac0f4ed1e0b9221abb31)
2019-11-05 08:33:40 +00:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Class: fs</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Class: fs</h1>
<section>
<header>
<h2><span class="attribs"><span class="type-signature"></span></span>
<span class="ancestors"><a href="LuCI.html">LuCI</a>.</span>fs</h2>
<div class="class-description"><p>Provides high level utilities to wrap file system related RPC calls.
To import the class in views, use <code>'require fs'</code>, to import it in
external JavaScript, use <code>L.require(&quot;fs&quot;).then(...)</code>.</p></div>
</header>
<article>
<div class="container-overview">
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line111">line 111</a>
</li></ul></dd>
</dl>
</div>
<h3 class="subsection-title">Methods</h3>
<h4 class="name" id="exec"><span class="type-signature"></span>exec<span class="signature">(command, params<span class="signature-attributes">opt</span>, env<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise.&lt;<a href="LuCI.fs.html#.FileExecResult">LuCI.fs.FileExecResult</a>>}</span></h4>
<div class="description">
<p>Execute the specified command, optionally passing params and
environment variables.</p>
<p>Note: The <code>command</code> 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 <code>params</code> will be passed
as arguments to the command.</p>
<p>The key/value pairs in the optional <code>env</code> table are translated to
<code>setenv()</code> calls prior to running the command.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>command</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"><p>The command to invoke.</p></td>
</tr>
<tr>
<td class="name"><code>params</code></td>
<td class="type">
<span class="param-type">Array.&lt;string></span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="description last"><p>The arguments to pass to the command.</p></td>
</tr>
<tr>
<td class="name"><code>env</code></td>
<td class="type">
<span class="param-type">Object.&lt;string, string></span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="description last"><p>Environment variables to set.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line232">line 232</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to an object describing the execution
results or rejecting with an error stating the failure reason.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;<a href="LuCI.fs.html#.FileExecResult">LuCI.fs.FileExecResult</a>></span>
</dd>
</dl>
<h4 class="name" id="lines"><span class="type-signature"></span>lines<span class="signature">(path)</span><span class="type-signature"> &rarr; {Promise.&lt;Array.&lt;string>>}</span></h4>
<div class="description">
<p>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.</p>
<p>This function is guaranteed to not reject its promises, on failure,
an empty array will be returned.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The file path to read.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line281">line 281</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to an array containing the stripped lines
of the given file or <code>[]</code> on failure.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;Array.&lt;string>></span>
</dd>
</dl>
<h4 class="name" id="list"><span class="type-signature"></span>list<span class="signature">(path)</span><span class="type-signature"> &rarr; {Promise.&lt;Array.&lt;<a href="LuCI.fs.html#.FileStatEntry">LuCI.fs.FileStatEntry</a>>>}</span></h4>
<div class="description">
<p>Obtains a listing of the specified directory.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The directory path to list.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line132">line 132</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to an array of stat detail objects or
rejecting with an error stating the failure reason.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;Array.&lt;<a href="LuCI.fs.html#.FileStatEntry">LuCI.fs.FileStatEntry</a>>></span>
</dd>
</dl>
<h4 class="name" id="read"><span class="type-signature"></span>read<span class="signature">(path)</span><span class="type-signature"> &rarr; {Promise.&lt;string>}</span></h4>
<div class="description">
<p>Read the contents of the given file and return them.
Note: this function is unsuitable for obtaining binary data.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The file path to read.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line161">line 161</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to a string containing the file contents or
rejecting with an error stating the failure reason.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;string></span>
</dd>
</dl>
<h4 class="name" id="remove"><span class="type-signature"></span>remove<span class="signature">(The)</span><span class="type-signature"> &rarr; {Promise.&lt;number>}</span></h4>
<div class="description">
<p>Unlink the given file.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>The</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>file path to remove.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line203">line 203</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to <code>0</code> or rejecting with an error stating
the failure reason.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;number></span>
</dd>
</dl>
<h4 class="name" id="stat"><span class="type-signature"></span>stat<span class="signature">(path)</span><span class="type-signature"> &rarr; {Promise.&lt;<a href="LuCI.fs.html#.FileStatEntry">LuCI.fs.FileStatEntry</a>>}</span></h4>
<div class="description">
<p>Return file stat information on the specified path.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The filesystem path to stat.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line146">line 146</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to a stat detail object or
rejecting with an error stating the failure reason.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;<a href="LuCI.fs.html#.FileStatEntry">LuCI.fs.FileStatEntry</a>></span>
</dd>
</dl>
<h4 class="name" id="trimmed"><span class="type-signature"></span>trimmed<span class="signature">(path)</span><span class="type-signature"> &rarr; {Promise.&lt;string>}</span></h4>
<div class="description">
<p>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.</p>
<p>Note: this function is useful to read single-value files in <code>/sys</code>
or <code>/proc</code>.</p>
<p>This function is guaranteed to not reject its promises, on failure,
an empty string will be returned.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>The file path to read.</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line260">line 260</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to the file contents or the empty string
on failure.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;string></span>
</dd>
</dl>
<h4 class="name" id="write"><span class="type-signature"></span>write<span class="signature">(path, data<span class="signature-attributes">opt</span>, mode<span class="signature-attributes">opt</span>)</span><span class="type-signature"> &rarr; {Promise.&lt;number>}</span></h4>
<div class="description">
<p>Write the given data to the specified file path.
If the specified file path does not exist, it will be created, given
sufficient permissions.</p>
<p>Note: <code>data</code> will be converted to a string using <code>String(data)</code> or to
<code>''</code> when it is <code>null</code>.</p>
</div>
<h5>Parameters:</h5>
<table class="params">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>path</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
</td>
<td class="description last"><p>The file path to write to.</p></td>
</tr>
<tr>
<td class="name"><code>data</code></td>
<td class="type">
<span class="param-type">*</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="description last"><p>The file data to write. If it is null, it will be set to an empty
string.</p></td>
</tr>
<tr>
<td class="name"><code>mode</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="description last"><p>The permissions to use on file creation. Default is 420 (0644).</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line187">line 187</a>
</li></ul></dd>
</dl>
<h5>Returns:</h5>
<div class="param-desc">
<p>Returns a promise resolving to <code>0</code> or rejecting with an error stating
the failure reason.</p>
</div>
<dl>
<dt>
Type
</dt>
<dd>
<span class="param-type">Promise.&lt;number></span>
</dd>
</dl>
<h3 class="subsection-title">Type Definitions</h3>
<h4 class="name" id=".FileExecResult">FileExecResult</h4>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Attributes</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>code</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="attributes">
</td>
<td class="description last"><p>The exit code of the invoked command</p></td>
</tr>
<tr>
<td class="name"><code>stdout</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="description last"><p>The stdout produced by the command, if any</p></td>
</tr>
<tr>
<td class="name"><code>stderr</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="attributes">
&lt;optional><br>
</td>
<td class="description last"><p>The stderr produced by the command, if any</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line20">line 20</a>
</li></ul></dd>
</dl>
<h4 class="name" id=".FileStatEntry">FileStatEntry</h4>
<h5>Type:</h5>
<ul>
<li>
<span class="param-type">Object</span>
</li>
</ul>
<h5 class="subsection-title">Properties:</h5>
<table class="props">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th class="last">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="name"><code>name</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>Name of the directory entry</p></td>
</tr>
<tr>
<td class="name"><code>type</code></td>
<td class="type">
<span class="param-type">string</span>
</td>
<td class="description last"><p>Type of the entry, one of <code>block</code>, <code>char</code>, <code>directory</code>, <code>fifo</code>, <code>symlink</code>, <code>file</code>, <code>socket</code> or <code>unknown</code></p></td>
</tr>
<tr>
<td class="name"><code>size</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Size in bytes</p></td>
</tr>
<tr>
<td class="name"><code>mode</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Access permissions</p></td>
</tr>
<tr>
<td class="name"><code>atime</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Last access time in seconds since epoch</p></td>
</tr>
<tr>
<td class="name"><code>mtime</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Last modification time in seconds since epoch</p></td>
</tr>
<tr>
<td class="name"><code>ctime</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Last change time in seconds since epoch</p></td>
</tr>
<tr>
<td class="name"><code>inode</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Inode number</p></td>
</tr>
<tr>
<td class="name"><code>uid</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Numeric owner id</p></td>
</tr>
<tr>
<td class="name"><code>gid</code></td>
<td class="type">
<span class="param-type">number</span>
</td>
<td class="description last"><p>Numeric group id</p></td>
</tr>
</tbody>
</table>
<dl class="details">
<dt class="tag-source">Source:</dt>
<dd class="tag-source"><ul class="dummy"><li>
<a href="fs.js.html">fs.js</a>, <a href="fs.js.html#line4">line 4</a>
</li></ul></dd>
</dl>
</article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="LuCI.html">LuCI</a></li><li><a href="LuCI.Class.html">Class</a></li><li><a href="LuCI.dom.html">dom</a></li><li><a href="LuCI.fs.html">fs</a></li><li><a href="LuCI.Headers.html">Headers</a></li><li><a href="LuCI.Network.html">Network</a></li><li><a href="LuCI.Network.Device.html">Device</a></li><li><a href="LuCI.Network.Hosts.html">Hosts</a></li><li><a href="LuCI.Network.Protocol.html">Protocol</a></li><li><a href="LuCI.Network.WifiDevice.html">WifiDevice</a></li><li><a href="LuCI.Network.WifiNetwork.html">WifiNetwork</a></li><li><a href="LuCI.Poll.html">Poll</a></li><li><a href="LuCI.Request.html">Request</a></li><li><a href="LuCI.Request.poll.html">poll</a></li><li><a href="LuCI.Response.html">Response</a></li><li><a href="LuCI.rpc.html">rpc</a></li><li><a href="LuCI.uci.html">uci</a></li><li><a href="LuCI.view.html">view</a></li><li><a href="LuCI.XHR.html">XHR</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 3.6.3</a> on Tue Nov 05 2019 09:33:05 GMT+0100 (Central European Standard Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>
Reference in a new issue Copy permalink