From 132c77e9f968f7a9b44de3f491926061c42a06af Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Sat, 23 Mar 2013 15:38:17 +0100 Subject: [PATCH] doc: document that stdio is usually blocking --- doc/api/stdio.markdown | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/api/stdio.markdown b/doc/api/stdio.markdown index 0da30a0add0..e53902f7ad9 100644 --- a/doc/api/stdio.markdown +++ b/doc/api/stdio.markdown @@ -9,6 +9,19 @@ For printing to stdout and stderr. Similar to the console object functions provided by most web browsers, here the output is sent to stdout or stderr. +The console functions are synchronous when the destination is a terminal or +a file (to avoid lost messages in case of premature exit) and asynchronous +when it's a pipe (to avoid blocking for long periods of time). + +That is, in the following example, stdout is non-blocking while stderr +is blocking: + + $ node script.js 2> error.log | tee info.log + +In daily use, the blocking/non-blocking dichotomy is not something you +should worry about unless you log huge amounts of data. + + ## console.log([data], [...]) Prints to stdout with newline. This function can take multiple arguments in a