1 2.. _pipe: 3 4:c:type:`uv_pipe_t` --- Pipe handle 5=================================== 6 7Pipe handles provide an abstraction over streaming files on Unix (including 8local domain sockets, pipes, and FIFOs) and named pipes on Windows. 9 10:c:type:`uv_pipe_t` is a 'subclass' of :c:type:`uv_stream_t`. 11 12 13Data types 14---------- 15 16.. c:type:: uv_pipe_t 17 18 Pipe handle type. 19 20 21Public members 22^^^^^^^^^^^^^^ 23 24.. c:member:: int uv_pipe_t.ipc 25 26 Whether this pipe is suitable for handle passing between processes. 27 Only a connected pipe that will be passing the handles should have this flag 28 set, not the listening pipe that uv_accept is called on. 29 30.. seealso:: The :c:type:`uv_stream_t` members also apply. 31 32 33API 34--- 35 36.. c:function:: int uv_pipe_init(uv_loop_t* loop, uv_pipe_t* handle, int ipc) 37 38 Initialize a pipe handle. The `ipc` argument is a boolean to indicate if 39 this pipe will be used for handle passing between processes (which may 40 change the bytes on the wire). Only a connected pipe that will be 41 passing the handles should have this flag set, not the listening pipe 42 that uv_accept is called on. 43 44.. c:function:: int uv_pipe_open(uv_pipe_t* handle, uv_file file) 45 46 Open an existing file descriptor or HANDLE as a pipe. 47 48 .. versionchanged:: 1.2.1 the file descriptor is set to non-blocking mode. 49 50 .. note:: 51 The passed file descriptor or HANDLE is not checked for its type, but 52 it's required that it represents a valid pipe. 53 54.. c:function:: int uv_pipe_bind(uv_pipe_t* handle, const char* name) 55 56 Bind the pipe to a file path (Unix) or a name (Windows). 57 58 .. note:: 59 Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes, typically between 60 92 and 108 bytes. 61 62.. c:function:: void uv_pipe_connect(uv_connect_t* req, uv_pipe_t* handle, const char* name, uv_connect_cb cb) 63 64 Connect to the Unix domain socket or the named pipe. 65 66 .. note:: 67 Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes, typically between 68 92 and 108 bytes. 69 70.. c:function:: int uv_pipe_getsockname(const uv_pipe_t* handle, char* buffer, size_t* size) 71 72 Get the name of the Unix domain socket or the named pipe. 73 74 A preallocated buffer must be provided. The size parameter holds the length 75 of the buffer and it's set to the number of bytes written to the buffer on 76 output. If the buffer is not big enough ``UV_ENOBUFS`` will be returned and 77 len will contain the required size. 78 79 .. versionchanged:: 1.3.0 the returned length no longer includes the terminating null byte, 80 and the buffer is not null terminated. 81 82.. c:function:: int uv_pipe_getpeername(const uv_pipe_t* handle, char* buffer, size_t* size) 83 84 Get the name of the Unix domain socket or the named pipe to which the handle 85 is connected. 86 87 A preallocated buffer must be provided. The size parameter holds the length 88 of the buffer and it's set to the number of bytes written to the buffer on 89 output. If the buffer is not big enough ``UV_ENOBUFS`` will be returned and 90 len will contain the required size. 91 92 .. versionadded:: 1.3.0 93 94.. c:function:: void uv_pipe_pending_instances(uv_pipe_t* handle, int count) 95 96 Set the number of pending pipe instance handles when the pipe server is 97 waiting for connections. 98 99 .. note:: 100 This setting applies to Windows only. 101 102.. c:function:: int uv_pipe_pending_count(uv_pipe_t* handle) 103.. c:function:: uv_handle_type uv_pipe_pending_type(uv_pipe_t* handle) 104 105 Used to receive handles over IPC pipes. 106 107 First - call :c:func:`uv_pipe_pending_count`, if it's > 0 then initialize 108 a handle of the given `type`, returned by :c:func:`uv_pipe_pending_type` 109 and call ``uv_accept(pipe, handle)``. 110 111.. seealso:: The :c:type:`uv_stream_t` API functions also apply. 112 113.. c:function:: int uv_pipe_chmod(uv_pipe_t* handle, int flags) 114 115 Alters pipe permissions, allowing it to be accessed from processes run by 116 different users. Makes the pipe writable or readable by all users. Mode can 117 be ``UV_WRITABLE``, ``UV_READABLE`` or ``UV_WRITABLE | UV_READABLE``. This 118 function is blocking. 119 120 .. versionadded:: 1.16.0 121 122.. c:function:: int uv_pipe(uv_file fds[2], int read_flags, int write_flags) 123 124 Create a pair of connected pipe handles. 125 Data may be written to `fds[1]` and read from `fds[0]`. 126 The resulting handles can be passed to `uv_pipe_open`, used with `uv_spawn`, 127 or for any other purpose. 128 129 Valid values for `flags` are: 130 131 - UV_NONBLOCK_PIPE: Opens the specified socket handle for `OVERLAPPED` 132 or `FIONBIO`/`O_NONBLOCK` I/O usage. 133 This is recommended for handles that will be used by libuv, 134 and not usually recommended otherwise. 135 136 Equivalent to :man:`pipe(2)` with the `O_CLOEXEC` flag set. 137 138 .. versionadded:: 1.41.0 139