VirtualBox

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

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.0 KB
Line 
1/** @file
2 * IPRT - I/O Stream.
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_stream_h
37#define IPRT_INCLUDED_stream_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/stdarg.h>
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_rt_stream RTStrm - File Streams
49 * @ingroup grp_rt
50 * @{
51 */
52
53#ifndef IPRT_INCLUDED_message_h
54/** Pointer to a stream. */
55typedef struct RTSTREAM *PRTSTREAM;
56#endif
57
58/** Pointer to the standard input stream. */
59extern RTDATADECL(PRTSTREAM) g_pStdIn;
60
61/** Pointer to the standard error stream. */
62extern RTDATADECL(PRTSTREAM) g_pStdErr;
63
64/** Pointer to the standard output stream. */
65extern RTDATADECL(PRTSTREAM) g_pStdOut;
66
67
68/**
69 * Opens a file stream.
70 *
71 * @returns iprt status code.
72 * @param pszFilename Path to the file to open.
73 * @param pszMode The open mode. See fopen() standard.
74 * Format: <a|r|w>[+][b|t][x][e|N|E]
75 * - 'a': Open or create file and writes
76 * append tos it.
77 * - 'r': Open existing file and read from it.
78 * - 'w': Open or truncate existing file and write
79 * to it.
80 * - '+': Open for both read and write access.
81 * - 'b' / 't': binary / text
82 * - 'x': exclusively create, no open. Only
83 * possible with 'w'.
84 * - 'e' / 'N': No inherit on exec. (The 'e' is
85 * how Linux and FreeBSD expresses this, the
86 * latter is Visual C++).
87 * @param ppStream Where to store the opened stream.
88 */
89RTR3DECL(int) RTStrmOpen(const char *pszFilename, const char *pszMode, PRTSTREAM *ppStream);
90
91/**
92 * Opens a file stream.
93 *
94 * @returns iprt status code.
95 * @param pszMode The open mode. See fopen() standard.
96 * Format: <a|r|w>[+][b|t][x][e|N|E]
97 * - 'a': Open or create file and writes
98 * append tos it.
99 * - 'r': Open existing file and read from it.
100 * - 'w': Open or truncate existing file and write
101 * to it.
102 * - '+': Open for both read and write access.
103 * - 'b' / 't': binary / text
104 * - 'x': exclusively create, no open. Only
105 * possible with 'w'.
106 * - 'e' / 'N': No inherit on exec. (The 'e' is
107 * how Linux and FreeBSD expresses this, the
108 * latter is Visual C++).
109 * @param ppStream Where to store the opened stream.
110 * @param pszFilenameFmt Filename path format string.
111 * @param args Arguments to the format string.
112 */
113RTR3DECL(int) RTStrmOpenFV(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt,
114 va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
115
116/**
117 * Opens a file stream.
118 *
119 * @returns iprt status code.
120 * @param pszMode The open mode. See fopen() standard.
121 * Format: <a|r|w>[+][b|t][x][e|N|E]
122 * - 'a': Open or create file and writes
123 * append tos it.
124 * - 'r': Open existing file and read from it.
125 * - 'w': Open or truncate existing file and write
126 * to it.
127 * - '+': Open for both read and write access.
128 * - 'b' / 't': binary / text
129 * - 'x': exclusively create, no open. Only
130 * possible with 'w'.
131 * - 'e' / 'N': No inherit on exec. (The 'e' is
132 * how Linux and FreeBSD expresses this, the
133 * latter is Visual C++).
134 * @param ppStream Where to store the opened stream.
135 * @param pszFilenameFmt Filename path format string.
136 * @param ... Arguments to the format string.
137 */
138RTR3DECL(int) RTStrmOpenF(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
139
140/**
141 * Opens a file stream for a RTFILE handle, taking ownership of the handle.
142 *
143 * @returns iprt status code.
144 * @param hFile The file handle to use. On success, handle
145 * ownership is transfered to the stream and it will be
146 * closed when the stream closes.
147 * @param pszMode The open mode, accept the same as RTStrOpen and
148 * friends however it is only used to figure out what
149 * we can do with the handle.
150 * @param fFlags Reserved, must be zero.
151 * @param ppStream Where to store the opened stream.
152 */
153RTR3DECL(int) RTStrmOpenFileHandle(RTFILE hFile, const char *pszMode, uint32_t fFlags, PRTSTREAM *ppStream);
154
155/**
156 * Queries the file handle backing the stream.
157 *
158 * @returns iprt status code.
159 * @retval VERR_NOT_AVAILABLE if the stream has no valid handle associated with
160 * it.
161 *
162 * @param pStream The stream.
163 * @param phFile Where to return the file handle. This should not be
164 * closed!
165 */
166RTR3DECL(int) RTStrmQueryFileHandle(PRTSTREAM pStream, PRTFILE phFile);
167
168/**
169 * Closes the specified stream.
170 *
171 * @returns iprt status code.
172 * @param pStream The stream to close.
173 *
174 * @note The stream will be closed and freed even when failure is returned.
175 * It cannot be used again after this call. The error status is only
176 * to indicate that the flushing of buffers or the closing of the
177 * underlying file handle failed.
178 */
179RTR3DECL(int) RTStrmClose(PRTSTREAM pStream);
180
181/**
182 * Get the pending error of the stream.
183 *
184 * @returns iprt status code. of the stream.
185 * @param pStream The stream.
186 */
187RTR3DECL(int) RTStrmError(PRTSTREAM pStream);
188
189/**
190 * Clears stream error condition.
191 *
192 * All stream operations save RTStrmClose and this will fail
193 * while an error is asserted on the stream
194 *
195 * @returns iprt status code.
196 * @param pStream The stream.
197 */
198RTR3DECL(int) RTStrmClearError(PRTSTREAM pStream);
199
200/**
201 * Changes the stream mode.
202 *
203 * @returns iprt status code.
204 * @param pStream The stream.
205 * @param fBinary The desired binary (@c true) / text mode (@c false).
206 * Pass -1 to leave it unchanged.
207 * @param fCurrentCodeSet Whether converting the stream from UTF-8 to the
208 * current code set is desired (@c true) or not (@c
209 * false). Pass -1 to leave this property unchanged.
210 */
211RTR3DECL(int) RTStrmSetMode(PRTSTREAM pStream, int fBinary, int fCurrentCodeSet);
212
213/** Stream buffering modes. */
214typedef enum RTSTRMBUFMODE
215{
216 RTSTRMBUFMODE_INVALID = 0,
217 RTSTRMBUFMODE_FULL, /**< Full buffering. */
218 RTSTRMBUFMODE_LINE, /**< Line buffering. On Windows this could be the same as RTSTRMBUFMODE_FULL. */
219 RTSTRMBUFMODE_UNBUFFERED, /**< No buffering. */
220 RTSTRMBUFMODE_END,
221 RTSTRMBUFMODE_32BIT_HACK = 0x7fffffff
222} RTSTRMBUFMODE;
223
224/**
225 * Changes the stream buffering mode.
226 *
227 * @returns iprt status code.
228 * @param pStream The stream.
229 * @param enmBufMode The new buffering mode.
230 */
231RTR3DECL(int) RTStrmSetBufferingMode(PRTSTREAM pStream, RTSTRMBUFMODE enmBufMode);
232
233/**
234 * Returns the current echo mode.
235 *
236 * This works only for standard input streams.
237 *
238 * @returns iprt status code.
239 * @retval VERR_INVALID_FUNCTION if not a TTY.
240 * @param pStream The stream.
241 * @param pfEchoChars Where to store the flag whether typed characters are echoed.
242 */
243RTR3DECL(int) RTStrmInputGetEchoChars(PRTSTREAM pStream, bool *pfEchoChars);
244
245/**
246 * Changes the behavior for echoing inpit characters on the command line.
247 *
248 * This works only for standard input streams.
249 *
250 * @returns iprt status code.
251 * @retval VERR_INVALID_FUNCTION if not a TTY.
252 * @param pStream The stream.
253 * @param fEchoChars Flag whether echoing typed characters is wanted.
254 */
255RTR3DECL(int) RTStrmInputSetEchoChars(PRTSTREAM pStream, bool fEchoChars);
256
257/**
258 * Checks if this is a terminal (TTY) or not.
259 *
260 * @returns true if it is, false if it isn't or the stream isn't valid.
261 * @param pStream The stream.
262 */
263RTR3DECL(bool) RTStrmIsTerminal(PRTSTREAM pStream);
264
265/**
266 * Gets the width of the terminal the stream is associated with.
267 *
268 * @returns IPRT status code.
269 * @retval VERR_INVALID_FUNCTION if not connected to a terminal.
270 * @param pStream The stream.
271 * @param pcchWidth Where to return the width. This will never be zero
272 * and always be set, even on error.
273 */
274RTR3DECL(int) RTStrmQueryTerminalWidth(PRTSTREAM pStream, uint32_t *pcchWidth);
275
276/**
277 * Rewinds the stream.
278 *
279 * Stream errors will be reset on success.
280 *
281 * @returns IPRT status code.
282 *
283 * @param pStream The stream.
284 *
285 * @remarks Not all streams are rewindable and that behavior is currently
286 * undefined for those.
287 */
288RTR3DECL(int) RTStrmRewind(PRTSTREAM pStream);
289
290/**
291 * Changes the file position.
292 *
293 * @returns IPRT status code.
294 *
295 * @param pStream The stream.
296 * @param off The seek offset.
297 * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
298 *
299 * @remarks Not all streams are seekable and that behavior is currently
300 * undefined for those.
301 */
302RTR3DECL(int) RTStrmSeek(PRTSTREAM pStream, RTFOFF off, uint32_t uMethod);
303
304/**
305 * Tells the stream position.
306 *
307 * @returns Stream position or IPRT error status. Non-negative numbers are
308 * stream positions, while negative numbers are IPRT error stauses.
309 *
310 * @param pStream The stream.
311 *
312 * @remarks Not all streams have a position and that behavior is currently
313 * undefined for those.
314 */
315RTR3DECL(RTFOFF) RTStrmTell(PRTSTREAM pStream);
316
317/**
318 * Reads from a file stream.
319 *
320 * @returns iprt status code.
321 * @param pStream The stream.
322 * @param pvBuf Where to put the read bits.
323 * Must be cbRead bytes or more.
324 * @param cbToRead Number of bytes to read.
325 * @param pcbRead Where to store the number of bytes actually read.
326 * If NULL cbRead bytes are read or an error is returned.
327 */
328RTR3DECL(int) RTStrmReadEx(PRTSTREAM pStream, void *pvBuf, size_t cbToRead, size_t *pcbRead);
329
330/**
331 * Writes to a file stream.
332 *
333 * @returns iprt status code.
334 * @param pStream The stream.
335 * @param pvBuf Where to get the bits to write from.
336 * @param cbToWrite Number of bytes to write.
337 * @param pcbWritten Where to store the number of bytes actually written.
338 * If NULL cbWrite bytes are written or an error is returned.
339 */
340RTR3DECL(int) RTStrmWriteEx(PRTSTREAM pStream, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
341
342/**
343 * Reads from a file stream.
344 *
345 * @returns iprt status code.
346 * @param pStream The stream.
347 * @param pvBuf Where to put the read bits.
348 * Must be cbRead bytes or more.
349 * @param cbToRead Number of bytes to read.
350 */
351DECLINLINE(int) RTStrmRead(PRTSTREAM pStream, void *pvBuf, size_t cbToRead)
352{
353 return RTStrmReadEx(pStream, pvBuf, cbToRead, NULL);
354}
355
356/**
357 * Writes to a file stream.
358 *
359 * @returns iprt status code.
360 * @param pStream The stream.
361 * @param pvBuf Where to get the bits to write from.
362 * @param cbToWrite Number of bytes to write.
363 */
364DECLINLINE(int) RTStrmWrite(PRTSTREAM pStream, const void *pvBuf, size_t cbToWrite)
365{
366 return RTStrmWriteEx(pStream, pvBuf, cbToWrite, NULL);
367}
368
369/**
370 * Reads a character from a file stream.
371 *
372 * @returns The char as an unsigned char cast to int.
373 * @returns -1 on failure.
374 * @param pStream The stream.
375 */
376RTR3DECL(int) RTStrmGetCh(PRTSTREAM pStream);
377
378/**
379 * Writes a character to a file stream.
380 *
381 * @returns iprt status code.
382 * @param pStream The stream.
383 * @param ch The char to write.
384 */
385RTR3DECL(int) RTStrmPutCh(PRTSTREAM pStream, int ch);
386
387/**
388 * Writes a string to a file stream.
389 *
390 * @returns iprt status code.
391 * @param pStream The stream.
392 * @param pszString The string to write.
393 * No newlines or anything are appended or prepended.
394 * The terminating '\\0' is not written, of course.
395 */
396RTR3DECL(int) RTStrmPutStr(PRTSTREAM pStream, const char *pszString);
397
398/**
399 * Reads a line from a file stream.
400 *
401 * A line ends with a '\\n', '\\r\\n', '\\0' or the end of the file.
402 *
403 * @returns iprt status code.
404 * @retval VINF_BUFFER_OVERFLOW if the buffer wasn't big enough to read an
405 * entire line.
406 * @retval VERR_BUFFER_OVERFLOW if a lone '\\r' was encountered at the end of
407 * the buffer and we ended up dropping the following character.
408 *
409 * @param pStream The stream.
410 * @param pszString Where to store the line.
411 * The line will *NOT* contain any '\\n'.
412 * @param cbString The size of the string buffer.
413 */
414RTR3DECL(int) RTStrmGetLine(PRTSTREAM pStream, char *pszString, size_t cbString);
415
416/**
417 * Flushes a stream.
418 *
419 * @returns iprt status code.
420 * @param pStream The stream to flush.
421 */
422RTR3DECL(int) RTStrmFlush(PRTSTREAM pStream);
423
424/**
425 * Prints a formatted string to the specified stream.
426 *
427 * @returns Number of bytes printed.
428 * @param pStream The stream to print to.
429 * @param pszFormat Runtime format string.
430 * @param ... Arguments specified by pszFormat.
431 */
432RTR3DECL(int) RTStrmPrintf(PRTSTREAM pStream, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
433
434/**
435 * Prints a formatted string to the specified stream.
436 *
437 * @returns Number of bytes printed.
438 * @param pStream The stream to print to.
439 * @param pszFormat Runtime format string.
440 * @param args Arguments specified by pszFormat.
441 */
442RTR3DECL(int) RTStrmPrintfV(PRTSTREAM pStream, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(2, 0);
443
444/**
445 * Prints a formatted string to the specified stream, performing wrapping of
446 * lines considered too long.
447 *
448 * If the stream is to a terminal, the terminal width is used as the max line
449 * width. Otherwise, the width is taken from @a fFlags
450 * (RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_MASK /
451 * RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_SHIFT), defaulting to 80 if zero.
452 *
453 * @returns Low 16 bits is the line offset, high 16 bits the number of lines
454 * outputted. Apply RTSTRMWRAPPED_F_LINE_OFFSET_MASK to the value and
455 * it can be passed via @a fFlags to the next invocation (not necessary
456 * if all format strings ends with a newline).
457 * Negative values are IPRT error status codes.
458 * @param pStream The stream to print to.
459 * @param fFlags RTSTRMWRAPPED_F_XXX - flags, configuration and state.
460 * @param pszFormat Runtime format string.
461 * @param ... Arguments specified by pszFormat.
462 * @sa RTStrmWrappedPrintfV, RTStrmPrintf, RTStrmPrintfV
463 */
464RTDECL(int32_t) RTStrmWrappedPrintf(PRTSTREAM pStream, uint32_t fFlags, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
465
466/**
467 * Prints a formatted string to the specified stream, performing wrapping of
468 * lines considered too long.
469 *
470 * If the stream is to a terminal, the terminal width is used as the max line
471 * width. Otherwise, the width is taken from @a fFlags
472 * (RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_MASK /
473 * RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_SHIFT), defaulting to 80 if zero.
474 *
475 * @returns Low 16 bits is the line offset, high 16 bits the number of lines
476 * outputted. Apply RTSTRMWRAPPED_F_LINE_OFFSET_MASK to the value and
477 * it can be passed via @a fFlags to the next invocation (not necessary
478 * if all format strings ends with a newline).
479 * Negative values are IPRT error status codes.
480 * @param pStream The stream to print to.
481 * @param fFlags RTSTRMWRAPPED_F_XXX - flags, configuration and state.
482 * @param pszFormat Runtime format string.
483 * @param va Arguments specified by pszFormat.
484 * @sa RTStrmWrappedPrintf, RTStrmPrintf, RTStrmPrintfV
485 */
486RTDECL(int32_t) RTStrmWrappedPrintfV(PRTSTREAM pStream, uint32_t fFlags, const char *pszFormat,
487 va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
488
489/** @name RTSTRMWRAPPED_F_XXX - Flags for RTStrmWrappedPrintf &
490 * RTStrmWrappedPrintfV.
491 * @{ */
492/** The current line offset mask.
493 * This should be used to passed the line off state from one call to the next
494 * when printing incomplete lines. If all format strings ends with a newline,
495 * this is not necessary. */
496#define RTSTRMWRAPPED_F_LINE_OFFSET_MASK UINT32_C(0x00000fff)
497/** The non-terminal width mask. Defaults to 80 if not specified (zero). */
498#define RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_MASK UINT32_C(0x000ff000)
499/** The non-terminal width shift. */
500#define RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_SHIFT 12
501/** The hanging indent level mask - defaults to 4 if zero.
502 * Used when RTSTRMWRAPPED_F_HANGING_INDENT is set. */
503#define RTSTRMWRAPPED_F_HANGING_INDENT_MASK UINT32_C(0x01f00000)
504/** The hanging indent level shift. */
505#define RTSTRMWRAPPED_F_HANGING_INDENT_SHIFT 20
506/** Hanging indent. Used for command synopsis and such. */
507#define RTSTRMWRAPPED_F_HANGING_INDENT UINT32_C(0x80000000)
508/** @} */
509
510/**
511 * Dumper vprintf-like function outputting to a stream.
512 *
513 * @param pvUser The stream to print to. NULL means standard output.
514 * @param pszFormat Runtime format string.
515 * @param va Arguments specified by pszFormat.
516 */
517RTR3DECL(void) RTStrmDumpPrintfV(void *pvUser, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
518
519/**
520 * Prints a formatted string to the standard output stream (g_pStdOut).
521 *
522 * @returns Number of bytes printed.
523 * @param pszFormat Runtime format string.
524 * @param ... Arguments specified by pszFormat.
525 */
526RTR3DECL(int) RTPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
527
528/**
529 * Prints a formatted string to the standard output stream (g_pStdOut).
530 *
531 * @returns Number of bytes printed.
532 * @param pszFormat Runtime format string.
533 * @param args Arguments specified by pszFormat.
534 */
535RTR3DECL(int) RTPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
536
537/** @} */
538
539RT_C_DECLS_END
540
541#endif /* !IPRT_INCLUDED_stream_h */
542
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