VirtualBox

source: vbox/trunk/include/iprt/stream.h@ 26694

Last change on this file since 26694 was 21045, checked in by vboxsync, 15 years ago

IPRT: Fixed RTStrmClearError so that it clears the error on the stream as well. Added RTStrmRewind. (Needed for #3897.)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 8.5 KB
Line 
1/** @file
2 * IPRT - I/O Stream.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___iprt_stream_h
31#define ___iprt_stream_h
32
33#include <iprt/cdefs.h>
34#include <iprt/types.h>
35#include <iprt/stdarg.h>
36
37RT_C_DECLS_BEGIN
38
39/** @defgroup grp_rt_stream RTStrm - File Streams
40 * @ingroup grp_rt
41 * @{
42 */
43
44/** Pointer to a stream. */
45typedef struct RTSTREAM *PRTSTREAM;
46
47/** Pointer to the standard input stream. */
48extern RTDATADECL(PRTSTREAM) g_pStdIn;
49
50/** Pointer to the standard error stream. */
51extern RTDATADECL(PRTSTREAM) g_pStdErr;
52
53/** Pointer to the standard output stream. */
54extern RTDATADECL(PRTSTREAM) g_pStdOut;
55
56
57/**
58 * Opens a file stream.
59 *
60 * @returns iprt status code.
61 * @param pszFilename Path to the file to open.
62 * @param pszMode The open mode. See fopen() standard.
63 * Format: <a|r|w>[+][b|t]
64 * @param ppStream Where to store the opened stream.
65 */
66RTR3DECL(int) RTStrmOpen(const char *pszFilename, const char *pszMode, PRTSTREAM *ppStream);
67
68/**
69 * Opens a file stream.
70 *
71 * @returns iprt status code.
72 * @param pszMode The open mode. See fopen() standard.
73 * Format: <a|r|w>[+][b|t]
74 * @param ppStream Where to store the opened stream.
75 * @param pszFilenameFmt Filename path format string.
76 * @param args Arguments to the format string.
77 */
78RTR3DECL(int) RTStrmOpenFV(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, va_list args);
79
80/**
81 * Opens a file stream.
82 *
83 * @returns iprt status code.
84 * @param pszMode The open mode. See fopen() standard.
85 * Format: <a|r|w>[+][b|t]
86 * @param ppStream Where to store the opened stream.
87 * @param pszFilenameFmt Filename path format string.
88 * @param ... Arguments to the format string.
89 */
90RTR3DECL(int) RTStrmOpenF(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, ...);
91
92/**
93 * Closes the specified stream.
94 *
95 * @returns iprt status code.
96 * @param pStream The stream to close.
97 */
98RTR3DECL(int) RTStrmClose(PRTSTREAM pStream);
99
100/**
101 * Get the pending error of the stream.
102 *
103 * @returns iprt status code. of the stream.
104 * @param pStream The stream.
105 */
106RTR3DECL(int) RTStrmError(PRTSTREAM pStream);
107
108/**
109 * Clears stream error condition.
110 *
111 * All stream operations save RTStrmClose and this will fail
112 * while an error is asserted on the stream
113 *
114 * @returns iprt status code.
115 * @param pStream The stream.
116 */
117RTR3DECL(int) RTStrmClearError(PRTSTREAM pStream);
118
119/**
120 * Rewinds the stream.
121 *
122 * Stream errors will be reset on success.
123 *
124 * @returns IPRT status code.
125 *
126 * @param pStream The stream.
127 *
128 * @remarks Not all streams are rewindable and that behavior is currently
129 * undefined for those.
130 */
131RTR3DECL(int) RTStrmRewind(PRTSTREAM pStream);
132
133/**
134 * Reads from a file stream.
135 *
136 * @returns iprt status code.
137 * @param pStream The stream.
138 * @param pvBuf Where to put the read bits.
139 * Must be cbRead bytes or more.
140 * @param cbRead Number of bytes to read.
141 * @param pcbRead Where to store the number of bytes actually read.
142 * If NULL cbRead bytes are read or an error is returned.
143 */
144RTR3DECL(int) RTStrmReadEx(PRTSTREAM pStream, void *pvBuf, size_t cbRead, size_t *pcbRead);
145
146/**
147 * Writes to a file stream.
148 *
149 * @returns iprt status code.
150 * @param pStream The stream.
151 * @param pvBuf Where to get the bits to write from.
152 * @param cbWrite Number of bytes to write.
153 * @param pcbWritten Where to store the number of bytes actually written.
154 * If NULL cbWrite bytes are written or an error is returned.
155 */
156RTR3DECL(int) RTStrmWriteEx(PRTSTREAM pStream, const void *pvBuf, size_t cbWrite, size_t *pcbWritten);
157
158/**
159 * Reads from a file stream.
160 *
161 * @returns iprt status code.
162 * @param pStream The stream.
163 * @param pvBuf Where to put the read bits.
164 * Must be cbRead bytes or more.
165 * @param cbRead Number of bytes to read.
166 */
167DECLINLINE(int) RTStrmRead(PRTSTREAM pStream, void *pvBuf, size_t cbRead)
168{
169 return RTStrmReadEx(pStream, pvBuf, cbRead, NULL);
170}
171
172/**
173 * Writes to a file stream.
174 *
175 * @returns iprt status code.
176 * @param pStream The stream.
177 * @param pvBuf Where to get the bits to write from.
178 * @param cbWrite Number of bytes to write.
179 */
180DECLINLINE(int) RTStrmWrite(PRTSTREAM pStream, const void *pvBuf, size_t cbWrite)
181{
182 return RTStrmWriteEx(pStream, pvBuf, cbWrite, NULL);
183}
184
185/**
186 * Reads a character from a file stream.
187 *
188 * @returns The char as an unsigned char cast to int.
189 * @returns -1 on failure.
190 * @param pStream The stream.
191 */
192RTR3DECL(int) RTStrmGetCh(PRTSTREAM pStream);
193
194/**
195 * Writes a character to a file stream.
196 *
197 * @returns iprt status code.
198 * @param pStream The stream.
199 * @param ch The char to write.
200 */
201RTR3DECL(int) RTStrmPutCh(PRTSTREAM pStream, int ch);
202
203/**
204 * Writes a string to a file stream.
205 *
206 * @returns iprt status code.
207 * @param pStream The stream.
208 * @param pszString The string to write.
209 * No newlines or anything is appended or prepended.
210 * The terminating '\\0' is not written, of course.
211 */
212RTR3DECL(int) RTStrmPutStr(PRTSTREAM pStream, const char *pszString);
213
214/**
215 * Reads a line from a file stream.
216 * A line ends with a '\\n', '\\0' or the end of the file.
217 *
218 * @returns iprt status code.
219 * @returns VINF_BUFFER_OVERFLOW if the buffer wasn't big enough to read an entire line.
220 * @param pStream The stream.
221 * @param pszString Where to store the line.
222 * The line will *NOT* contain any '\\n'.
223 * @param cchString The size of the string buffer.
224 */
225RTR3DECL(int) RTStrmGetLine(PRTSTREAM pStream, char *pszString, size_t cchString);
226
227/**
228 * Flushes a stream.
229 *
230 * @returns iprt status code.
231 * @param pStream The stream to flush.
232 */
233RTR3DECL(int) RTStrmFlush(PRTSTREAM pStream);
234
235/**
236 * Prints a formatted string to the specified stream.
237 *
238 * @returns Number of bytes printed.
239 * @param pStream The stream to print to.
240 * @param pszFormat Runtime format string.
241 * @param ... Arguments specified by pszFormat.
242 */
243RTR3DECL(int) RTStrmPrintf(PRTSTREAM pStream, const char *pszFormat, ...);
244
245/**
246 * Prints a formatted string to the specified stream.
247 *
248 * @returns Number of bytes printed.
249 * @param pStream The stream to print to.
250 * @param pszFormat Runtime format string.
251 * @param args Arguments specified by pszFormat.
252 */
253RTR3DECL(int) RTStrmPrintfV(PRTSTREAM pStream, const char *pszFormat, va_list args);
254
255/**
256 * Prints a formatted string to the standard output stream (g_pStdOut).
257 *
258 * @returns Number of bytes printed.
259 * @param pszFormat Runtime format string.
260 * @param ... Arguments specified by pszFormat.
261 */
262RTR3DECL(int) RTPrintf(const char *pszFormat, ...);
263
264/**
265 * Prints a formatted string to the standard output stream (g_pStdOut).
266 *
267 * @returns Number of bytes printed.
268 * @param pszFormat Runtime format string.
269 * @param args Arguments specified by pszFormat.
270 */
271RTR3DECL(int) RTPrintfV(const char *pszFormat, va_list args);
272
273/** @} */
274
275RT_C_DECLS_END
276
277#endif
278
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