Mercurial

comparison third_party/libuv/docs/src/pipe.rst @ 160:948de3f54cea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added libuv
author June Park <parkjune1995@gmail.com>
date Wed, 14 Jan 2026 19:39:52 -0800
parents
children
comparison
equal deleted inserted replaced
159:05cf9467a1c3 160:948de3f54cea
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