VirtualBox

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

Last change on this file since 95029 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

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