docs: clarify that uv_pipe_t is a pipe

Some people have misread this section to imply that libuv does not
support Unix `pipe` objects, while it only should be saying that the
UV_CREATE_PIPE makes a socketpair. Clarify the docs to say specifically
that `uv_pipe_t` represents any local file stream.

PR-URL: https://github.com/libuv/libuv/pull/2607
Reviewed-By: Santiago Gimeno <santiago.gimeno@gmail.com>
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>

2 files changed, 28 insertions, 18 deletions

diff --git a/docs/src/guide/processes.rst b/docs/src/guide/processes.rst
index 839774b5..a7806278 100644
--- a/docs/src/guide/processes.rst
+++ b/docs/src/guide/processes.rst
@@ -243,26 +243,35 @@ is great. Just be warned that creating processes is a costly task.
 
 .. _pipes:
 
-Pipes
------
-
-libuv's ``uv_pipe_t`` structure is slightly confusing to Unix programmers,
-because it immediately conjures up ``|`` and `pipe(7)`_. But ``uv_pipe_t`` is
-not related to anonymous pipes, rather it is an IPC mechanism. ``uv_pipe_t``
-can be backed by a `Unix Domain Socket`_ or `Windows Named Pipe`_ to allow
-multiple processes to communicate. This is discussed below.
-
-.. _pipe(7): http://man7.org/linux/man-pages/man7/pipe.7.html
-.. _Unix Domain Socket: http://man7.org/linux/man-pages/man7/unix.7.html
-.. _Windows Named Pipe: https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipes
-
 Parent-child IPC
-++++++++++++++++
+----------------
 
 A parent and child can have one or two way communication over a pipe created by
 settings ``uv_stdio_container_t.flags`` to a bit-wise combination of
 ``UV_CREATE_PIPE`` and ``UV_READABLE_PIPE`` or ``UV_WRITABLE_PIPE``. The
-read/write flag is from the perspective of the child process.
+read/write flag is from the perspective of the child process.  In this case,
+the ``uv_stream_t* stream`` field must be set to point to an initialized,
+unopened ``uv_pipe_t`` instance.
+
+New stdio Pipes
++++++++++++++++
+
+The ``uv_pipe_t`` structure represents more than just `pipe(7)`_ (or ``|``),
+but supports any streaming file-like objects. On Windows, the only object of
+that description is the `Named Pipe`_.  On Unix, this could be any of `Unix
+Domain Socket`_, or derived from `mkfifo(1)`_, or it could actually be a
+`pipe(7)`_.  When ``uv_spawn`` initializes a ``uv_pipe_t`` due to the
+`UV_CREATE_PIPE` flag, it opts for creating a `socketpair(2)`_.
+
+This is intended for the purpose of allowing multiple libuv processes to
+communicate with IPC. This is discussed below.
+
+.. _pipe(7): http://man7.org/linux/man-pages/man7/pipe.7.html
+.. _mkfifo(1): http://man7.org/linux/man-pages/man1/mkfifo.1.html
+.. _socketpair(2): http://man7.org/linux/man-pages/man2/socketpair.2.html
+.. _Unix Domain Socket: http://man7.org/linux/man-pages/man7/unix.7.html
+.. _Named Pipe: https://docs.microsoft.com/en-us/windows/win32/ipc/named-pipes
+
 
 Arbitrary process IPC
 +++++++++++++++++++++
diff --git a/docs/src/pipe.rst b/docs/src/pipe.rst
index 376d6117..5eac1b6d 100644
--- a/docs/src/pipe.rst
+++ b/docs/src/pipe.rst
@@ -4,8 +4,8 @@
 :c:type:`uv_pipe_t` --- Pipe handle
 ===================================
 
-Pipe handles provide an abstraction over local domain sockets on Unix and named
-pipes on Windows.
+Pipe handles provide an abstraction over streaming files on Unix (including
+local domain sockets, pipes, and FIFOs) and named pipes on Windows.
 
 :c:type:`uv_pipe_t` is a 'subclass' of :c:type:`uv_stream_t`.
 
@@ -34,7 +34,8 @@ API
 .. c:function:: int uv_pipe_init(uv_loop_t* loop, uv_pipe_t* handle, int ipc)
 
     Initialize a pipe handle. The `ipc` argument is a boolean to indicate if
-    this pipe will be used for handle passing between processes.
+    this pipe will be used for handle passing between processes (which may
+    change the bytes on the wire).
 
 .. c:function:: int uv_pipe_open(uv_pipe_t* handle, uv_file file)