VirtualBox

source: vbox/trunk/include/iprt/pipe.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.4 KB
Line 
1/** @file
2 * IPRT - Anonymous Pipes.
3 */
4
5/*
6 * Copyright (C) 2010-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_pipe_h
37#define IPRT_INCLUDED_pipe_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/fs.h>
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_rt_pipe RTPipe - Anonymous Pipes
49 * @ingroup grp_rt
50 *
51 * @note The current Windows implementation has some peculiarities,
52 * especially with respect to the write side where the it is possible
53 * to write one extra pipe buffer sized block of data when the pipe
54 * buffer is full.
55 *
56 * @{
57 */
58
59/**
60 * Create an anonymous pipe.
61 *
62 * @returns IPRT status code.
63 * @param phPipeRead Where to return the read end of the pipe.
64 * @param phPipeWrite Where to return the write end of the pipe.
65 * @param fFlags A combination of RTPIPE_C_XXX defines.
66 */
67RTDECL(int) RTPipeCreate(PRTPIPE phPipeRead, PRTPIPE phPipeWrite, uint32_t fFlags);
68
69/** @name RTPipeCreate flags.
70 * @{ */
71/** Mark the read end as inheritable. */
72#define RTPIPE_C_INHERIT_READ RT_BIT(0)
73/** Mark the write end as inheritable. */
74#define RTPIPE_C_INHERIT_WRITE RT_BIT(1)
75/** Mask of valid flags. */
76#define RTPIPE_C_VALID_MASK UINT32_C(0x00000003)
77/** @} */
78
79/**
80 * Closes one end of a pipe created by RTPipeCreate.
81 *
82 * @returns IPRT status code.
83 * @param hPipe The pipe end to close.
84 */
85RTDECL(int) RTPipeClose(RTPIPE hPipe);
86
87/**
88 * Closes one end of a pipe created by RTPipeCreate, extended version.
89 *
90 * @returns IPRT status code.
91 * @param hPipe The pipe end to close.
92 * @param fLeaveOpen Wheter to leave the underlying native handle open
93 * (for RTPipeClose() this is @c false).
94 */
95RTDECL(int) RTPipeCloseEx(RTPIPE hPipe, bool fLeaveOpen);
96
97/**
98 * Creates an IPRT pipe handle from a native one.
99 *
100 * Do NOT use the native handle after passing it to this function, IPRT owns it
101 * and might even have closed in some cases (in order to gain some query
102 * information access on Windows).
103 *
104 * @returns IPRT status code.
105 * @param phPipe Where to return the pipe handle.
106 * @param hNativePipe The native pipe handle.
107 * @param fFlags Pipe flags, RTPIPE_N_XXX.
108 */
109RTDECL(int) RTPipeFromNative(PRTPIPE phPipe, RTHCINTPTR hNativePipe, uint32_t fFlags);
110
111/** @name RTPipeFromNative flags.
112 * @{ */
113/** The read end. */
114#define RTPIPE_N_READ RT_BIT(0)
115/** The write end. */
116#define RTPIPE_N_WRITE RT_BIT(1)
117/** Make sure the pipe is inheritable if set and not inheritable when clear. */
118#define RTPIPE_N_INHERIT RT_BIT(2)
119/** Mask of valid flags for . */
120#define RTPIPE_N_VALID_MASK UINT32_C(0x00000007)
121/** RTPipeFromNative: Leave the native pipe handle open on close. */
122#define RTPIPE_N_LEAVE_OPEN RT_BIT(3)
123/** Mask of valid flags for RTPipeFromNative(). */
124#define RTPIPE_N_VALID_MASK_FN UINT32_C(0x0000000f)
125/** @} */
126
127/**
128 * Gets the native handle for an IPRT pipe handle.
129 *
130 * This is mainly for passing a pipe to a child and then closing the parent
131 * handle. IPRT also uses it internally to implement RTProcCreatEx and
132 * RTPollSetAdd on some platforms. Do NOT expect sane API behavior if used
133 * for any other purpose.
134 *
135 * @returns The native handle. -1 on failure.
136 * @param hPipe The IPRT pipe handle.
137 */
138RTDECL(RTHCINTPTR) RTPipeToNative(RTPIPE hPipe);
139
140/**
141 * Get the creation inheritability of the pipe.
142 *
143 * @returns true if inherited by children (when pipe was created), false if not.
144 * @param hPipe The IPRT pipe handle.
145 */
146RTDECL(int) RTPipeGetCreationInheritability(RTPIPE hPipe);
147
148/**
149 * Read bytes from a pipe, non-blocking.
150 *
151 * @returns IPRT status code.
152 * @retval VERR_WRONG_ORDER if racing a call to RTPipeReadBlocking.
153 * @retval VERR_BROKEN_PIPE if the remote party has disconnected and we've read
154 * all the buffered data.
155 * @retval VINF_TRY_AGAIN if no data was available. @a *pcbRead will be set to
156 * 0.
157 * @retval VERR_ACCESS_DENIED if it's a write pipe.
158 *
159 * @param hPipe The IPRT pipe handle to read from.
160 * @param pvBuf Where to put the bytes we read.
161 * @param cbToRead How much to read. Must be greater than 0.
162 * @param pcbRead Where to return the number of bytes that has been
163 * read (mandatory). This is 0 if there is no more
164 * bytes to read.
165 * @sa RTPipeReadBlocking.
166 */
167RTDECL(int) RTPipeRead(RTPIPE hPipe, void *pvBuf, size_t cbToRead, size_t *pcbRead);
168
169/**
170 * Read bytes from a pipe, blocking.
171 *
172 * @returns IPRT status code.
173 * @retval VERR_WRONG_ORDER if racing a call to RTPipeRead.
174 * @retval VERR_BROKEN_PIPE if the remote party has disconnected and we've read
175 * all the buffered data.
176 * @retval VERR_ACCESS_DENIED if it's a write pipe.
177 *
178 * @param hPipe The IPRT pipe handle to read from.
179 * @param pvBuf Where to put the bytes we read.
180 * @param cbToRead How much to read.
181 * @param pcbRead Where to return the number of bytes that has been
182 * read. Optional.
183 */
184RTDECL(int) RTPipeReadBlocking(RTPIPE hPipe, void *pvBuf, size_t cbToRead, size_t *pcbRead);
185
186/**
187 * Write bytes to a pipe, non-blocking.
188 *
189 * @returns IPRT status code.
190 * @retval VERR_WRONG_ORDER if racing a call to RTPipeWriteBlocking.
191 * @retval VERR_BROKEN_PIPE if the remote party has disconnected. Does not
192 * trigger when @a cbToWrite is 0.
193 * @retval VINF_TRY_AGAIN if no data was written. @a *pcbWritten will be set
194 * to 0.
195 * @retval VERR_ACCESS_DENIED if it's a read pipe.
196 *
197 * @param hPipe The IPRT pipe handle to write to.
198 * @param pvBuf What to write.
199 * @param cbToWrite How much to write.
200 * @param pcbWritten How many bytes we wrote, mandatory. The return can
201 * be 0.
202 */
203RTDECL(int) RTPipeWrite(RTPIPE hPipe, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
204
205/**
206 * Write bytes to a pipe, blocking.
207 *
208 * @returns IPRT status code.
209 * @retval VERR_WRONG_ORDER if racing a call to RTPipeWrite.
210 * @retval VERR_BROKEN_PIPE if the remote party has disconnected. Does not
211 * trigger when @a cbToWrite is 0.
212 * @retval VERR_ACCESS_DENIED if it's a read pipe.
213 *
214 * @param hPipe The IPRT pipe handle to write to.
215 * @param pvBuf What to write.
216 * @param cbToWrite How much to write.
217 * @param pcbWritten How many bytes we wrote, optional. If NULL then all
218 * bytes will be written.
219 */
220RTDECL(int) RTPipeWriteBlocking(RTPIPE hPipe, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
221
222/**
223 * Flushes the buffers for the specified pipe and making sure the other party
224 * reads them.
225 *
226 * @returns IPRT status code.
227 * @retval VERR_NOT_SUPPORTED if not supported by the OS.
228 * @retval VERR_BROKEN_PIPE if the remote party has disconnected.
229 * @retval VERR_ACCESS_DENIED if it's a read pipe.
230 *
231 * @param hPipe The IPRT pipe handle to flush.
232 */
233RTDECL(int) RTPipeFlush(RTPIPE hPipe);
234
235/**
236 * Checks if the pipe is ready for reading or writing (depending on the pipe
237 * end).
238 *
239 * @returns IPRT status code.
240 * @retval VERR_TIMEOUT if the timeout was reached before the pipe was ready
241 * for reading/writing.
242 * @retval VERR_NOT_SUPPORTED if not supported by the OS?
243 *
244 * @param hPipe The IPRT pipe handle to select on.
245 * @param cMillies Number of milliseconds to wait. Use
246 * RT_INDEFINITE_WAIT to wait for ever.
247 */
248RTDECL(int) RTPipeSelectOne(RTPIPE hPipe, RTMSINTERVAL cMillies);
249
250/**
251 * Queries the number of bytes immediately available for reading.
252 *
253 * @returns IPRT status code.
254 * @retval VERR_NOT_SUPPORTED if not supported by the OS. The caller shall
255 * handle this case.
256 *
257 * @param hPipe The IPRT read pipe handle.
258 * @param pcbReadable Where to return the number of bytes that is ready
259 * to be read.
260 */
261RTDECL(int) RTPipeQueryReadable(RTPIPE hPipe, size_t *pcbReadable);
262
263/**
264 * Query information about a pipe (mainly a VFS I/O stream formality).
265 *
266 * The only thing we guarentee to be returned is RTFSOBJINFO::Attr.fMode being
267 * set to FIFO and will reflect the read/write end in the RTFS_DOS_READONLY,
268 * RTFS_UNIX_IRUSR and RTFS_UNIX_IWUSR bits.
269 *
270 * Some implementations sometimes provide the pipe buffer size via
271 * RTFSOBJINFO::cbAllocated.
272 *
273 * Some implementations sometimes provide the available read data or available
274 * write space via RTFSOBJINFO::cbObject.
275 *
276 * Some implementations sometimes provide valid device and/or inode numbers.
277 *
278 * @returns iprt status code.
279 *
280 * @param hPipe The IPRT read pipe handle.
281 * @param pObjInfo Object information structure to be filled on successful
282 * return.
283 * @param enmAddAttr Which set of additional attributes to request. Use
284 * RTFSOBJATTRADD_NOTHING if this doesn't matter.
285 */
286RTDECL(int) RTPipeQueryInfo(RTPIPE hPipe, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAddAttr);
287
288/** @} */
289
290RT_C_DECLS_END
291
292#endif /* !IPRT_INCLUDED_pipe_h */
293
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette