Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update behaviour of fs.writeFile #25080

Closed

Conversation

thefourtheye
Copy link
Contributor

As per the decision in #23433,
the fs.writeFile will always write from the current position if it
is used with file descriptors. This patch updates it.

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • documentation is changed or added
  • commit message follows commit guidelines

cc @nodejs/fs @nodejs/tsc

@thefourtheye thefourtheye added doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. semver-major PRs that contain breaking changes and should be released in the next major version. labels Dec 17, 2018
Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@vsemozhetbyt vsemozhetbyt added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Dec 17, 2018
@vsemozhetbyt
Copy link
Contributor

Node.js Collaborators, please, add 👍 here if you approve fast-tracking.

Copy link
Member

@rvagg rvagg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pls make sure there's a Ref: https://github.com/nodejs/node/pull/23709 in the metadata too.

@sam-github
Copy link
Contributor

I don't think it should be fast-tracked. Its a critical, much debated, long discussed change, and documentation text should at least have the opportunity for people to comment on it.

doc/api/fs.md Outdated
then the contents of the file would be `'Aloha World'`, rather than just
`'Aloha'`.
3. The writing will begin at the current position. For example, if the string
`'Hello'` is written to the file descriptor, and if `'World'` is written with
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest a string of ', World'. Or perhaps, the first string could be 'Dogs\n', and the second 'Cats\n'? The docs as written generate a misspelled phrase, which to me suggests its demonstrating a side-effect of some kind of misuse of the API, rather than a working-as-designed-and-useful capability.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I included your suggestion, the , World. I didn't change it to Dogs and Cats because, readFile also uses Hello World as the example. Perhaps we can change them together in a separate PR. What do you think?

Copy link
Member

@trivikr trivikr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related code change #23709

@thefourtheye thefourtheye force-pushed the update-fs-writefile-doc branch 2 times, most recently from 3177ae2 to bb31222 Compare December 26, 2018 07:38
As per the decision in nodejs#23433,
the `fs.writeFile` will always write from the current position if it
is used with file descriptors. This patch updates it.

Ref: nodejs#23709
@addaleax
Copy link
Member

addaleax commented Jan 7, 2019

Landed in 309e772

@addaleax addaleax closed this Jan 7, 2019
addaleax pushed a commit that referenced this pull request Jan 7, 2019
As per the decision in #23433,
the `fs.writeFile` will always write from the current position if it
is used with file descriptors. This patch updates it.

Ref: #23709

PR-URL: #25080
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Weijia Wang <starkwang@126.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
@thefourtheye thefourtheye deleted the update-fs-writefile-doc branch January 8, 2019 03:52
refack pushed a commit to refack/node that referenced this pull request Jan 14, 2019
As per the decision in nodejs#23433,
the `fs.writeFile` will always write from the current position if it
is used with file descriptors. This patch updates it.

Ref: nodejs#23709

PR-URL: nodejs#25080
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Weijia Wang <starkwang@126.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
@BethGriggs BethGriggs mentioned this pull request Apr 18, 2019
BethGriggs added a commit that referenced this pull request Apr 22, 2019
Notable changes:

* assert:
  * improve performance to instantiate errors (Ruben Bridgewater)
    [#26738](#26738)
  * validate required arguments (Ruben Bridgewater)
    [#26641](#26641)
  * adjust loose assertions (Ruben Bridgewater)
    [#25008](#25008)
* async_hooks:
  * remove deprecated emitBefore and emitAfter (Matteo Collina)
    [#26530](#26530)
  * remove promise object from resource (Andreas Madsen)
    [#23443](#23443)
* bootstrap
  * make Buffer and process non-enumerable (Ruben Bridgewater)
    [#24874](#24874)
* buffer:
  * use stricter range checks (Ruben Bridgewater)
    [#27045](#27045)
  * harden SlowBuffer creation (ZYSzys)
    [#26272](#26272)
  * harden validation of buffer allocation size (ZYSzys)
    [#26162](#26162)
  * do proper error propagation in addon methods (Anna Henningsen)
    [#23939](#23939)
* child_process:
  * change the defaults maxBuffer size (kohta ito)
    [#27179](#27179)
  * harden fork arguments validation (ZYSzys)
    [#27039](#27039)
  * use non-infinite maxBuffer defaults (kohta ito)
    [#23027](#23027)
* console:
  * don't use ANSI escape codes when TERM=dumb (Vladislav Kaminsky)
    [#26261](#26261)
* crypto:
  * remove legacy native handles (Tobias Nießen)
    [#27011](#27011)
  * decode missing passphrase errors (Tobias Nießen)
    [#25208](#25208)
  * move DEP0113 to End-of-Life (Tobias Nießen)
    [#26249](#26249)
  * remove deprecated crypto.\_toBuf (Tobias Nießen)
    [#25338](#25338)
  * set `DEFAULT\_ENCODING` property to non-enumerable
    (Antoine du Hamel)
    [#23222](#23222)
* deps:
  * silence irrelevant V8 warning (Michaël Zasso)
    [#26685](#26685)
  * update postmortem metadata generation script (cjihrig)
    [#26685](#26685)
  * V8: un-cherry-pick bd019bd (Refael Ackermann)
    [#26685](#26685)
  * V8: cherry-pick 6 commits (Michaël Zasso)
    [#26685](#26685)
  * V8: cherry-pick d82c9af (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick e5f01ba (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick d5f08e4 (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick 6b09d21 (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick f0bb5d2 (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick 5b0510d (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick 91f0cd0 (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick 392316d (Anna Henningsen)
    [#26685](#26685)
  * V8: cherry-pick 2f79d68 (Anna Henningsen)
    [#26685](#26685)
  * sync V8 gypfiles with 7.4 (Ujjwal Sharma)
    [#26685](#26685)
  * update V8 to 7.4.288.13 (Ujjwal Sharma)
    [#26685](#26685)
  * bump minimum icu version to 63 (Ujjwal Sharma)
    [#25852](#25852)
  * silence irrelevant V8 warnings (Michaël Zasso)
    [#25852](#25852)
  * V8: cherry-pick 7803fa6 (Jon Kunkee)
    [#25852](#25852)
  * V8: cherry-pick 58cefed (Jon Kunkee)
    [#25852](#25852)
  * V8: cherry-pick d3308d0 (Michaël Zasso)
    [#25852](#25852)
  * V8: cherry-pick 74571c8 (Michaël Zasso)
    [#25852](#25852)
  * cherry-pick fc0ddf5 from upstream V8 (Anna Henningsen)
    [#25852](#25852)
  * sync V8 gypfiles with 7.3 (Ujjwal Sharma)
    [#25852](#25852)
  * sync V8 gypfiles with 7.2 (Michaël Zasso)
    [#25852](#25852)
  * update V8 to 7.3.492.25 (Michaël Zasso)
    [#25852](#25852)
  * add s390 asm rules for OpenSSL-1.1.1 (Shigeki Ohtsu)
    [#19794](#19794)
  * sync V8 gypfiles with 7.1 (Refael Ackermann)
    [#23423](#23423)
  * update V8 to 7.1.302.28 (Michaël Zasso)
    [#23423](#23423)
* doc:
  * update behaviour of fs.writeFile
    (Sakthipriyan Vairamani (thefourtheye))
    [#25080](#25080)
  * add internal functionality details of util.inherits
    (Ruben Bridgewater)
    [#24755](#24755)
* errors:
  * update error name (Ruben Bridgewater)
    [#26738](#26738)
* fs:
  * use proper .destroy() implementation for SyncWriteStream
    (Matteo Collina)
    [#26690](#26690)
  * improve mode validation (Ruben Bridgewater)
    [#26575](#26575)
  * harden validation of start option in createWriteStream (ZYSzys)
    [#25579](#25579)
  * make writeFile consistent with readFile wrt fd
    (Sakthipriyan Vairamani (thefourtheye))
    [#23709](#23709)
* http:
  * validate timeout in ClientRequest() (cjihrig)
    [#26214](#26214)
  * return HTTP 431 on HPE\_HEADER\_OVERFLOW error (Albert Still)
    [#25605](#25605)
  * switch default parser to llhttp (Anna Henningsen)
    [#24870](#24870)
  * change DEP0066 to a runtime deprecation (Morgan Roderick)
    [#24167](#24167)
  * else case is not reachable (szabolcsit)
    [#24176](#24176)
* lib:
  * move DEP0021 to end of life (cjihrig)
    [#27127](#27127)
  * remove Atomics.wake (Gus Caplan)
    [#27033](#27033)
  * validate Error.captureStackTrace() calls (Ruben Bridgewater)
    [#26738](#26738)
  * refactor Error.captureStackTrace() usage (Ruben Bridgewater)
    [#26738](#26738)
  * move DTRACE\_\* probes out of global scope (James M Snell)
    [#26541](#26541)
  * deprecate \_stream\_wrap (Sam Roberts)  [#26245]
  (#26245)
  * don't use `util.inspect()` internals (Ruben Bridgewater)
    [#24971](#24971)
  * improve error message for MODULE\_NOT\_FOUND (Ali Ijaz Sheikh)
    [#25690](#25690)
  * requireStack property for MODULE\_NOT\_FOUND (Ali Ijaz Sheikh)
    [#25690](#25690)
  * move DEP0029 to end of life (cjihrig)
    [#25377](#25377)
  * move DEP0028 to end of life (cjihrig)
    [#25377](#25377)
  * move DEP0027 to end of life (cjihrig)
    [#25377](#25377)
  * move DEP0026 to end of life (cjihrig)
    [#25377](#25377)
  * move DEP0023 to end of life (cjihrig)
    [#25280](#25280)
  * move DEP0006 to end of life (cjihrig)
    [#25279](#25279)
  * remove unintended access to deps/ (Anna Henningsen)
    [#25138](#25138)
  * move DEP0120 to end of life (cjihrig)
    [#24862](#24862)
  * use ES6 class inheritance style (Ruben Bridgewater)
    [#24755](#24755)
  * remove `inherits()` usage (Ruben Bridgewater)
    [#24755](#24755)
* module:
  * remove dead code (Ruben Bridgewater)
    [#26983](#26983)
  * mark DEP0019 as End-of-Life (Ruben Bridgewater)
    [#26973](#26973)
  * throw an error for invalid package.json main entries
    (Ruben Bridgewater)
    [#26823](#26823)
  * don't search in require.resolve.paths (cjihrig)
    [#23683](#23683)
* n-api:
  * remove code from error name (Ruben Bridgewater)
    [#26738](#26738)
* net:
  * do not manipulate potential user code (Ruben Bridgewater)
    [#26751](#26751)
  * emit "write after end" errors in the next tick (Ouyang Yadong)
    [#24457](#24457)
  * deprecate \_setSimultaneousAccepts() undocumented function
    (James M Snell)
    [#23760](#23760)
* net,http2:
  * merge setTimeout code (ZYSzys)
    [#25084](#25084)
* os:
  * implement os.type() using uv\_os\_uname() (cjihrig)
    [#25659](#25659)
* process:
  * global.process, global.Buffer getters (Guy Bedford)
    [#26882](#26882)
  * move DEP0062 (node --debug) to end-of-life (Joyee Cheung)
    [#25828](#25828)
  * exit on --debug and --debug-brk after option parsing (Joyee Cheung)
    [#25828](#25828)
  * improve `--redirect-warnings` handling (Ruben Bridgewater)
    [#24965](#24965)
* readline:
  * support TERM=dumb (Vladislav Kaminsky)
    [#26261](#26261)
* repl:
  * add welcome message (gengjiawen)
    [#25947](#25947)
  * fix terminal default setting (Ruben Bridgewater)
    [#26518](#26518)
  * check colors with .getColorDepth() (Vladislav Kaminsky)
    [#26261](#26261)
  * deprecate REPLServer.rli (Ruben Bridgewater)
    [#26260](#26260)
* src:
  * remove unused INT\_MAX constant (Sam Roberts)
    [#27078](#27078)
  * update NODE\_MODULE\_VERSION to 72 (Ujjwal Sharma)
    [#26685](#26685)
  * remove `AddPromiseHook()` (Anna Henningsen)
    [#26574](#26574)
  * update NODE\_MODULE\_VERSION to 71 (Michaël Zasso)
    [#25852](#25852)
  * clean up MultiIsolatePlatform interface (Anna Henningsen)
    [#26384](#26384)
  * properly configure default heap limits (Ali Ijaz Sheikh)
    [#25576](#25576)
  * remove icuDataDir from node config (GauthamBanasandra)
    [#24780](#24780)
  * explicitly allow JS in ReadHostObject (Yang Guo)
    [#23423](#23423)
  * update postmortem constant (cjihrig)
    [#23423](#23423)
  * update NODE\_MODULE\_VERSION to 68 (Michaël Zasso)
    [#23423](#23423)
* tls:
  * support TLSv1.3 (Sam Roberts)
    [#26209](#26209)
  * return correct version from getCipher() (Sam Roberts)
    [#26625](#26625)
  * check arg types of renegotiate() (Sam Roberts)
    [#25876](#25876)
  * add code for ERR\_TLS\_INVALID\_PROTOCOL\_METHOD (Sam Roberts)
    [#24729](#24729)
  * emit a warning when servername is an IP address (Rodger Combs)
    [#23329](#23329)
  * disable TLS v1.0 and v1.1 by default (Ben Noordhuis)
    [#23814](#23814)
  * remove unused arg to createSecureContext() (Sam Roberts)
    [#24241](#24241)
  * deprecate Server.prototype.setOptions() (cjihrig)[
    #23820](#23820)
  * load NODE\_EXTRA\_CA\_CERTS at startup (Ouyang Yadong)
    [#23354](#23354)
* util:
  * change inspect compact and breakLength default (Ruben Bridgewater)
    [#27109](#27109)
  * improve inspect edge cases (Ruben Bridgewater)
    [#27109](#27109)
  * only the first line of the error message (Simon Zünd)
    [#26685](#26685)
  * don't set the prototype of callbackified functions
    (Ruben Bridgewater)
    [#26893](#26893)
  * rename callbackified function (Ruben Bridgewater)
    [#26893](#26893)
  * increase function length when using `callbackify()`
    (Ruben Bridgewater)
    [#26893](#26893)
  * prevent tampering with internals in `inspect()` (Ruben Bridgewater)
    [#26577](#26577)
  * fix proxy inspection (Ruben Bridgewater)
    [#26241](#26241)
  * prevent leaking internal properties (Ruben Bridgewater)
    [#24971](#24971)
  * protect against monkeypatched Object prototype for inspect()
    (Rich Trott)
    [#25953](#25953)
  * treat format arguments equally (Roman Reiss)
    [#23162](#23162)
* win, fs:
  * detect if symlink target is a directory (Bartosz Sosnowski)
    [#23724](#23724)
* zlib:
  * throw TypeError if callback is missing (Anna Henningsen)[
    #24929](#24929)
  * make “bare” constants un-enumerable (Anna Henningsen)
    [#24824](#24824)

PR-URL: #26930
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations. fs Issues and PRs related to the fs subsystem / file system. semver-major PRs that contain breaking changes and should be released in the next major version.
Projects
None yet
Development

Successfully merging this pull request may close these issues.