# Interface FileHandle

interface FileHandle {
fd: number;
appendFile(data: string | Uint8Array, options?: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode): Promise<void>;
chown(uid: number, gid: number): Promise<void>;
chmod(mode: Mode): Promise<void>;
createReadStream(options?: CreateReadStreamOptions): ReadStream;
createWriteStream(options?: CreateWriteStreamOptions): WriteStream;
datasync(): Promise<void>;
sync(): Promise<void>;
read<T>(buffer: T, offset?: number, length?: number, position?: number): Promise<FileReadResult<T>>;
read<T>(options?: FileReadOptions<T>): Promise<FileReadResult<T>>;
readableWebStream(options?: ReadableWebStreamOptions): ReadableStream<any>;
readFile(options?: {
encoding?: null;
flag?: OpenMode;
}): Promise<Buffer>;
readFile(options: BufferEncoding | {
encoding: BufferEncoding;
flag?: OpenMode;
}): Promise<string>;
readFile(options?: BufferEncoding | ObjectEncodingOptions & {
flag?: OpenMode;
}): Promise<string | Buffer>;
readLines(options?: CreateReadStreamOptions): Interface;
stat(opts?: StatOptions & {
bigint?: false;
}): Promise<Stats>;
stat(opts: StatOptions & {
bigint: true;
}): Promise<BigIntStats>;
stat(opts?: StatOptions): Promise<Stats | BigIntStats>;
truncate(len?: number): Promise<void>;
utimes(atime: TimeLike, mtime: TimeLike): Promise<void>;
writeFile(data: string | Uint8Array, options?: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode & Abortable): Promise<void>;
write<TBuffer>(buffer: TBuffer, offset?: number, length?: number, position?: number): Promise<{
bytesWritten: number;
buffer: TBuffer;
}>;
write(data: string, position?: number, encoding?: BufferEncoding): Promise<{
bytesWritten: number;
buffer: string;
}>;
writev(buffers: readonly ArrayBufferView[], position?: number): Promise<WriteVResult>;
readv(buffers: readonly ArrayBufferView[], position?: number): Promise<ReadVResult>;
close(): Promise<void>;
[asyncDispose](): Promise<void>;
}

- Defined in node_modules/@types/node/fs/promises.d.ts:95

#####
Index

### Properties

fd

### Methods

appendFile
chown
chmod
createReadStream
createWriteStream
datasync
sync
read
readableWebStream
readFile
readLines
stat
truncate
utimes
writeFile
write
writev
readv
close
[asyncDispose]

##
Properties

### `Readonly` fd

fd: number

The numeric file descriptor managed by the {FileHandle} object.

#### Since

v10.0.0

- Defined in node_modules/@types/node/fs/promises.d.ts:100

##
Methods

### appendFile

- appendFile(data, options?): Promise<void>

- Alias of `filehandle.writeFile()`.

  When operating on file handles, the mode cannot be changed from what it was set to with `fsPromises.open()`. Therefore, this is equivalent to `filehandle.writeFile()`.

  #### Parameters

  - data: string | Uint8Array
  - `Optional` options: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode

  #### Returns Promise<void>

  Fulfills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:109

### chown

- chown(uid, gid): Promise<void>

- Changes the ownership of the file. A wrapper for `chown(2)`.

  #### Parameters

  - uid: number

    The file's new owner's user id.

  - gid: number

    The file's new group's group id.

  #### Returns Promise<void>

  Fulfills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:120

### chmod

- chmod(mode): Promise<void>

- Modifies the permissions on the file. See `chmod(2)`.

  #### Parameters

  - mode: Mode

    the file mode bit mask.

  #### Returns Promise<void>

  Fulfills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:127

### createReadStream

- createReadStream(options?): ReadStream

- Unlike the 16 kb default `highWaterMark` for a `stream.Readable`, the stream returned by this method has a default `highWaterMark` of 64 kb.

  `options` can include `start` and `end` values to read a range of bytes from the file instead of the entire file. Both `start` and `end` are inclusive and start counting at 0, allowed values are in the [0, `Number.MAX_SAFE_INTEGER`] range. If `start` is omitted or `undefined`, `filehandle.createReadStream()` reads sequentially from the current file position. The `encoding` can be any one of those accepted by `Buffer`.

  If the `FileHandle` points to a character device that only supports blocking reads (such as keyboard or sound card), read operations do not finish until data is available. This can prevent the process from exiting and the stream from closing naturally.

  By default, the stream will emit a `'close'` event after it has been destroyed. Set the `emitClose` option to `false` to change this behavior.

      import { open } from 'fs/promises';

      const fd = await open('/dev/input/event0');
      // Create a stream from some character device.
      const stream = fd.createReadStream();
      setTimeout(() => {
        stream.close(); // This may not close the stream.
        // Artificially marking end-of-stream, as if the underlying resource had
        // indicated end-of-file by itself, allows the stream to close.
        // This does not cancel pending read operations, and if there is such an
        // operation, the process may still not be able to exit successfully
        // until it finishes.
        stream.push(null);
        stream.read(0);
      }, 100);

  If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If `autoClose` is set to true (default behavior), on `'error'` or `'end'` the file descriptor will be closed automatically.

  An example to read the last 10 bytes of a file which is 100 bytes long:

      import { open } from 'fs/promises';

      const fd = await open('sample.txt');
      fd.createReadStream({ start: 90, end: 99 });

  #### Parameters

  - `Optional` options: CreateReadStreamOptions

  #### Returns ReadStream

  #### Since

  v16.11.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:181

### createWriteStream

- createWriteStream(options?): WriteStream

- `options` may also include a `start` option to allow writing data at some position past the beginning of the file, allowed values are in the [0, `Number.MAX_SAFE_INTEGER`] range. Modifying a file rather than replacing it may require the `flags` `open` option to be set to `r+` rather than the default `r`. The `encoding` can be any one of those accepted by `Buffer`.

  If `autoClose` is set to true (default behavior) on `'error'` or `'finish'`the file descriptor will be closed automatically. If `autoClose` is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak.

  By default, the stream will emit a `'close'` event after it has been destroyed. Set the `emitClose` option to `false` to change this behavior.

  #### Parameters

  - `Optional` options: CreateWriteStreamOptions

  #### Returns WriteStream

  #### Since

  v16.11.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:198

### datasync

- datasync(): Promise<void>

- Forces all currently queued I/O operations associated with the file to the operating system's synchronized I/O completion state. Refer to the POSIX `fdatasync(2)` documentation for details.

  Unlike `filehandle.sync` this method does not flush modified metadata.

  #### Returns Promise<void>

  Fulfills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:207

### sync

- sync(): Promise<void>

- Request that all data for the open file descriptor is flushed to the storage device. The specific implementation is operating system and device specific. Refer to the POSIX `fsync(2)` documentation for more detail.

  #### Returns Promise<void>

  Fufills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:215

### read

- read<T>(buffer, offset?, length?, position?): Promise<FileReadResult<T>>

- Reads data from the file and stores that in the given buffer.

  If the file is not modified concurrently, the end-of-file is reached when the number of bytes read is zero.

  #### Type Parameters

  - T extends ArrayBufferView

  #### Parameters

  - buffer: T

    A buffer that will be filled with the file data read.

  - `Optional` offset: number

    The location in the buffer at which to start filling.

  - `Optional` length: number

    The number of bytes to read.

  - `Optional` position: number

    The location where to begin reading data from the file. If `null`, data will be read from the current file position, and the position will be updated. If `position` is an integer, the current file position will remain unchanged.

  #### Returns Promise<FileReadResult<T>>

  Fulfills upon success with an object with two properties:

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:229
- read<T>(options?): Promise<FileReadResult<T>>

- #### Type Parameters

  - T extends ArrayBufferView = Buffer

  #### Parameters

  - `Optional` options: FileReadOptions<T>

  #### Returns Promise<FileReadResult<T>>

  - Defined in node_modules/@types/node/fs/promises.d.ts:235

### readableWebStream

- readableWebStream(options?): ReadableStream<any>
- `Experimental`

  Returns a `ReadableStream` that may be used to read the files data.

  An error will be thrown if this method is called more than once or is called after the `FileHandle` is closed or closing.

      import { open } from 'node:fs/promises';

      const file = await open('./some/file/to/read');

      for await (const chunk of file.readableWebStream())
        console.log(chunk);

      await file.close();

  While the `ReadableStream` will read the file to completion, it will not close the `FileHandle` automatically. User code must still call the `fileHandle.close()` method.

  #### Parameters

  - `Optional` options: ReadableWebStreamOptions

  #### Returns ReadableStream<any>

  #### Since

  v17.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:258

### readFile

- readFile(options?): Promise<Buffer>

- Asynchronously reads the entire contents of a file.

  If `options` is a string, then it specifies the `encoding`.

  The `FileHandle` has to support reading.

  If one or more `filehandle.read()` calls are made on a file handle and then a`filehandle.readFile()` call is made, the data will be read from the current position till the end of the file. It doesn't always read from the beginning of the file.

  #### Parameters

  - `Optional` options: {
    encoding?: null;
    flag?: OpenMode;
    }

    - ##### `Optional` encoding?: null

    - ##### `Optional` flag?: OpenMode

  #### Returns Promise<Buffer>

  Fulfills upon a successful read with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a {Buffer} object. Otherwise, the data will be a string.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:273
- readFile(options): Promise<string>

- Asynchronously reads the entire contents of a file. The underlying file will not be closed automatically. The `FileHandle` must have been opened for reading.

  #### Parameters

  - options: BufferEncoding | {
    encoding: BufferEncoding;
    flag?: OpenMode;
    }

    An object that may contain an optional flag. If a flag is not provided, it defaults to `'r'`.

  #### Returns Promise<string>

  - Defined in node_modules/@types/node/fs/promises.d.ts:285
- readFile(options?): Promise<string | Buffer>

- Asynchronously reads the entire contents of a file. The underlying file will not be closed automatically. The `FileHandle` must have been opened for reading.

  #### Parameters

  - `Optional` options: BufferEncoding | ObjectEncodingOptions & {
    flag?: OpenMode;
    }

    An object that may contain an optional flag. If a flag is not provided, it defaults to `'r'`.

  #### Returns Promise<string | Buffer>

  - Defined in node_modules/@types/node/fs/promises.d.ts:299

### readLines

- readLines(options?): Interface

- Convenience method to create a `readline` interface and stream over the file. For example:

      import { open } from 'node:fs/promises';

      const file = await open('./some/file/to/read');

      for await (const line of file.readLines()) {
        console.log(line);
      }

  #### Parameters

  - `Optional` options: CreateReadStreamOptions

    See `filehandle.createReadStream()` for the options.

  #### Returns Interface

  #### Since

  v18.11.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:323

### stat

- stat(opts?): Promise<Stats>

- #### Parameters

  - `Optional` opts: StatOptions & {
    bigint?: false;
    }

  #### Returns Promise<Stats>

  Fulfills with an {fs.Stats} for the file.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:328
- stat(opts): Promise<BigIntStats>

- #### Parameters

  - opts: StatOptions & {
    bigint: true;
    }

  #### Returns Promise<BigIntStats>

  - Defined in node_modules/@types/node/fs/promises.d.ts:333
- stat(opts?): Promise<Stats | BigIntStats>

- #### Parameters

  - `Optional` opts: StatOptions

  #### Returns Promise<Stats | BigIntStats>

  - Defined in node_modules/@types/node/fs/promises.d.ts:338

### truncate

- truncate(len?): Promise<void>

- Truncates the file.

  If the file was larger than `len` bytes, only the first `len` bytes will be retained in the file.

  The following example retains only the first four bytes of the file:

      import { open } from 'fs/promises';

      let filehandle = null;
      try {
        filehandle = await open('temp.txt', 'r+');
        await filehandle.truncate(4);
      } finally {
        await filehandle?.close();
      }

  If the file previously was shorter than `len` bytes, it is extended, and the extended part is filled with null bytes (`'\0'`):

  If `len` is negative then `0` will be used.

  #### Parameters

  - `Optional` len: number

  #### Returns Promise<void>

  Fulfills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:367

### utimes

- utimes(atime, mtime): Promise<void>

- Change the file system timestamps of the object referenced by the `FileHandle` then resolves the promise with no arguments upon success.

  #### Parameters

  - atime: TimeLike
  - mtime: TimeLike

  #### Returns Promise<void>

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:372

### writeFile

- writeFile(data, options?): Promise<void>

- Asynchronously writes data to a file, replacing the file if it already exists.`data` can be a string, a buffer, an AsyncIterable or Iterable object. The promise is resolved with no arguments upon success.

  If `options` is a string, then it specifies the `encoding`.

  The `FileHandle` has to support writing.

  It is unsafe to use `filehandle.writeFile()` multiple times on the same file without waiting for the promise to be resolved (or rejected).

  If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the current position till the end of the file. It doesn't always write from the beginning of the file.

  #### Parameters

  - data: string | Uint8Array
  - `Optional` options: BufferEncoding | ObjectEncodingOptions & FlagAndOpenMode & Abortable

  #### Returns Promise<void>

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:391

### write

- write<TBuffer>(buffer, offset?, length?, position?): Promise<{
  bytesWritten: number;
  buffer: TBuffer;
  }>

- Write `buffer` to the file.

  The promise is resolved with an object containing two properties:

  It is unsafe to use `filehandle.write()` multiple times on the same file without waiting for the promise to be resolved (or rejected). For this scenario, use `filehandle.createWriteStream()`.

  On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.

  #### Type Parameters

  - TBuffer extends Uint8Array

  #### Parameters

  - buffer: TBuffer
  - `Optional` offset: number

    The start position from within `buffer` where the data to write begins.

  - `Optional` length: number

    The number of bytes from `buffer` to write.

  - `Optional` position: number

    The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail.

  #### Returns Promise<{
  bytesWritten: number;
  buffer: TBuffer;
  }>

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:413
- write(data, position?, encoding?): Promise<{
  bytesWritten: number;
  buffer: string;
  }>

- #### Parameters

  - data: string
  - `Optional` position: number
  - `Optional` encoding: BufferEncoding

  #### Returns Promise<{
  bytesWritten: number;
  buffer: string;
  }>

  - Defined in node_modules/@types/node/fs/promises.d.ts:422

### writev

- writev(buffers, position?): Promise<WriteVResult>

- Write an array of ArrayBufferView s to the file.

  The promise is resolved with an object containing a two properties:

  It is unsafe to call `writev()` multiple times on the same file without waiting for the promise to be resolved (or rejected).

  On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file.

  #### Parameters

  - buffers: readonly ArrayBufferView[]
  - `Optional` position: number

    The offset from the beginning of the file where the data from `buffers` should be written. If `position` is not a `number`, the data will be written at the current position.

  #### Returns Promise<WriteVResult>

  #### Since

  v12.9.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:445

### readv

- readv(buffers, position?): Promise<ReadVResult>

- Read from a file and write to an array of ArrayBufferView s

  #### Parameters

  - buffers: readonly ArrayBufferView[]
  - `Optional` position: number

    The offset from the beginning of the file where the data should be read from. If `position` is not a `number`, the data will be read from the current position.

  #### Returns Promise<ReadVResult>

  Fulfills upon success an object containing two properties:

  #### Since

  v13.13.0, v12.17.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:452

### close

- close(): Promise<void>

- Closes the file handle after waiting for any pending operation on the handle to complete.

      import { open } from 'fs/promises';

      let filehandle;
      try {
        filehandle = await open('thefile.txt', 'r');
      } finally {
        await filehandle?.close();
      }

  #### Returns Promise<void>

  Fulfills with `undefined` upon success.

  #### Since

  v10.0.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:470

### [asyncDispose]

- [asyncDispose](): Promise<void>

- An alias for ().

  #### Returns Promise<void>

  #### Since

  v18.18.0

  - Defined in node_modules/@types/node/fs/promises.d.ts:475