From c56640138abfbd1d95b68a1ad0f9848dd86d822d Mon Sep 17 00:00:00 2001 From: Benjamin Gruenbaum Date: Thu, 30 May 2019 12:15:02 +0200 Subject: [PATCH] doc: warn about relying on fs gc close behavior Warn about using the bahvior where file handles are closed automatically when the file is closed. PR-URL: https://github.com/nodejs/node/pull/27972 Reviewed-By: Anna Henningsen Reviewed-By: Rich Trott Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Anto Aravinth Reviewed-By: Luigi Pinca --- doc/api/fs.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 3b3c6efd58243f..581af574038d7c 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -3733,9 +3733,14 @@ added: v10.0.0 A `FileHandle` object is a wrapper for a numeric file descriptor. Instances of `FileHandle` are distinct from numeric file descriptors -in that, if the `FileHandle` is not explicitly closed using the -`filehandle.close()` method, they will automatically close the file descriptor +in that they provide an object oriented API for working with files. + +If a `FileHandle` is not closed using the +`filehandle.close()` method, it might automatically close the file descriptor and will emit a process warning, thereby helping to prevent memory leaks. +Please do not rely on this behavior in your code because it is unreliable and +your file may not be closed. Instead, always explicitly close `FileHandle`s. +Node.js may change this behavior in the future. Instances of the `FileHandle` object are created internally by the `fsPromises.open()` method.