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