VirtualBox

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

Last change on this file since 58389 was 56919, checked in by vboxsync, 9 years ago

Introducing RT_IPRT_FORMAT_ATTR for the purpose of marking functions working on our special format strings.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.2 KB
Line 
1/** @file
2 * IPRT - I/O Stream.
3 */
4
5/*
6 * Copyright (C) 2006-2015 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_stream_h
27#define ___iprt_stream_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31#include <iprt/stdarg.h>
32
33RT_C_DECLS_BEGIN
34
35/** @defgroup grp_rt_stream RTStrm - File Streams
36 * @ingroup grp_rt
37 * @{
38 */
39
40/** Pointer to a stream. */
41typedef struct RTSTREAM *PRTSTREAM;
42
43/** Pointer to the standard input stream. */
44extern RTDATADECL(PRTSTREAM) g_pStdIn;
45
46/** Pointer to the standard error stream. */
47extern RTDATADECL(PRTSTREAM) g_pStdErr;
48
49/** Pointer to the standard output stream. */
50extern RTDATADECL(PRTSTREAM) g_pStdOut;
51
52
53/**
54 * Opens a file stream.
55 *
56 * @returns iprt status code.
57 * @param pszFilename Path to the file to open.
58 * @param pszMode The open mode. See fopen() standard.
59 * Format: <a|r|w>[+][b|t]
60 * @param ppStream Where to store the opened stream.
61 */
62RTR3DECL(int) RTStrmOpen(const char *pszFilename, const char *pszMode, PRTSTREAM *ppStream);
63
64/**
65 * Opens a file stream.
66 *
67 * @returns iprt status code.
68 * @param pszMode The open mode. See fopen() standard.
69 * Format: <a|r|w>[+][b|t]
70 * @param ppStream Where to store the opened stream.
71 * @param pszFilenameFmt Filename path format string.
72 * @param args Arguments to the format string.
73 */
74RTR3DECL(int) RTStrmOpenFV(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt,
75 va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
76
77/**
78 * Opens a file stream.
79 *
80 * @returns iprt status code.
81 * @param pszMode The open mode. See fopen() standard.
82 * Format: <a|r|w>[+][b|t]
83 * @param ppStream Where to store the opened stream.
84 * @param pszFilenameFmt Filename path format string.
85 * @param ... Arguments to the format string.
86 */
87RTR3DECL(int) RTStrmOpenF(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
88
89/**
90 * Closes the specified stream.
91 *
92 * @returns iprt status code.
93 * @param pStream The stream to close.
94 */
95RTR3DECL(int) RTStrmClose(PRTSTREAM pStream);
96
97/**
98 * Get the pending error of the stream.
99 *
100 * @returns iprt status code. of the stream.
101 * @param pStream The stream.
102 */
103RTR3DECL(int) RTStrmError(PRTSTREAM pStream);
104
105/**
106 * Clears stream error condition.
107 *
108 * All stream operations save RTStrmClose and this will fail
109 * while an error is asserted on the stream
110 *
111 * @returns iprt status code.
112 * @param pStream The stream.
113 */
114RTR3DECL(int) RTStrmClearError(PRTSTREAM pStream);
115
116/**
117 * Changes the stream mode.
118 *
119 * @returns iprt status code.
120 * @param pStream The stream.
121 * @param fBinary The desired binary (@c true) / text mode (@c false).
122 * Pass -1 to leave it unchanged.
123 * @param fCurrentCodeSet Whether converting the stream from UTF-8 to the
124 * current code set is desired (@c true) or not (@c
125 * false). Pass -1 to leave this property unchanged.
126 */
127RTR3DECL(int) RTStrmSetMode(PRTSTREAM pStream, int fBinary, int fCurrentCodeSet);
128
129/**
130 * Returns the current echo mode.
131 * This works only for standard input streams.
132 *
133 * @returns iprt status code.
134 * @param pStream The stream.
135 * @param pfEchoChars Where to store the flag whether typed characters are echoed.
136 */
137RTR3DECL(int) RTStrmInputGetEchoChars(PRTSTREAM pStream, bool *pfEchoChars);
138
139/**
140 * Changes the behavior for echoing inpit characters on the command line.
141 * This works only for standard input streams.
142 *
143 * @returns iprt status code.
144 * @param pStream The stream.
145 * @param fEchoChars Flag whether echoing typed characters is wanted.
146 */
147RTR3DECL(int) RTStrmInputSetEchoChars(PRTSTREAM pStream, bool fEchoChars);
148
149/**
150 * Rewinds the stream.
151 *
152 * Stream errors will be reset on success.
153 *
154 * @returns IPRT status code.
155 *
156 * @param pStream The stream.
157 *
158 * @remarks Not all streams are rewindable and that behavior is currently
159 * undefined for those.
160 */
161RTR3DECL(int) RTStrmRewind(PRTSTREAM pStream);
162
163/**
164 * Reads from a file stream.
165 *
166 * @returns iprt status code.
167 * @param pStream The stream.
168 * @param pvBuf Where to put the read bits.
169 * Must be cbRead bytes or more.
170 * @param cbRead Number of bytes to read.
171 * @param pcbRead Where to store the number of bytes actually read.
172 * If NULL cbRead bytes are read or an error is returned.
173 */
174RTR3DECL(int) RTStrmReadEx(PRTSTREAM pStream, void *pvBuf, size_t cbRead, size_t *pcbRead);
175
176/**
177 * Writes to a file stream.
178 *
179 * @returns iprt status code.
180 * @param pStream The stream.
181 * @param pvBuf Where to get the bits to write from.
182 * @param cbWrite Number of bytes to write.
183 * @param pcbWritten Where to store the number of bytes actually written.
184 * If NULL cbWrite bytes are written or an error is returned.
185 */
186RTR3DECL(int) RTStrmWriteEx(PRTSTREAM pStream, const void *pvBuf, size_t cbWrite, size_t *pcbWritten);
187
188/**
189 * Reads from a file stream.
190 *
191 * @returns iprt status code.
192 * @param pStream The stream.
193 * @param pvBuf Where to put the read bits.
194 * Must be cbRead bytes or more.
195 * @param cbRead Number of bytes to read.
196 */
197DECLINLINE(int) RTStrmRead(PRTSTREAM pStream, void *pvBuf, size_t cbRead)
198{
199 return RTStrmReadEx(pStream, pvBuf, cbRead, NULL);
200}
201
202/**
203 * Writes to a file stream.
204 *
205 * @returns iprt status code.
206 * @param pStream The stream.
207 * @param pvBuf Where to get the bits to write from.
208 * @param cbWrite Number of bytes to write.
209 */
210DECLINLINE(int) RTStrmWrite(PRTSTREAM pStream, const void *pvBuf, size_t cbWrite)
211{
212 return RTStrmWriteEx(pStream, pvBuf, cbWrite, NULL);
213}
214
215/**
216 * Reads a character from a file stream.
217 *
218 * @returns The char as an unsigned char cast to int.
219 * @returns -1 on failure.
220 * @param pStream The stream.
221 */
222RTR3DECL(int) RTStrmGetCh(PRTSTREAM pStream);
223
224/**
225 * Writes a character to a file stream.
226 *
227 * @returns iprt status code.
228 * @param pStream The stream.
229 * @param ch The char to write.
230 */
231RTR3DECL(int) RTStrmPutCh(PRTSTREAM pStream, int ch);
232
233/**
234 * Writes a string to a file stream.
235 *
236 * @returns iprt status code.
237 * @param pStream The stream.
238 * @param pszString The string to write.
239 * No newlines or anything is appended or prepended.
240 * The terminating '\\0' is not written, of course.
241 */
242RTR3DECL(int) RTStrmPutStr(PRTSTREAM pStream, const char *pszString);
243
244/**
245 * Reads a line from a file stream.
246 *
247 * A line ends with a '\\n', '\\r\\n', '\\0' or the end of the file.
248 *
249 * @returns iprt status code.
250 * @retval VINF_BUFFER_OVERFLOW if the buffer wasn't big enough to read an
251 * entire line.
252 * @retval VERR_BUFFER_OVERFLOW if a lone '\\r' was encountered at the end of
253 * the buffer and we ended up dropping the following character.
254 *
255 * @param pStream The stream.
256 * @param pszString Where to store the line.
257 * The line will *NOT* contain any '\\n'.
258 * @param cbString The size of the string buffer.
259 */
260RTR3DECL(int) RTStrmGetLine(PRTSTREAM pStream, char *pszString, size_t cbString);
261
262/**
263 * Flushes a stream.
264 *
265 * @returns iprt status code.
266 * @param pStream The stream to flush.
267 */
268RTR3DECL(int) RTStrmFlush(PRTSTREAM pStream);
269
270/**
271 * Prints a formatted string to the specified stream.
272 *
273 * @returns Number of bytes printed.
274 * @param pStream The stream to print to.
275 * @param pszFormat Runtime format string.
276 * @param ... Arguments specified by pszFormat.
277 */
278RTR3DECL(int) RTStrmPrintf(PRTSTREAM pStream, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
279
280/**
281 * Prints a formatted string to the specified stream.
282 *
283 * @returns Number of bytes printed.
284 * @param pStream The stream to print to.
285 * @param pszFormat Runtime format string.
286 * @param args Arguments specified by pszFormat.
287 */
288RTR3DECL(int) RTStrmPrintfV(PRTSTREAM pStream, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(2, 0);
289
290/**
291 * Dumper vprintf-like function outputting to a stream.
292 *
293 * @param pvUser The stream to print to. NULL means standard output.
294 * @param pszFormat Runtime format string.
295 * @param va Arguments specified by pszFormat.
296 */
297RTR3DECL(void) RTStrmDumpPrintfV(void *pvUser, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
298
299/**
300 * Prints a formatted string to the standard output stream (g_pStdOut).
301 *
302 * @returns Number of bytes printed.
303 * @param pszFormat Runtime format string.
304 * @param ... Arguments specified by pszFormat.
305 */
306RTR3DECL(int) RTPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
307
308/**
309 * Prints a formatted string to the standard output stream (g_pStdOut).
310 *
311 * @returns Number of bytes printed.
312 * @param pszFormat Runtime format string.
313 * @param args Arguments specified by pszFormat.
314 */
315RTR3DECL(int) RTPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
316
317/** @} */
318
319RT_C_DECLS_END
320
321#endif
322
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