|
160
|
1
|
|
|
2 .. _pipe:
|
|
|
3
|
|
|
4 :c:type:`uv_pipe_t` --- Pipe handle
|
|
|
5 ===================================
|
|
|
6
|
|
|
7 Pipe handles provide an abstraction over streaming files on Unix (including
|
|
|
8 local 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
|
|
|
13 Data types
|
|
|
14 ----------
|
|
|
15
|
|
|
16 .. c:type:: uv_pipe_t
|
|
|
17
|
|
|
18 Pipe handle type.
|
|
|
19
|
|
|
20
|
|
|
21 Public 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
|
|
|
33 API
|
|
|
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 Does not support Linux abstract namespace sockets,
|
|
|
59 unlike :c:func:`uv_pipe_bind2`.
|
|
|
60
|
|
|
61 Alias for ``uv_pipe_bind2(handle, name, strlen(name), 0)``.
|
|
|
62
|
|
|
63 .. note::
|
|
|
64 Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes,
|
|
|
65 typically between 92 and 108 bytes.
|
|
|
66
|
|
|
67 .. c:function:: int uv_pipe_bind2(uv_pipe_t* handle, const char* name, size_t namelen, unsigned int flags)
|
|
|
68
|
|
|
69 Bind the pipe to a file path (Unix) or a name (Windows).
|
|
|
70
|
|
|
71 ``flags`` must be zero or ``UV_PIPE_NO_TRUNCATE``. Returns ``UV_EINVAL``
|
|
|
72 for unsupported flags without performing the bind operation.
|
|
|
73
|
|
|
74 Supports Linux abstract namespace sockets. ``namelen`` must include
|
|
|
75 the leading nul byte but not the trailing nul byte.
|
|
|
76
|
|
|
77 .. versionadded:: 1.46.0
|
|
|
78
|
|
|
79 .. note::
|
|
|
80 Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes,
|
|
|
81 typically between 92 and 108 bytes, unless the ``UV_PIPE_NO_TRUNCATE``
|
|
|
82 flag is specified, in which case an ``UV_EINVAL`` error is returned.
|
|
|
83
|
|
|
84 .. c:function:: void uv_pipe_connect(uv_connect_t* req, uv_pipe_t* handle, const char* name, uv_connect_cb cb)
|
|
|
85
|
|
|
86 Connect to the Unix domain socket or the Windows named pipe.
|
|
|
87
|
|
|
88 Does not support Linux abstract namespace sockets,
|
|
|
89 unlike :c:func:`uv_pipe_connect2`.
|
|
|
90
|
|
|
91 Alias for ``uv_pipe_connect2(req, handle, name, strlen(name), 0, cb)``.
|
|
|
92
|
|
|
93 .. note::
|
|
|
94 Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes,
|
|
|
95 typically between 92 and 108 bytes.
|
|
|
96
|
|
|
97 .. c:function:: void uv_pipe_connect2(uv_connect_t* req, uv_pipe_t* handle, const char* name, size_t namelen, unsigned int flags, uv_connect_cb cb)
|
|
|
98
|
|
|
99 Connect to the Unix domain socket or the Windows named pipe.
|
|
|
100
|
|
|
101 ``flags`` must be zero or ``UV_PIPE_NO_TRUNCATE``. Returns ``UV_EINVAL``
|
|
|
102 for unsupported flags without performing the connect operation.
|
|
|
103
|
|
|
104 Supports Linux abstract namespace sockets. ``namelen`` must include
|
|
|
105 the leading nul byte but not the trailing nul byte.
|
|
|
106
|
|
|
107 .. versionadded:: 1.46.0
|
|
|
108
|
|
|
109 .. note::
|
|
|
110 Paths on Unix get truncated to ``sizeof(sockaddr_un.sun_path)`` bytes,
|
|
|
111 typically between 92 and 108 bytes, unless the ``UV_PIPE_NO_TRUNCATE``
|
|
|
112 flag is specified, in which case an ``UV_EINVAL`` error is returned.
|
|
|
113
|
|
|
114 .. c:function:: int uv_pipe_getsockname(const uv_pipe_t* handle, char* buffer, size_t* size)
|
|
|
115
|
|
|
116 Get the name of the Unix domain socket or the named pipe.
|
|
|
117
|
|
|
118 A preallocated buffer must be provided. The size parameter holds the length
|
|
|
119 of the buffer and it's set to the number of bytes written to the buffer on
|
|
|
120 output. If the buffer is not big enough ``UV_ENOBUFS`` will be returned and
|
|
|
121 len will contain the required size.
|
|
|
122
|
|
|
123 .. versionchanged:: 1.3.0 the returned length no longer includes the terminating null byte,
|
|
|
124 and the buffer is not null terminated.
|
|
|
125
|
|
|
126 .. c:function:: int uv_pipe_getpeername(const uv_pipe_t* handle, char* buffer, size_t* size)
|
|
|
127
|
|
|
128 Get the name of the Unix domain socket or the named pipe to which the handle
|
|
|
129 is connected.
|
|
|
130
|
|
|
131 A preallocated buffer must be provided. The size parameter holds the length
|
|
|
132 of the buffer and it's set to the number of bytes written to the buffer on
|
|
|
133 output. If the buffer is not big enough ``UV_ENOBUFS`` will be returned and
|
|
|
134 len will contain the required size.
|
|
|
135
|
|
|
136 .. versionadded:: 1.3.0
|
|
|
137
|
|
|
138 .. c:function:: void uv_pipe_pending_instances(uv_pipe_t* handle, int count)
|
|
|
139
|
|
|
140 Set the number of pending pipe instance handles when the pipe server is
|
|
|
141 waiting for connections.
|
|
|
142
|
|
|
143 .. note::
|
|
|
144 This setting applies to Windows only.
|
|
|
145
|
|
|
146 .. c:function:: int uv_pipe_pending_count(uv_pipe_t* handle)
|
|
|
147 .. c:function:: uv_handle_type uv_pipe_pending_type(uv_pipe_t* handle)
|
|
|
148
|
|
|
149 Used to receive handles over IPC pipes.
|
|
|
150
|
|
|
151 First - call :c:func:`uv_pipe_pending_count`, if it's > 0 then initialize
|
|
|
152 a handle of the given `type`, returned by :c:func:`uv_pipe_pending_type`
|
|
|
153 and call ``uv_accept(pipe, handle)``.
|
|
|
154
|
|
|
155 .. seealso:: The :c:type:`uv_stream_t` API functions also apply.
|
|
|
156
|
|
|
157 .. c:function:: int uv_pipe_chmod(uv_pipe_t* handle, int flags)
|
|
|
158
|
|
|
159 Alters pipe permissions, allowing it to be accessed from processes run by
|
|
|
160 different users. Makes the pipe writable or readable by all users. Mode can
|
|
|
161 be ``UV_WRITABLE``, ``UV_READABLE`` or ``UV_WRITABLE | UV_READABLE``. This
|
|
|
162 function is blocking.
|
|
|
163
|
|
|
164 .. versionadded:: 1.16.0
|
|
|
165
|
|
|
166 .. c:function:: int uv_pipe(uv_file fds[2], int read_flags, int write_flags)
|
|
|
167
|
|
|
168 Create a pair of connected pipe handles.
|
|
|
169 Data may be written to `fds[1]` and read from `fds[0]`.
|
|
|
170 The resulting handles can be passed to `uv_pipe_open`, used with `uv_spawn`,
|
|
|
171 or for any other purpose.
|
|
|
172
|
|
|
173 Valid values for `flags` are:
|
|
|
174
|
|
|
175 - UV_NONBLOCK_PIPE: Opens the specified socket handle for `OVERLAPPED`
|
|
|
176 or `FIONBIO`/`O_NONBLOCK` I/O usage.
|
|
|
177 This is recommended for handles that will be used by libuv,
|
|
|
178 and not usually recommended otherwise.
|
|
|
179
|
|
|
180 Equivalent to :man:`pipe(2)` with the `O_CLOEXEC` flag set.
|
|
|
181
|
|
|
182 .. versionadded:: 1.41.0
|
