> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
This module provides common file storage functions. It provides the following JavaScript I/O APIs, including:
- Basic APIs for file management
- Basic APIs for directory management
- Statistical APIs for obtaining file information
- Stream APIs for reading and writing files
## Modules to Import
```js
...
...
@@ -10,11 +17,6 @@ import fileio from '@ohos.fileio';
```
## Required Permissions
None
## Guidelines
Before using this module to perform operations on a file or directory, obtain the absolute path of the file or directory. For details, see [getOrCreateLocalDir of the Context module](js-apis-Context.md).
...
...
@@ -40,21 +42,23 @@ let fd = fileio.openSync(path);
stat(path: string): Promise<Stat>
Asynchronously obtains file information. This method uses a promise to return the result.
Asynchronously obtains file information. This API uses a promise to return the result.
| path | string | Yes | Absolute path of the target file. |
| mode | number | No | Options for accessing the file. You can specify multiple options, separated with a bitwise OR operator (|). The default value is **0**.<br>The options are as follows:<br>- **0**: check whether the file exists.<br>- **1**: check whether the current process has the execute permission on the file.<br>- **2**: check whether the current process has the write permission on the file.<br>- **4**: check whether the current process has the read permission on the file.|
| path | string | Yes | Absolute path of the target file. |
| mode | number | No | Options for accessing the file. You can specify multiple options, separated with a bitwise OR operator (|). The default value is **0**.<br>The options are as follows:<br>- **0**: check whether the file exists.<br>- **1**: check whether the current process has the execute permission on the file.<br>- **2**: check whether the current process has the write permission on the file.<br>- **4**: check whether the current process has the read permission on the file.|
| callback | AsyncCallback<void> | Yes | Callback invoked when the file is asynchronously checked. |
- Example
**Example**
```js
fileio.access(path,function(err){
// Do something.
...
...
@@ -250,13 +257,13 @@ Synchronously checks whether the current process can access the specified file.
| path | string | Yes | Absolute path of the target file. |
| mode | number | No | Options for accessing the file. You can specify multiple options, separated with a bitwise OR operator (|). The default value is **0**.<br>The options are as follows:<br>- **0**: check whether the file exists.<br>- **1**: check whether the current process has the execute permission on the file.<br>- **2**: check whether the current process has the write permission on the file.<br>- **4**: check whether the current process has the read permission on the file.|
- Example
**Example**
```js
try{
fileio.accessSync(path);
...
...
@@ -270,21 +277,21 @@ Synchronously checks whether the current process can access the specified file.
close(fd: number):Promise<void>
Asynchronously closes a file. This method uses a promise to return the result.
Asynchronously closes a file. This API uses a promise to return the result.
| src | string \| number | Yes | Path or file descriptor of the file to copy. |
| dest | string \| number | Yes | Path or file descriptor of the new file. |
| mode | number | No | Option for overwriting the file of the same name in the destination path. The default value is **0**, which is the only value supported.<br>**0**: Completely overwrite the file with the same name and truncate the part that is not overwritten.|
| src | string \| number | Yes | Path or file descriptor of the file to copy. |
...
...
@@ -427,7 +434,7 @@ Asynchronously copies a file. This method uses a callback to return the result.
| mode | number | No | Option for overwriting the file of the same name in the destination path. The default value is **0**, which is the only value supported.<br>**0**: Completely overwrite the file with the same name and truncate the part that is not overwritten.|
| callback | AsyncCallback<void> | Yes | Callback invoked when the file is copied asynchronously. |
- Example
**Example**
```js
fileio.copyFile(src,dest,function(err){
// Do something.
...
...
@@ -443,14 +450,14 @@ Synchronously copies a file.
| src | string \| number | Yes | Path or file descriptor of the file to copy. |
| dest | string \| number | Yes | Path or file descriptor of the new file. |
| mode | number | No | Option for overwriting the file of the same name in the destination path. The default value is **0**, which is the only value supported.<br>**0**: Completely overwrite the file with the same name and truncate the part that is not overwritten.|
- Example
**Example**
```js
fileio.copyFileSync(src,dest);
```
...
...
@@ -460,22 +467,22 @@ Synchronously copies a file.
| path | string | Yes | Absolute path of the directory to create. |
| mode | number | No | Permission on the directory to create. You can specify multiple permissions, separated using a bitwise OR operator (|). The default value is **0o775**.<br>- **0o775**: The owner has the read, write, and execute permissions, and other users have the read and execute permissions.<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| path | string | Yes | Absolute path of the directory to create. |
| mode | number | No | Permission on the directory to create. You can specify multiple permissions, separated using a bitwise OR operator (|). The default value is **0o775**.<br>- **0o775**: The owner has the read, write, and execute permissions, and other users have the read and execute permissions.<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| callback | AsyncCallback<void> | Yes | Callback invoked when the directory is created asynchronously. |
- Example
**Example**
```js
fileio.mkdir(path,function(err){
console.info("mkdir successfully");
...
...
@@ -516,13 +523,13 @@ Synchronously creates a directory.
| path | string | Yes | Absolute path of the directory to create. |
| mode | number | No | Permission on the directory to create. You can specify multiple permissions, separated using a bitwise OR operator (|). The default value is **0o775**.<br>- **0o775**: The owner has the read, write, and execute permissions, and other users have the read and execute permissions.<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
- Example
**Example**
```js
fileio.mkdirSync(path);
```
...
...
@@ -532,23 +539,23 @@ Synchronously creates a directory.
| path | string | Yes | Absolute path of the target file. |
| flags | number | No | Option for opening the file. You must specify one of the following options. By default, the file is open in read-only mode.<br>- **0o0**: Open the file in read-only mode.<br>- **0o1**: Open the file in write-only mode.<br>- **0o2**: Open the file in read/write mode.<br>In addition, you can specify the following options, separated using a bitwise OR operator (|). By default, no additional option is specified.<br>- **0o100**: If the file does not exist, create it. If you use this option, you must also specify **mode**.<br>- **0o200**: If **0o100** is added and the file already exists, throw an exception.<br>- **0o1000**: If the file exists and is open in write-only or read/write mode, truncate the file length to 0.<br>- **0o2000**: Open the file in append mode. New data will be appended to the file (added to the end of the file).<br>- **0o4000**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the open file and in subsequent I/Os.<br>- **0o200000**: If **path** points to a directory, throw an exception.<br><br/>- **0o400000**: If **path** points to a symbolic link, throw an exception.<br>- **0o4010000**: Open the file in synchronous I/O mode.|
| flags | number | No | Option for opening the file. You must specify one of the following options. By default, the file is open in read-only mode.<br>- **0o0**: Open the file in read-only mode.<br>- **0o1**: Open the file in write-only mode.<br>- **0o2**: Open the file in read/write mode.<br>In addition, you can specify the following options, separated using a bitwise OR operator (|). By default, no additional option is specified.<br>- **0o100**: If the file does not exist, create it. If you use this option, you must also specify **mode**.<br>- **0o200**: If **0o100** is added and the file already exists, throw an exception.<br>- **0o1000**: If the file exists and is open in write-only or read/write mode, truncate the file length to 0.<br>- **0o2000**: Open the file in append mode. New data will be appended to the file (added to the end of the file).<br>- **0o4000**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the open file and in subsequent I/Os.<br>- **0o200000**: If **path** points to a directory, throw an exception.<br><br>- **0o400000**: If **path** points to a symbolic link, throw an exception.<br>- **0o4010000**: Open the file in synchronous I/O mode.|
| mode | number | No | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|). The default value is **0o666**.<br>- **0o666**: The owner, user group, and other users have the read and write permissions on the file.<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
- Return value
**Return value**
| Type | Description |
| --------------------- | ----------- |
| Promise<number> | File descriptor of the file opened.|
| path | string | Yes | Absolute path of the target file. |
...
...
@@ -574,7 +581,7 @@ Asynchronously opens a file. This method uses a callback to return the result.
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|). The default value is **0o666**.<br>- **0o666**: The owner, user group, and other users have the read and write permissions on the file.<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| callback | AsyncCallback <void> | Yes | Callback invoked when the file is open asynchronously. |
| path | string | Yes | Absolute path of the target file. |
| flags | number | No | Option for opening the file. You must specify one of the following options. By default, the file is open in read-only mode.<br>- **0o0**: Open the file in read-only mode.<br>- **0o1**: Open the file in write-only mode.<br>- **0o2**: Open the file in read/write mode.<br>In addition, you can specify the following options, separated using a bitwise OR operator (|). By default, no additional option is specified.<br>- **0o100**: If the file does not exist, create it. If you use this option, you must also specify **mode**.<br>- **0o200**: If **0o100** is added and the file already exists, throw an exception.<br>- **0o1000**: If the file exists and is open in write-only or read/write mode, truncate the file length to 0.<br>- **0o2000**: Open the file in append mode. New data will be appended to the file (added to the end of the file).<br>- **0o4000**: If **path** points to a named pipe (also known as a FIFO), block special file, or character special file, perform non-blocking operations on the open file and in subsequent I/Os.<br>- **0o200000**: If **path** points to a directory, throw an exception.<br><br/>- **0o400000**: If **path** points to a symbolic link, throw an exception.<br>- **0o4010000**: Open the file in synchronous I/O mode.|
| mode | number | No | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|). The default value is **0o666**.<br>- **0o666**: The owner, user group, and other users have the read and write permissions on the file.<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.<br>The file permissions on newly created files are affected by umask, which is set as the process starts. Currently, the modification of umask is not open.|
| fd | number | Yes | File descriptor of the file to read. |
| buffer | ArrayBuffer | Yes | Buffer used to store the file data read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| fd | number | Yes | File descriptor of the file to read. |
| buffer | ArrayBuffer | Yes | Buffer used to store the file data read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>Constraints: offset + length <= Buffer size|
**Return value**
- Return value
| Type | Description |
| ---------------------------------- | ------ |
| Promise<[ReadOut](#readout)> | Data read.|
| fd | number | Yes | File descriptor of the file to read. |
| buffer | ArrayBuffer | Yes | Buffer used to store the file data read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>Constraints: offset + length <= Buffer size |
| callback | AsyncCallback<[ReadOut](#readout)> | Yes | Callback invoked when the data is read asynchronously. |
- Example
**Example**
```js
letfd=fileio.openSync(path,0o2);
letbuf=newArrayBuffer(4096);
...
...
@@ -690,19 +698,19 @@ Synchronously reads data from a file.
| fd | number | Yes | File descriptor of the file to read. |
| buffer | ArrayBuffer | Yes | Buffer used to store the file data read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>Constraints: offset + length <= Buffer size |
- Return value
**Return value**
| Type | Description |
| ------ | -------- |
| number | Length of the data read.|
- Example
**Example**
```js
letfd=fileio.openSync(path,0o2);
letbuf=newArrayBuffer(4096);
...
...
@@ -714,21 +722,21 @@ Synchronously reads data from a file.
rmdir(path: string): Promise<void>
Asynchronously deletes a directory. This method uses a promise to return the result.
Asynchronously deletes a directory. This API uses a promise to return the result.
| fd | number | Yes | File descriptor of the file to write. |
| buffer | ArrayBuffer \| string | Yes | Data to write. It can be a string or data from a buffer. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size.|
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>Constraints: offset + length <= Buffer size|
- Return value
**Return value**
| Type | Description |
| --------------------- | -------- |
| Promise<number> | Length of the data written in the file.|
| fd | number | Yes | File descriptor of the file to write. |
| buffer | ArrayBuffer \| string | Yes | Data to write. It can be a string or data from a buffer. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size.|
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>Constraints: offset + length <= Buffer size|
| callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. |
| fd | number | Yes | File descriptor of the file to write. |
| buffer | ArrayBuffer \| string | Yes | Data to write. It can be a string or data from a buffer. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size.|
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>Constraints: offset + length <= Buffer size|
- Return value
**Return value**
| Type | Description |
| ------ | -------- |
| number | Length of the data written in the file.|
- Example
**Example**
```js
letfd=fileio.openSync(path,0o100|0o2,0o666);
letnum=fileio.writeSync(fd,"hello, world");
...
...
@@ -953,22 +961,22 @@ Synchronously writes data into a file.
| path | string | Yes | Absolute path of the target file. |
| algorithm | string | Yes | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**.<br/>**sha256** is recommended for security purposes.|
| algorithm | string | Yes | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**.**sha256** is recommended for security purposes.|
| Promise<string> | Promise used to return the hash value of the file. The hash value is a hexadecimal string consisting of digits and uppercase letters.|
| path | string | Yes | Absolute path of the target file. |
| algorithm | string | Yes | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**.<br/>**sha256** is recommended for security purposes.|
| algorithm | string | Yes | Algorithm used to calculate the hash value. The value can be **md5**, **sha1**, or **sha256**.**sha256** is recommended for security purposes.|
| callback | AsyncCallback<string> | Yes | Callback used to return the hash value. The hash value is a hexadecimal string consisting of digits and uppercase letters.|
- Example
**Example**
```js
fileio.hash(fpath,"sha256",function(err,hashStr){
if(hashStr){
...
...
@@ -1007,22 +1015,22 @@ Asynchronously calculates the hash value of a file. This method uses a callback
| path | string | Yes | Absolute path of the target file. |
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|).<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| path | string | Yes | Absolute path of the target file. |
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|).<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| callback | AsyncCallback<void> | Yes | Callback invoked when the file permissions are changed asynchronously. |
- Example
**Example**
```js
fileio.chmod(path,mode,function(err){
// Do something.
...
...
@@ -1063,13 +1071,13 @@ Synchronously changes the file permissions based on its path.
| path | string | Yes | Absolute path of the target file. |
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|).<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
- Example
**Example**
```js
fileio.chmodSync(fpath,mode);
```
...
...
@@ -1079,21 +1087,21 @@ Synchronously changes the file permissions based on its path.
fstat(fd: number): Promise<Stat>
Asynchronously obtains file status information based on the file descriptor. This method uses a promise to return the result.
Asynchronously obtains file status information based on the file descriptor. This API uses a promise to return the result.
| filePath | string | Yes | Absolute path of the file to read. |
| options | Object | No | The options are as follows:<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **encoding** (string): format of the data (string) to be encoded. The default value is **utf-8**, which is the only value supported.|
- Return value
**Return value**
| Type | Description |
| --------------------- | ---------- |
| Promise<string> | Promise used to return the content of the file read.|
| filePath | string | Yes | Absolute path of the file to read. |
| options | Object | No | The options are as follows:<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **encoding** (string): format of the data (string) to be encoded. The default value is **utf-8**, which is the only value supported.|
| callback | AsyncCallback<string> | Yes | Callback invoked when the file is read asynchronously. |
- Example
**Example**
```js
fileio.readText(path,function(err,str){
// Do something.
...
...
@@ -1368,18 +1376,18 @@ Synchronously reads the text of a file.
| filePath | string | Yes | Absolute path of the file to read. |
| options | Object | No | The options are as follows:<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **encoding** (string): format of the data (string) to be encoded. The default value is **utf-8**, which is the only value supported.|
- Return value
**Return value**
| Type | Description |
| ------ | -------------------- |
| string | Content of the file read.|
| string | Promise used to return the content of the file read.|
| buffer | ArrayBuffer | Yes | Buffer used to store the file data read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size.|
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>Constraints: offset + length <= Buffer size|
- Return value
**Return value**
| Type | Description |
| ---------------------------------- | ------ |
| Promise<[ReadOut](#readout)> | Data read.|
| buffer | ArrayBuffer | Yes | Buffer used to store the file data read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size.|
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>Constraints: offset + length <= Buffer size|
| callback | AsyncCallback<[ReadOut](#readout)> | Yes | Callback invoked when the data is read asynchronously from the file. |
- Example
**Example**
```js
letbuf=newArrayBuffer(4096);
fileio.read(buf,function(err,readOut){
...
...
@@ -1528,22 +1536,22 @@ Asynchronously reads data from a file. This method uses a callback to return the
| fd | number | Yes | File descriptor of the target file. |
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|).<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| fd | number | Yes | File descriptor of the target file. |
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|).<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
| callback | AsyncCallback <void> | Yes | Callback invoked when the file permissions are changed asynchronously. |
- Example
**Example**
```js
fileio.fchmod(fd,mode,function(err){
// Do something.
...
...
@@ -2017,13 +2025,13 @@ Synchronously changes the file permissions based on the file descriptor.
| fd | number | Yes | File descriptor of the target file. |
| mode | number | Yes | Permissions on the file. You can specify multiple permissions, separated using a bitwise OR operator (|).<br>- **0o700**: The owner has the read, write, and execute permissions.<br>- **0o400**: The owner has the read permission.<br>- **0o200**: The owner has the write permission.<br>- **0o100**: The owner has the execute permission.<br>- **0o070**: The user group has the read, write, and execute permissions.<br>- **0o040**: The user group has the read permission.<br>- **0o020**: The user group has the write permission.<br>- **0o010**: The user group has the execute permission.<br>- **0o007**: Other users have the read, write, and execute permissions.<br>- **0o004**: Other users have the read permission.<br>- **0o002**: Other users have the write permission.<br>- **0o001**: Other users have the execute permission.|
- Example
**Example**
```js
fileio.fchmodSync(fd,mode);
```
...
...
@@ -2033,22 +2041,22 @@ Synchronously changes the file permissions based on the file descriptor.
| path | string | Yes | Absolute path of the target file. |
| mode | string | Yes | - **r**: Open a file for reading. The file must exist.<br>- **r+**: Open a file for both reading and writing. The file must exist.<br>- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).<br>- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).|
- Return value
**Return value**
| Type | Description |
| --------------------------------- | --------- |
| Promise<[Stream](#stream7)> | Promise used to return the result.|
| path | string | Yes | Absolute path of the target file. |
| mode | string | Yes | - **r**: Open a file for reading. The file must exist.<br>- **r+**: Open a file for both reading and writing. The file must exist.<br>- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).<br>- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).|
| callback | AsyncCallback<[Stream](#stream7)> | Yes | Callback invoked when the stream is open asynchronously. |
| path | string | Yes | Absolute path of the target file. |
| mode | string | Yes | - **r**: Open a file for reading. The file must exist.<br>- **r+**: Open a file for both reading and writing. The file must exist.<br>- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).<br>- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).|
- Return value
**Return value**
| Name | Description |
| ------------------ | --------- |
| [Stream](#stream7) | Stream opened.|
- Example
**Example**
```js
letss=fileio.createStreamSync(path,"r+");
```
...
...
@@ -2110,22 +2118,22 @@ Synchronously opens a stream based on the file path.
| fd | number | Yes | File descriptor of the target file. |
| mode | string | Yes | - **r**: Open a file for reading. The file must exist.<br>- **r+**: Open a file for both reading and writing. The file must exist.<br>- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).<br>- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).|
- Return value
**Return value**
| Name | Description |
| --------------------------------- | --------- |
| Promise<[Stream](#stream7)> | Promise used to return the result.|
| fd | number | Yes | File descriptor of the target file. |
| mode | string | Yes | - **r**: Open a file for reading. The file must exist.<br>- **r+**: Open a file for both reading and writing. The file must exist.<br>- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).<br>- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).|
| callback | AsyncCallback <[Stream](#stream7)> | Yes | Callback invoked when the stream is open asynchronously. |
- Example
**Example**
```js
fileio.fdopenStream(fd,mode,function(err,stream){
// Do something.
...
...
@@ -2166,18 +2174,18 @@ Synchronously opens a stream based on the file descriptor.
| fd | number | Yes | File descriptor of the target file. |
| mode | string | Yes | - **r**: Open a file for reading. The file must exist.<br>- **r+**: Open a file for both reading and writing. The file must exist.<br>- **w**: Open a file for writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **w+**: Open a file for both reading and writing. If the file exists, clear its content. If the file does not exist, create a file.<br>- **a**: Open a file in append mode for writing at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).<br>- **a+**: Open a file in append mode for reading or updating at the end of the file. If the file does not exist, create a file. If the file exists, write data to the end of the file (the original content of the file is reserved).|
- Return value
| Name | Description |
**Return value**
| Type | Description |
| ------------------ | --------- |
| [Stream](#stream7) | Stream opened.|
- Example
**Example**
```js
letss=fileio.fdopenStreamSync(fd,"r+");
```
...
...
@@ -2187,23 +2195,23 @@ Synchronously opens a stream based on the file descriptor.
| filename | string | Yes | Absolute path of the target file. |
| events | Number | Yes | - **1**: The file or directory is renamed.<br>- **2**: The file or directory is modified.<br>- **3**: The file or directory is modified and renamed.|
| callback | AsyncCallback<number > | Yes | Called each time a change is detected. |
- Return value
**Return value**
| Name | Description |
| -------------------- | ---------- |
| [Watcher](#watcher7) | Instance for listening for a file change event.|
| buffer | ArrayBuffer \| string | Yes | Data to write. It can be a string or data from a buffer. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>Constraints: offset + length <= Buffer size |
- Return value
**Return value**
| Type | Description |
| --------------------- | -------- |
| Promise<number> | Length of the data written in the file.|
| buffer | ArrayBuffer \| string | Yes | Data to write. It can be a string or data from a buffer. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size.|
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>Constraints: offset + length <= Buffer size|
| callback | AsyncCallback<number> | Yes | Callback invoked when the data is written asynchronously. |
| buffer | ArrayBuffer \| string | Yes | Data to write. It can be a string or data from a buffer. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position of the data to write in reference to the start address of the data. The default value is **0**.<br>- **length** (number): length of the data to write. The default value is the buffer length minus the offset.<br>- **position** (number): start position to write the data in the file. By default, data is written from the current position.<br>- **encoding** (string): format of the string to be encoded. The default value is **utf-8**, which is the only value supported.<br>Constraints: offset + length <= Buffer size |
- Return value
**Return value**
| Type | Description |
| ------ | -------- |
| number | Length of the data written in the file.|
| buffer | ArrayBuffer | Yes | Buffer used to store the file read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>Constraints: offset + length <= Buffer size |
- Return value
**Return value**
| Type | Description |
| ---------------------------------- | ------ |
| Promise<[ReadOut](#readout)> | Data read.|
| buffer | ArrayBuffer | Yes | Buffer used to store the file read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>Constraints: offset + length <= Buffer size |
| callback | AsyncCallback<[ReadOut](#readout)> | Yes | Callback invoked when data is read asynchronously from the stream. |
| buffer | ArrayBuffer | Yes | Buffer used to store the file read. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>- The sum of **offset** and **length** must be less than or equal to the buffer size. |
| options | Object | No | The options are as follows:<br>- **offset** (number): position to store the data read in the buffer in reference to the start address of the buffer. The default value is **0**.<br>- **length** (number): length of the data to read. The default value is the buffer length minus the offset.<br>- **position** (number): position of the data to read in the file. By default, data is read from the current position.<br>Constraints: offset + length <= Buffer size |