VirtualBox

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

Last change on this file since 64721 was 62473, checked in by vboxsync, 8 years ago

(C) 2016

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