VirtualBox

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

Last change on this file since 76557 was 76557, checked in by vboxsync, 6 years ago

include/iprt: Use IPRT_INCLUDED_ rather than _iprt_ as header guard prefix, letting scm enforce this (thereby avoiding copy&paste errors like rsa.h).

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