changeset 2887:155c8745f596

Documented new fs methods and fs.FileHandle in njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 30 Aug 2022 21:00:58 +0100
parents 76fddfe7826d
children 88956e57f930
files xml/en/docs/njs/reference.xml
diffstat 1 files changed, 428 insertions(+), 4 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/njs/reference.xml
+++ b/xml/en/docs/njs/reference.xml
@@ -9,7 +9,7 @@
 <article name="Reference"
         link="/en/docs/njs/reference.html"
         lang="en"
-        rev="87">
+        rev="88">
 
 <section id="summary">
 
@@ -3462,9 +3462,9 @@ otherwise, the method will return undefi
 
 <tag-name><literal>mode</literal></tag-name>
 <tag-desc>
-by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>.
-The mode argument is an optional integer
-that specifies the accessibility checks to be performed.
+an optional integer
+that specifies the accessibility checks to be performed,
+by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>
 <example>
 try {
     fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
@@ -3504,6 +3504,15 @@ by default is <literal>a</literal>
 </list>
 </tag-desc>
 
+<tag-name id="fs_fstatsync"><literal>fstatSync(<value>fd</value>)</literal></tag-name>
+<tag-desc>
+Retrieves the <link id="fs_stats"><literal>fs.Stats</literal></link> object
+for the file descriptor
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+The <literal>fd</literal> parameter is an integer
+representing the file descriptor used by the method.
+</tag-desc>
+
 <tag-name id="fs_lstatsync"><literal>lstatSync(<value>path</value>[,
 <value>options</value>])</literal></tag-name>
 <tag-desc>
@@ -3543,6 +3552,97 @@ mode option, by default is <literal>0o77
 </list>
 </tag-desc>
 
+<tag-name id="fs_opensync"><literal>openSync(<value>path</value>[,
+<value>flags</value>[, <value>mode</value>]])</literal></tag-name>
+<tag-desc>
+Returns an integer
+representing the file descriptor for the opened file <literal>path</literal>
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+<list type="tag">
+
+<tag-name><literal>flags</literal></tag-name>
+<tag-desc>
+file system <link id="njs_api_fs_flags">flag</link>,
+by default is <literal>r</literal>
+</tag-desc>
+
+<tag-name><literal>mode</literal></tag-name>
+<tag-desc>
+mode option, by default is <literal>0o666</literal>
+</tag-desc>
+
+</list>
+</tag-desc>
+
+<tag-name id="fs_promises_open"><literal>promises.open(<value>path</value>[,
+<value>flags</value>[, <value>mode</value>]])</literal></tag-name>
+<tag-desc>
+Returns a <link id="fs_filehandle"><literal>FileHandle</literal></link> object
+representing the opened file <literal>path</literal>
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+<list type="tag">
+
+<tag-name><literal>flags</literal></tag-name>
+<tag-desc>
+file system <link id="njs_api_fs_flags">flag</link>,
+by default is <literal>r</literal>
+</tag-desc>
+
+<tag-name><literal>mode</literal></tag-name>
+<tag-desc>
+mode option, by default is <literal>0o666</literal>
+</tag-desc>
+
+</list>
+</tag-desc>
+
+<tag-name id="fs_readsync"><literal>readSync(<value>fd</value>,
+<value>buffer</value>, <value>offset</value>[,
+<value>length</value>[, <value>position</value>]])</literal></tag-name>
+<tag-desc>
+Reads the content of a file path using file descriptor <literal>fd</literal>,
+returns the number of bytes read
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+
+<list type="tag">
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+the <literal>buffer</literal> value can be a
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+
+<tag-name><literal>offset</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing
+the position in buffer to write the data to
+</tag-desc>
+
+<tag-name><literal>length</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing
+the number of bytes to read
+</tag-desc>
+
+<tag-name><literal>position</literal></tag-name>
+<tag-desc>
+specifies where to begin reading from in the file,
+the value can be
+<literal>integer</literal> or
+<literal>null</literal>,
+by default is <literal>null</literal>.
+If <literal>position</literal> is <literal>null</literal>,
+data will be read from the current file position,
+and the file position will be updated.
+If position is an <literal>integer</literal>,
+the file position will be unchanged
+</tag-desc>
+</list>
+
+</tag-desc>
+
 <tag-name id="fs_readdirsync"><literal>readdirSync(<value>path</value>[,
 <value>options</value>])</literal></tag-name>
 <tag-desc>
@@ -3684,6 +3784,95 @@ pointing to <literal>target</literal> us
 Relative targets are relative to the link’s parent directory.
 </tag-desc>
 
+<tag-name id="fs_writesync_buf"><literal>writeSync(<value>fd</value>,
+<value>buffer</value>, <value>offset</value>[,
+<value>length</value>[, <value>position</value>]])</literal></tag-name>
+<tag-desc>
+Writes a buffer to a file using file descriptor,
+returns the <literal>number</literal> of bytes written
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+
+<list type="tag">
+
+<tag-name><literal>fd</literal></tag-name>
+<tag-desc>
+an <literal>integer</literal> representing the file descriptor
+</tag-desc>
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+the <literal>buffer</literal> value can be a
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+
+<tag-name><literal>offset</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> that determines
+the part of the buffer to be written,
+by default <literal>0</literal>
+</tag-desc>
+
+<tag-name><literal>length</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> specifying the number of bytes to write,
+by default is an offset of
+<link id="buffer_bytelength">Buffer.byteLength</link>
+</tag-desc>
+
+<tag-name><literal>position</literal></tag-name>
+<tag-desc>
+refers to the offset from the beginning of the file
+where this data should be written,
+can be an
+<literal>integer</literal> or
+<literal>null</literal>,
+by default is <literal>null</literal>.
+See also
+<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>.
+</tag-desc>
+</list>
+
+</tag-desc>
+
+<tag-name id="fs_writesync_str"><literal>writeSync(<value>fd</value>,
+<value>string</value>[,
+<value>position</value>[,
+<value>encoding</value>]])</literal></tag-name>
+<tag-desc>
+Writes a <literal>string</literal> to a file
+using file descriptor <literal>fd</literal>,
+returns the <literal>number</literal> of bytes written
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+
+<list type="tag">
+
+<tag-name><literal>fd</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing a file descriptor
+</tag-desc>
+
+<tag-name><literal>position</literal></tag-name>
+<tag-desc>
+refers to the offset from the beginning of the file
+where this data should be written,
+can be an
+<literal>integer</literal> or
+<literal>null</literal>, by default is <literal>null</literal>.
+See also
+<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
+</tag-desc>
+
+<tag-name><literal>encoding</literal></tag-name>
+<tag-desc>
+is a <literal>string</literal>,
+by default is <literal>utf8</literal>
+</tag-desc>
+</list>
+
+</tag-desc>
+
 <tag-name id="fs_unlinksync"><literal>unlinkSync(<value>path</value>)</literal></tag-name>
 <tag-desc>
 Synchronously unlinks a file by <literal>path</literal>
@@ -3794,6 +3983,241 @@ the name of the file <literal>fs.Dirent<
 </section>
 
 
+<section id="fs_filehandle" name="fs.FileHandle">
+
+<para>
+The <literal>FileHandle</literal> object is an object wrapper
+for a numeric file descriptor
+(<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
+Instances of the <literal>FileHandle</literal> object are created by the
+<link id="fs_promises_open"><literal>fs.promises.open()</literal></link> method.
+If a <literal>FileHandle</literal> is not closed using the
+<link id="filehandle_close"><literal>filehandle.close()</literal></link> method,
+it will try to automatically close the file descriptor,
+helping to prevent memory leaks.
+Please do not rely on this behavior because it can be unreliable.
+Instead, always explicitly close a <literal>FileHandle</literal>.
+</para>
+
+<para>
+<list type="tag">
+
+<tag-name id="filehandle_close"><literal>filehandle.close()</literal></tag-name>
+<tag-desc>
+Closes the file handle after waiting for any pending operation on the handle
+to complete.
+Returns a <literal>promise</literal>, fulfills with undefined upon success.
+</tag-desc>
+
+<tag-name id="filehandle_fd"><literal>filehandle.fd</literal></tag-name>
+<tag-desc>
+The numeric file descriptor
+managed by the <literal>FileHandle</literal> object.
+</tag-desc>
+
+<tag-name id="filehandle_read"><literal>filehandle.read(<value>buffer</value>,
+<value>offset</value>[,
+<value>length</value>[,
+<value>position</value>]])</literal></tag-name>
+<tag-desc>
+Reads data from the file and stores that in the given buffer.
+
+<list type="tag">
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+a buffer that will be filled with the file data read,
+the value can be a
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+
+<tag-name><literal>offset</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal>
+representing the location in the buffer at which to start filling
+</tag-desc>
+
+<tag-name><literal>length</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal>
+representing the number of bytes to read
+</tag-desc>
+
+<tag-name><literal>position</literal></tag-name>
+<tag-desc>
+the location where to begin reading data from the file,
+the value can be
+<literal>integer</literal>,
+<literal>null</literal>.
+If <literal>null</literal>, data will be read from the current file position
+and the position will be updated.
+If position is an <literal>integer</literal>,
+the current file position will remain unchanged.
+</tag-desc>
+</list>
+
+Returns a <literal>Promise</literal> which fulfills upon success
+with an object with two properties:
+<list type="tag">
+
+<tag-name><literal>bytesRead</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing the number of bytes read
+</tag-desc>
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+is a reference to the passed argument in buffer, can be
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+</list>
+
+</tag-desc>
+
+<tag-name id="filehandle_stat"><literal>filehandle.stat()</literal></tag-name>
+<tag-desc>
+Fulfills with an
+<link id="fs_stats">fs.Stats</link> for the file,
+returns a <literal>promise</literal>.
+</tag-desc>
+
+<tag-name id="filehandle_write_buf"><literal>filehandle.write(<value>buffer</value>,
+<value>offset</value>[,
+<value>length</value>[,
+<value>position</value>]])</literal></tag-name>
+<tag-desc>
+Writes a buffer to the file.
+
+<list type="tag">
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+the <literal>buffer</literal> value can be a
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+
+<tag-name><literal>offset</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing
+the start position from within buffer where the data to write begins
+</tag-desc>
+
+<tag-name><literal>length</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing
+the number of bytes from buffer to write, by default
+is an offset of
+<link id="buffer_bytelength">Buffer.byteLength</link>
+</tag-desc>
+
+<tag-name><literal>position</literal></tag-name>
+<tag-desc>
+the offset from the beginning of the file
+where the data from buffer should be written,
+can be an
+<literal>integer</literal> or
+<literal>null</literal>,
+by default is <literal>null</literal>.
+If <literal>position</literal> is not a <literal>number</literal>,
+the data will be written at the current position.
+See the POSIX
+<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
+documentation for details.
+</tag-desc>
+</list>
+Returns a <literal>Promise</literal> which is resolved with an object
+containing two properties:
+<list type="tag">
+
+<tag-name><literal>bytesWritten</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing the number of bytes written
+</tag-desc>
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+a reference to the buffer written, can be a
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+</list>
+<para>
+<note>
+It is unsafe to use <literal>filehandle.write()</literal> multiple times
+on the same file without waiting for the promise to be resolved or rejected.
+</note>
+</para>
+
+</tag-desc>
+
+<tag-name id="filehandle_write_str"><literal>filehandle.write(<value>string</value>[,
+<value>position</value>[,
+<value>encoding</value>]])</literal></tag-name>
+<tag-desc>
+Writes a <literal>string</literal> to the file.
+
+<list type="tag">
+
+<tag-name><literal>position</literal></tag-name>
+<tag-desc>
+the offset from the beginning of the file
+where the data from buffer should be written,
+can be an
+<literal>integer</literal> or
+<literal>null</literal>,
+by default is <literal>null</literal>.
+If <literal>position</literal> is not a <literal>number</literal>,
+the data will be written at the current position.
+See the POSIX
+<link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
+documentation for details.
+</tag-desc>
+
+<tag-name><literal>encoding</literal></tag-name>
+<tag-desc>
+the expected encoding of the string, by default <literal>utf8</literal>
+</tag-desc>
+
+</list>
+Returns a <literal>Promise</literal> which is resolved with an object
+containing two properties:
+<list type="tag">
+
+<tag-name><literal>bytesWritten</literal></tag-name>
+<tag-desc>
+is an <literal>integer</literal> representing the number of bytes written
+</tag-desc>
+
+<tag-name><literal>buffer</literal></tag-name>
+<tag-desc>
+a reference to the buffer written, can be a
+<literal>Buffer</literal>,
+<literal>TypedArray</literal>, or
+<literal>DataView</literal>
+</tag-desc>
+</list>
+<para>
+<note>
+It is unsafe to use <literal>filehandle.write()</literal> multiple times
+on the same file without waiting for the promise to be resolved or rejected.
+</note>
+</para>
+
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+
 <section id="fs_stats" name="fs.Stats">
 
 <para>