Mercurial > hg > nginx-site
comparison xml/en/docs/njs/reference.xml @ 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 | 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>— | 3976 <literal>dirent.name</literal>— |
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> |