Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2887:155c8745f596

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 ccd42f2b99fb
children 88956e57f930
comparison
equal deleted inserted replaced
2886:76fddfe7826d 2887:155c8745f596
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="87"> 12 rev="88">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
3460 otherwise, the method will return undefined. 3460 otherwise, the method will return undefined.
3461 <list type="tag"> 3461 <list type="tag">
3462 3462
3463 <tag-name><literal>mode</literal></tag-name> 3463 <tag-name><literal>mode</literal></tag-name>
3464 <tag-desc> 3464 <tag-desc>
3465 by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>. 3465 an optional integer
3466 The mode argument is an optional integer 3466 that specifies the accessibility checks to be performed,
3467 that specifies the accessibility checks to be performed. 3467 by default is <link id="access_const"><literal>fs.constants.F_OK</literal></link>
3468 <example> 3468 <example>
3469 try { 3469 try {
3470 fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK); 3470 fs.accessSync('/file/path', fs.constants.R_OK | fs.constants.W_OK);
3471 console.log('has access'); 3471 console.log('has access');
3472 } catch (e) { 3472 } catch (e) {
3502 </tag-desc> 3502 </tag-desc>
3503 3503
3504 </list> 3504 </list>
3505 </tag-desc> 3505 </tag-desc>
3506 3506
3507 <tag-name id="fs_fstatsync"><literal>fstatSync(<value>fd</value>)</literal></tag-name>
3508 <tag-desc>
3509 Retrieves the <link id="fs_stats"><literal>fs.Stats</literal></link> object
3510 for the file descriptor
3511 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3512 The <literal>fd</literal> parameter is an integer
3513 representing the file descriptor used by the method.
3514 </tag-desc>
3515
3507 <tag-name id="fs_lstatsync"><literal>lstatSync(<value>path</value>[, 3516 <tag-name id="fs_lstatsync"><literal>lstatSync(<value>path</value>[,
3508 <value>options</value>])</literal></tag-name> 3517 <value>options</value>])</literal></tag-name>
3509 <tag-desc> 3518 <tag-desc>
3510 Synchronously retrieves 3519 Synchronously retrieves
3511 the <link id="fs_stats"><literal>fs.Stats</literal></link> object 3520 the <link id="fs_stats"><literal>fs.Stats</literal></link> object
3539 <tag-desc> 3548 <tag-desc>
3540 mode option, by default is <literal>0o777</literal>. 3549 mode option, by default is <literal>0o777</literal>.
3541 </tag-desc> 3550 </tag-desc>
3542 3551
3543 </list> 3552 </list>
3553 </tag-desc>
3554
3555 <tag-name id="fs_opensync"><literal>openSync(<value>path</value>[,
3556 <value>flags</value>[, <value>mode</value>]])</literal></tag-name>
3557 <tag-desc>
3558 Returns an integer
3559 representing the file descriptor for the opened file <literal>path</literal>
3560 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3561 <list type="tag">
3562
3563 <tag-name><literal>flags</literal></tag-name>
3564 <tag-desc>
3565 file system <link id="njs_api_fs_flags">flag</link>,
3566 by default is <literal>r</literal>
3567 </tag-desc>
3568
3569 <tag-name><literal>mode</literal></tag-name>
3570 <tag-desc>
3571 mode option, by default is <literal>0o666</literal>
3572 </tag-desc>
3573
3574 </list>
3575 </tag-desc>
3576
3577 <tag-name id="fs_promises_open"><literal>promises.open(<value>path</value>[,
3578 <value>flags</value>[, <value>mode</value>]])</literal></tag-name>
3579 <tag-desc>
3580 Returns a <link id="fs_filehandle"><literal>FileHandle</literal></link> object
3581 representing the opened file <literal>path</literal>
3582 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3583 <list type="tag">
3584
3585 <tag-name><literal>flags</literal></tag-name>
3586 <tag-desc>
3587 file system <link id="njs_api_fs_flags">flag</link>,
3588 by default is <literal>r</literal>
3589 </tag-desc>
3590
3591 <tag-name><literal>mode</literal></tag-name>
3592 <tag-desc>
3593 mode option, by default is <literal>0o666</literal>
3594 </tag-desc>
3595
3596 </list>
3597 </tag-desc>
3598
3599 <tag-name id="fs_readsync"><literal>readSync(<value>fd</value>,
3600 <value>buffer</value>, <value>offset</value>[,
3601 <value>length</value>[, <value>position</value>]])</literal></tag-name>
3602 <tag-desc>
3603 Reads the content of a file path using file descriptor <literal>fd</literal>,
3604 returns the number of bytes read
3605 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3606
3607 <list type="tag">
3608
3609 <tag-name><literal>buffer</literal></tag-name>
3610 <tag-desc>
3611 the <literal>buffer</literal> value can be a
3612 <literal>Buffer</literal>,
3613 <literal>TypedArray</literal>, or
3614 <literal>DataView</literal>
3615 </tag-desc>
3616
3617 <tag-name><literal>offset</literal></tag-name>
3618 <tag-desc>
3619 is an <literal>integer</literal> representing
3620 the position in buffer to write the data to
3621 </tag-desc>
3622
3623 <tag-name><literal>length</literal></tag-name>
3624 <tag-desc>
3625 is an <literal>integer</literal> representing
3626 the number of bytes to read
3627 </tag-desc>
3628
3629 <tag-name><literal>position</literal></tag-name>
3630 <tag-desc>
3631 specifies where to begin reading from in the file,
3632 the value can be
3633 <literal>integer</literal> or
3634 <literal>null</literal>,
3635 by default is <literal>null</literal>.
3636 If <literal>position</literal> is <literal>null</literal>,
3637 data will be read from the current file position,
3638 and the file position will be updated.
3639 If position is an <literal>integer</literal>,
3640 the file position will be unchanged
3641 </tag-desc>
3642 </list>
3643
3544 </tag-desc> 3644 </tag-desc>
3545 3645
3546 <tag-name id="fs_readdirsync"><literal>readdirSync(<value>path</value>[, 3646 <tag-name id="fs_readdirsync"><literal>readdirSync(<value>path</value>[,
3547 <value>options</value>])</literal></tag-name> 3647 <value>options</value>])</literal></tag-name>
3548 <tag-desc> 3648 <tag-desc>
3682 <link url="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</link> 3782 <link url="http://man7.org/linux/man-pages/man2/symlink.2.html">symlink(2)</link>
3683 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>). 3783 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
3684 Relative targets are relative to the link’s parent directory. 3784 Relative targets are relative to the link’s parent directory.
3685 </tag-desc> 3785 </tag-desc>
3686 3786
3787 <tag-name id="fs_writesync_buf"><literal>writeSync(<value>fd</value>,
3788 <value>buffer</value>, <value>offset</value>[,
3789 <value>length</value>[, <value>position</value>]])</literal></tag-name>
3790 <tag-desc>
3791 Writes a buffer to a file using file descriptor,
3792 returns the <literal>number</literal> of bytes written
3793 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3794
3795 <list type="tag">
3796
3797 <tag-name><literal>fd</literal></tag-name>
3798 <tag-desc>
3799 an <literal>integer</literal> representing the file descriptor
3800 </tag-desc>
3801
3802 <tag-name><literal>buffer</literal></tag-name>
3803 <tag-desc>
3804 the <literal>buffer</literal> value can be a
3805 <literal>Buffer</literal>,
3806 <literal>TypedArray</literal>, or
3807 <literal>DataView</literal>
3808 </tag-desc>
3809
3810 <tag-name><literal>offset</literal></tag-name>
3811 <tag-desc>
3812 is an <literal>integer</literal> that determines
3813 the part of the buffer to be written,
3814 by default <literal>0</literal>
3815 </tag-desc>
3816
3817 <tag-name><literal>length</literal></tag-name>
3818 <tag-desc>
3819 is an <literal>integer</literal> specifying the number of bytes to write,
3820 by default is an offset of
3821 <link id="buffer_bytelength">Buffer.byteLength</link>
3822 </tag-desc>
3823
3824 <tag-name><literal>position</literal></tag-name>
3825 <tag-desc>
3826 refers to the offset from the beginning of the file
3827 where this data should be written,
3828 can be an
3829 <literal>integer</literal> or
3830 <literal>null</literal>,
3831 by default is <literal>null</literal>.
3832 See also
3833 <link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>.
3834 </tag-desc>
3835 </list>
3836
3837 </tag-desc>
3838
3839 <tag-name id="fs_writesync_str"><literal>writeSync(<value>fd</value>,
3840 <value>string</value>[,
3841 <value>position</value>[,
3842 <value>encoding</value>]])</literal></tag-name>
3843 <tag-desc>
3844 Writes a <literal>string</literal> to a file
3845 using file descriptor <literal>fd</literal>,
3846 returns the <literal>number</literal> of bytes written
3847 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3848
3849 <list type="tag">
3850
3851 <tag-name><literal>fd</literal></tag-name>
3852 <tag-desc>
3853 is an <literal>integer</literal> representing a file descriptor
3854 </tag-desc>
3855
3856 <tag-name><literal>position</literal></tag-name>
3857 <tag-desc>
3858 refers to the offset from the beginning of the file
3859 where this data should be written,
3860 can be an
3861 <literal>integer</literal> or
3862 <literal>null</literal>, by default is <literal>null</literal>.
3863 See also
3864 <link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
3865 </tag-desc>
3866
3867 <tag-name><literal>encoding</literal></tag-name>
3868 <tag-desc>
3869 is a <literal>string</literal>,
3870 by default is <literal>utf8</literal>
3871 </tag-desc>
3872 </list>
3873
3874 </tag-desc>
3875
3687 <tag-name id="fs_unlinksync"><literal>unlinkSync(<value>path</value>)</literal></tag-name> 3876 <tag-name id="fs_unlinksync"><literal>unlinkSync(<value>path</value>)</literal></tag-name>
3688 <tag-desc> 3877 <tag-desc>
3689 Synchronously unlinks a file by <literal>path</literal> 3878 Synchronously unlinks a file by <literal>path</literal>
3690 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>). 3879 (<link doc="changes.xml" id="njs0.3.9">0.3.9</link>).
3691 </tag-desc> 3880 </tag-desc>
3785 3974
3786 <listitem> 3975 <listitem>
3787 <literal>dirent.name</literal>&mdash; 3976 <literal>dirent.name</literal>&mdash;
3788 the name of the file <literal>fs.Dirent</literal> object refers to. 3977 the name of the file <literal>fs.Dirent</literal> object refers to.
3789 </listitem> 3978 </listitem>
3979
3980 </list>
3981 </para>
3982
3983 </section>
3984
3985
3986 <section id="fs_filehandle" name="fs.FileHandle">
3987
3988 <para>
3989 The <literal>FileHandle</literal> object is an object wrapper
3990 for a numeric file descriptor
3991 (<link doc="changes.xml" id="njs0.7.7">0.7.7</link>).
3992 Instances of the <literal>FileHandle</literal> object are created by the
3993 <link id="fs_promises_open"><literal>fs.promises.open()</literal></link> method.
3994 If a <literal>FileHandle</literal> is not closed using the
3995 <link id="filehandle_close"><literal>filehandle.close()</literal></link> method,
3996 it will try to automatically close the file descriptor,
3997 helping to prevent memory leaks.
3998 Please do not rely on this behavior because it can be unreliable.
3999 Instead, always explicitly close a <literal>FileHandle</literal>.
4000 </para>
4001
4002 <para>
4003 <list type="tag">
4004
4005 <tag-name id="filehandle_close"><literal>filehandle.close()</literal></tag-name>
4006 <tag-desc>
4007 Closes the file handle after waiting for any pending operation on the handle
4008 to complete.
4009 Returns a <literal>promise</literal>, fulfills with undefined upon success.
4010 </tag-desc>
4011
4012 <tag-name id="filehandle_fd"><literal>filehandle.fd</literal></tag-name>
4013 <tag-desc>
4014 The numeric file descriptor
4015 managed by the <literal>FileHandle</literal> object.
4016 </tag-desc>
4017
4018 <tag-name id="filehandle_read"><literal>filehandle.read(<value>buffer</value>,
4019 <value>offset</value>[,
4020 <value>length</value>[,
4021 <value>position</value>]])</literal></tag-name>
4022 <tag-desc>
4023 Reads data from the file and stores that in the given buffer.
4024
4025 <list type="tag">
4026
4027 <tag-name><literal>buffer</literal></tag-name>
4028 <tag-desc>
4029 a buffer that will be filled with the file data read,
4030 the value can be a
4031 <literal>Buffer</literal>,
4032 <literal>TypedArray</literal>, or
4033 <literal>DataView</literal>
4034 </tag-desc>
4035
4036 <tag-name><literal>offset</literal></tag-name>
4037 <tag-desc>
4038 is an <literal>integer</literal>
4039 representing the location in the buffer at which to start filling
4040 </tag-desc>
4041
4042 <tag-name><literal>length</literal></tag-name>
4043 <tag-desc>
4044 is an <literal>integer</literal>
4045 representing the number of bytes to read
4046 </tag-desc>
4047
4048 <tag-name><literal>position</literal></tag-name>
4049 <tag-desc>
4050 the location where to begin reading data from the file,
4051 the value can be
4052 <literal>integer</literal>,
4053 <literal>null</literal>.
4054 If <literal>null</literal>, data will be read from the current file position
4055 and the position will be updated.
4056 If position is an <literal>integer</literal>,
4057 the current file position will remain unchanged.
4058 </tag-desc>
4059 </list>
4060
4061 Returns a <literal>Promise</literal> which fulfills upon success
4062 with an object with two properties:
4063 <list type="tag">
4064
4065 <tag-name><literal>bytesRead</literal></tag-name>
4066 <tag-desc>
4067 is an <literal>integer</literal> representing the number of bytes read
4068 </tag-desc>
4069
4070 <tag-name><literal>buffer</literal></tag-name>
4071 <tag-desc>
4072 is a reference to the passed argument in buffer, can be
4073 <literal>Buffer</literal>,
4074 <literal>TypedArray</literal>, or
4075 <literal>DataView</literal>
4076 </tag-desc>
4077 </list>
4078
4079 </tag-desc>
4080
4081 <tag-name id="filehandle_stat"><literal>filehandle.stat()</literal></tag-name>
4082 <tag-desc>
4083 Fulfills with an
4084 <link id="fs_stats">fs.Stats</link> for the file,
4085 returns a <literal>promise</literal>.
4086 </tag-desc>
4087
4088 <tag-name id="filehandle_write_buf"><literal>filehandle.write(<value>buffer</value>,
4089 <value>offset</value>[,
4090 <value>length</value>[,
4091 <value>position</value>]])</literal></tag-name>
4092 <tag-desc>
4093 Writes a buffer to the file.
4094
4095 <list type="tag">
4096
4097 <tag-name><literal>buffer</literal></tag-name>
4098 <tag-desc>
4099 the <literal>buffer</literal> value can be a
4100 <literal>Buffer</literal>,
4101 <literal>TypedArray</literal>, or
4102 <literal>DataView</literal>
4103 </tag-desc>
4104
4105 <tag-name><literal>offset</literal></tag-name>
4106 <tag-desc>
4107 is an <literal>integer</literal> representing
4108 the start position from within buffer where the data to write begins
4109 </tag-desc>
4110
4111 <tag-name><literal>length</literal></tag-name>
4112 <tag-desc>
4113 is an <literal>integer</literal> representing
4114 the number of bytes from buffer to write, by default
4115 is an offset of
4116 <link id="buffer_bytelength">Buffer.byteLength</link>
4117 </tag-desc>
4118
4119 <tag-name><literal>position</literal></tag-name>
4120 <tag-desc>
4121 the offset from the beginning of the file
4122 where the data from buffer should be written,
4123 can be an
4124 <literal>integer</literal> or
4125 <literal>null</literal>,
4126 by default is <literal>null</literal>.
4127 If <literal>position</literal> is not a <literal>number</literal>,
4128 the data will be written at the current position.
4129 See the POSIX
4130 <link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
4131 documentation for details.
4132 </tag-desc>
4133 </list>
4134 Returns a <literal>Promise</literal> which is resolved with an object
4135 containing two properties:
4136 <list type="tag">
4137
4138 <tag-name><literal>bytesWritten</literal></tag-name>
4139 <tag-desc>
4140 is an <literal>integer</literal> representing the number of bytes written
4141 </tag-desc>
4142
4143 <tag-name><literal>buffer</literal></tag-name>
4144 <tag-desc>
4145 a reference to the buffer written, can be a
4146 <literal>Buffer</literal>,
4147 <literal>TypedArray</literal>, or
4148 <literal>DataView</literal>
4149 </tag-desc>
4150 </list>
4151 <para>
4152 <note>
4153 It is unsafe to use <literal>filehandle.write()</literal> multiple times
4154 on the same file without waiting for the promise to be resolved or rejected.
4155 </note>
4156 </para>
4157
4158 </tag-desc>
4159
4160 <tag-name id="filehandle_write_str"><literal>filehandle.write(<value>string</value>[,
4161 <value>position</value>[,
4162 <value>encoding</value>]])</literal></tag-name>
4163 <tag-desc>
4164 Writes a <literal>string</literal> to the file.
4165
4166 <list type="tag">
4167
4168 <tag-name><literal>position</literal></tag-name>
4169 <tag-desc>
4170 the offset from the beginning of the file
4171 where the data from buffer should be written,
4172 can be an
4173 <literal>integer</literal> or
4174 <literal>null</literal>,
4175 by default is <literal>null</literal>.
4176 If <literal>position</literal> is not a <literal>number</literal>,
4177 the data will be written at the current position.
4178 See the POSIX
4179 <link url="https://man7.org/linux/man-pages/man2/write.2.html">pwrite(2)</link>
4180 documentation for details.
4181 </tag-desc>
4182
4183 <tag-name><literal>encoding</literal></tag-name>
4184 <tag-desc>
4185 the expected encoding of the string, by default <literal>utf8</literal>
4186 </tag-desc>
4187
4188 </list>
4189 Returns a <literal>Promise</literal> which is resolved with an object
4190 containing two properties:
4191 <list type="tag">
4192
4193 <tag-name><literal>bytesWritten</literal></tag-name>
4194 <tag-desc>
4195 is an <literal>integer</literal> representing the number of bytes written
4196 </tag-desc>
4197
4198 <tag-name><literal>buffer</literal></tag-name>
4199 <tag-desc>
4200 a reference to the buffer written, can be a
4201 <literal>Buffer</literal>,
4202 <literal>TypedArray</literal>, or
4203 <literal>DataView</literal>
4204 </tag-desc>
4205 </list>
4206 <para>
4207 <note>
4208 It is unsafe to use <literal>filehandle.write()</literal> multiple times
4209 on the same file without waiting for the promise to be resolved or rejected.
4210 </note>
4211 </para>
4212
4213 </tag-desc>
3790 4214
3791 </list> 4215 </list>
3792 </para> 4216 </para>
3793 4217
3794 </section> 4218 </section>