1
0
Fork 0
virtualbox/include/iprt/stream.h
Daniel Baumann df1bda4fe9
Adding upstream version 7.0.20-dfsg.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
2025-06-22 09:56:04 +02:00

542 lines
20 KiB
C

/** @file
* IPRT - I/O Stream.
*/
/*
* Copyright (C) 2006-2023 Oracle and/or its affiliates.
*
* This file is part of VirtualBox base platform packages, as
* available from https://www.virtualbox.org.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, in version 3 of the
* License.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see <https://www.gnu.org/licenses>.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
* in the VirtualBox distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
*/
#ifndef IPRT_INCLUDED_stream_h
#define IPRT_INCLUDED_stream_h
#ifndef RT_WITHOUT_PRAGMA_ONCE
# pragma once
#endif
#include <iprt/cdefs.h>
#include <iprt/types.h>
#include <iprt/stdarg.h>
RT_C_DECLS_BEGIN
/** @defgroup grp_rt_stream RTStrm - File Streams
* @ingroup grp_rt
* @{
*/
#ifndef IPRT_INCLUDED_message_h
/** Pointer to a stream. */
typedef struct RTSTREAM *PRTSTREAM;
#endif
/** Pointer to the standard input stream. */
extern RTDATADECL(PRTSTREAM) g_pStdIn;
/** Pointer to the standard error stream. */
extern RTDATADECL(PRTSTREAM) g_pStdErr;
/** Pointer to the standard output stream. */
extern RTDATADECL(PRTSTREAM) g_pStdOut;
/**
* Opens a file stream.
*
* @returns iprt status code.
* @param pszFilename Path to the file to open.
* @param pszMode The open mode. See fopen() standard.
* Format: <a|r|w>[+][b|t][x][e|N|E]
* - 'a': Open or create file and writes
* append tos it.
* - 'r': Open existing file and read from it.
* - 'w': Open or truncate existing file and write
* to it.
* - '+': Open for both read and write access.
* - 'b' / 't': binary / text
* - 'x': exclusively create, no open. Only
* possible with 'w'.
* - 'e' / 'N': No inherit on exec. (The 'e' is
* how Linux and FreeBSD expresses this, the
* latter is Visual C++).
* @param ppStream Where to store the opened stream.
*/
RTR3DECL(int) RTStrmOpen(const char *pszFilename, const char *pszMode, PRTSTREAM *ppStream);
/**
* Opens a file stream.
*
* @returns iprt status code.
* @param pszMode The open mode. See fopen() standard.
* Format: <a|r|w>[+][b|t][x][e|N|E]
* - 'a': Open or create file and writes
* append tos it.
* - 'r': Open existing file and read from it.
* - 'w': Open or truncate existing file and write
* to it.
* - '+': Open for both read and write access.
* - 'b' / 't': binary / text
* - 'x': exclusively create, no open. Only
* possible with 'w'.
* - 'e' / 'N': No inherit on exec. (The 'e' is
* how Linux and FreeBSD expresses this, the
* latter is Visual C++).
* @param ppStream Where to store the opened stream.
* @param pszFilenameFmt Filename path format string.
* @param args Arguments to the format string.
*/
RTR3DECL(int) RTStrmOpenFV(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt,
va_list args) RT_IPRT_FORMAT_ATTR(3, 0);
/**
* Opens a file stream.
*
* @returns iprt status code.
* @param pszMode The open mode. See fopen() standard.
* Format: <a|r|w>[+][b|t][x][e|N|E]
* - 'a': Open or create file and writes
* append tos it.
* - 'r': Open existing file and read from it.
* - 'w': Open or truncate existing file and write
* to it.
* - '+': Open for both read and write access.
* - 'b' / 't': binary / text
* - 'x': exclusively create, no open. Only
* possible with 'w'.
* - 'e' / 'N': No inherit on exec. (The 'e' is
* how Linux and FreeBSD expresses this, the
* latter is Visual C++).
* @param ppStream Where to store the opened stream.
* @param pszFilenameFmt Filename path format string.
* @param ... Arguments to the format string.
*/
RTR3DECL(int) RTStrmOpenF(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, ...) RT_IPRT_FORMAT_ATTR(3, 4);
/**
* Opens a file stream for a RTFILE handle, taking ownership of the handle.
*
* @returns iprt status code.
* @param hFile The file handle to use. On success, handle
* ownership is transfered to the stream and it will be
* closed when the stream closes.
* @param pszMode The open mode, accept the same as RTStrOpen and
* friends however it is only used to figure out what
* we can do with the handle.
* @param fFlags Reserved, must be zero.
* @param ppStream Where to store the opened stream.
*/
RTR3DECL(int) RTStrmOpenFileHandle(RTFILE hFile, const char *pszMode, uint32_t fFlags, PRTSTREAM *ppStream);
/**
* Queries the file handle backing the stream.
*
* @returns iprt status code.
* @retval VERR_NOT_AVAILABLE if the stream has no valid handle associated with
* it.
*
* @param pStream The stream.
* @param phFile Where to return the file handle. This should not be
* closed!
*/
RTR3DECL(int) RTStrmQueryFileHandle(PRTSTREAM pStream, PRTFILE phFile);
/**
* Closes the specified stream.
*
* @returns iprt status code.
* @param pStream The stream to close.
*
* @note The stream will be closed and freed even when failure is returned.
* It cannot be used again after this call. The error status is only
* to indicate that the flushing of buffers or the closing of the
* underlying file handle failed.
*/
RTR3DECL(int) RTStrmClose(PRTSTREAM pStream);
/**
* Get the pending error of the stream.
*
* @returns iprt status code. of the stream.
* @param pStream The stream.
*/
RTR3DECL(int) RTStrmError(PRTSTREAM pStream);
/**
* Clears stream error condition.
*
* All stream operations save RTStrmClose and this will fail
* while an error is asserted on the stream
*
* @returns iprt status code.
* @param pStream The stream.
*/
RTR3DECL(int) RTStrmClearError(PRTSTREAM pStream);
/**
* Changes the stream mode.
*
* @returns iprt status code.
* @param pStream The stream.
* @param fBinary The desired binary (@c true) / text mode (@c false).
* Pass -1 to leave it unchanged.
* @param fCurrentCodeSet Whether converting the stream from UTF-8 to the
* current code set is desired (@c true) or not (@c
* false). Pass -1 to leave this property unchanged.
*/
RTR3DECL(int) RTStrmSetMode(PRTSTREAM pStream, int fBinary, int fCurrentCodeSet);
/** Stream buffering modes. */
typedef enum RTSTRMBUFMODE
{
RTSTRMBUFMODE_INVALID = 0,
RTSTRMBUFMODE_FULL, /**< Full buffering. */
RTSTRMBUFMODE_LINE, /**< Line buffering. On Windows this could be the same as RTSTRMBUFMODE_FULL. */
RTSTRMBUFMODE_UNBUFFERED, /**< No buffering. */
RTSTRMBUFMODE_END,
RTSTRMBUFMODE_32BIT_HACK = 0x7fffffff
} RTSTRMBUFMODE;
/**
* Changes the stream buffering mode.
*
* @returns iprt status code.
* @param pStream The stream.
* @param enmBufMode The new buffering mode.
*/
RTR3DECL(int) RTStrmSetBufferingMode(PRTSTREAM pStream, RTSTRMBUFMODE enmBufMode);
/**
* Returns the current echo mode.
*
* This works only for standard input streams.
*
* @returns iprt status code.
* @retval VERR_INVALID_FUNCTION if not a TTY.
* @param pStream The stream.
* @param pfEchoChars Where to store the flag whether typed characters are echoed.
*/
RTR3DECL(int) RTStrmInputGetEchoChars(PRTSTREAM pStream, bool *pfEchoChars);
/**
* Changes the behavior for echoing inpit characters on the command line.
*
* This works only for standard input streams.
*
* @returns iprt status code.
* @retval VERR_INVALID_FUNCTION if not a TTY.
* @param pStream The stream.
* @param fEchoChars Flag whether echoing typed characters is wanted.
*/
RTR3DECL(int) RTStrmInputSetEchoChars(PRTSTREAM pStream, bool fEchoChars);
/**
* Checks if this is a terminal (TTY) or not.
*
* @returns true if it is, false if it isn't or the stream isn't valid.
* @param pStream The stream.
*/
RTR3DECL(bool) RTStrmIsTerminal(PRTSTREAM pStream);
/**
* Gets the width of the terminal the stream is associated with.
*
* @returns IPRT status code.
* @retval VERR_INVALID_FUNCTION if not connected to a terminal.
* @param pStream The stream.
* @param pcchWidth Where to return the width. This will never be zero
* and always be set, even on error.
*/
RTR3DECL(int) RTStrmQueryTerminalWidth(PRTSTREAM pStream, uint32_t *pcchWidth);
/**
* Rewinds the stream.
*
* Stream errors will be reset on success.
*
* @returns IPRT status code.
*
* @param pStream The stream.
*
* @remarks Not all streams are rewindable and that behavior is currently
* undefined for those.
*/
RTR3DECL(int) RTStrmRewind(PRTSTREAM pStream);
/**
* Changes the file position.
*
* @returns IPRT status code.
*
* @param pStream The stream.
* @param off The seek offset.
* @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
*
* @remarks Not all streams are seekable and that behavior is currently
* undefined for those.
*/
RTR3DECL(int) RTStrmSeek(PRTSTREAM pStream, RTFOFF off, uint32_t uMethod);
/**
* Tells the stream position.
*
* @returns Stream position or IPRT error status. Non-negative numbers are
* stream positions, while negative numbers are IPRT error stauses.
*
* @param pStream The stream.
*
* @remarks Not all streams have a position and that behavior is currently
* undefined for those.
*/
RTR3DECL(RTFOFF) RTStrmTell(PRTSTREAM pStream);
/**
* Reads from a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to put the read bits.
* Must be cbRead bytes or more.
* @param cbToRead Number of bytes to read.
* @param pcbRead Where to store the number of bytes actually read.
* If NULL cbRead bytes are read or an error is returned.
*/
RTR3DECL(int) RTStrmReadEx(PRTSTREAM pStream, void *pvBuf, size_t cbToRead, size_t *pcbRead);
/**
* Writes to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to get the bits to write from.
* @param cbToWrite Number of bytes to write.
* @param pcbWritten Where to store the number of bytes actually written.
* If NULL cbWrite bytes are written or an error is returned.
*/
RTR3DECL(int) RTStrmWriteEx(PRTSTREAM pStream, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
/**
* Reads from a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to put the read bits.
* Must be cbRead bytes or more.
* @param cbToRead Number of bytes to read.
*/
DECLINLINE(int) RTStrmRead(PRTSTREAM pStream, void *pvBuf, size_t cbToRead)
{
return RTStrmReadEx(pStream, pvBuf, cbToRead, NULL);
}
/**
* Writes to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pvBuf Where to get the bits to write from.
* @param cbToWrite Number of bytes to write.
*/
DECLINLINE(int) RTStrmWrite(PRTSTREAM pStream, const void *pvBuf, size_t cbToWrite)
{
return RTStrmWriteEx(pStream, pvBuf, cbToWrite, NULL);
}
/**
* Reads a character from a file stream.
*
* @returns The char as an unsigned char cast to int.
* @returns -1 on failure.
* @param pStream The stream.
*/
RTR3DECL(int) RTStrmGetCh(PRTSTREAM pStream);
/**
* Writes a character to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param ch The char to write.
*/
RTR3DECL(int) RTStrmPutCh(PRTSTREAM pStream, int ch);
/**
* Writes a string to a file stream.
*
* @returns iprt status code.
* @param pStream The stream.
* @param pszString The string to write.
* No newlines or anything are appended or prepended.
* The terminating '\\0' is not written, of course.
*/
RTR3DECL(int) RTStrmPutStr(PRTSTREAM pStream, const char *pszString);
/**
* Reads a line from a file stream.
*
* A line ends with a '\\n', '\\r\\n', '\\0' or the end of the file.
*
* @returns iprt status code.
* @retval VINF_BUFFER_OVERFLOW if the buffer wasn't big enough to read an
* entire line.
* @retval VERR_BUFFER_OVERFLOW if a lone '\\r' was encountered at the end of
* the buffer and we ended up dropping the following character.
*
* @param pStream The stream.
* @param pszString Where to store the line.
* The line will *NOT* contain any '\\n'.
* @param cbString The size of the string buffer.
*/
RTR3DECL(int) RTStrmGetLine(PRTSTREAM pStream, char *pszString, size_t cbString);
/**
* Flushes a stream.
*
* @returns iprt status code.
* @param pStream The stream to flush.
*/
RTR3DECL(int) RTStrmFlush(PRTSTREAM pStream);
/**
* Prints a formatted string to the specified stream.
*
* @returns Number of bytes printed.
* @param pStream The stream to print to.
* @param pszFormat Runtime format string.
* @param ... Arguments specified by pszFormat.
*/
RTR3DECL(int) RTStrmPrintf(PRTSTREAM pStream, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
/**
* Prints a formatted string to the specified stream.
*
* @returns Number of bytes printed.
* @param pStream The stream to print to.
* @param pszFormat Runtime format string.
* @param args Arguments specified by pszFormat.
*/
RTR3DECL(int) RTStrmPrintfV(PRTSTREAM pStream, const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(2, 0);
/**
* Prints a formatted string to the specified stream, performing wrapping of
* lines considered too long.
*
* If the stream is to a terminal, the terminal width is used as the max line
* width. Otherwise, the width is taken from @a fFlags
* (RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_MASK /
* RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_SHIFT), defaulting to 80 if zero.
*
* @returns Low 16 bits is the line offset, high 16 bits the number of lines
* outputted. Apply RTSTRMWRAPPED_F_LINE_OFFSET_MASK to the value and
* it can be passed via @a fFlags to the next invocation (not necessary
* if all format strings ends with a newline).
* Negative values are IPRT error status codes.
* @param pStream The stream to print to.
* @param fFlags RTSTRMWRAPPED_F_XXX - flags, configuration and state.
* @param pszFormat Runtime format string.
* @param ... Arguments specified by pszFormat.
* @sa RTStrmWrappedPrintfV, RTStrmPrintf, RTStrmPrintfV
*/
RTDECL(int32_t) RTStrmWrappedPrintf(PRTSTREAM pStream, uint32_t fFlags, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(3, 4);
/**
* Prints a formatted string to the specified stream, performing wrapping of
* lines considered too long.
*
* If the stream is to a terminal, the terminal width is used as the max line
* width. Otherwise, the width is taken from @a fFlags
* (RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_MASK /
* RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_SHIFT), defaulting to 80 if zero.
*
* @returns Low 16 bits is the line offset, high 16 bits the number of lines
* outputted. Apply RTSTRMWRAPPED_F_LINE_OFFSET_MASK to the value and
* it can be passed via @a fFlags to the next invocation (not necessary
* if all format strings ends with a newline).
* Negative values are IPRT error status codes.
* @param pStream The stream to print to.
* @param fFlags RTSTRMWRAPPED_F_XXX - flags, configuration and state.
* @param pszFormat Runtime format string.
* @param va Arguments specified by pszFormat.
* @sa RTStrmWrappedPrintf, RTStrmPrintf, RTStrmPrintfV
*/
RTDECL(int32_t) RTStrmWrappedPrintfV(PRTSTREAM pStream, uint32_t fFlags, const char *pszFormat,
va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
/** @name RTSTRMWRAPPED_F_XXX - Flags for RTStrmWrappedPrintf &
* RTStrmWrappedPrintfV.
* @{ */
/** The current line offset mask.
* This should be used to passed the line off state from one call to the next
* when printing incomplete lines. If all format strings ends with a newline,
* this is not necessary. */
#define RTSTRMWRAPPED_F_LINE_OFFSET_MASK UINT32_C(0x00000fff)
/** The non-terminal width mask. Defaults to 80 if not specified (zero). */
#define RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_MASK UINT32_C(0x000ff000)
/** The non-terminal width shift. */
#define RTSTRMWRAPPED_F_NON_TERMINAL_WIDTH_SHIFT 12
/** The hanging indent level mask - defaults to 4 if zero.
* Used when RTSTRMWRAPPED_F_HANGING_INDENT is set. */
#define RTSTRMWRAPPED_F_HANGING_INDENT_MASK UINT32_C(0x01f00000)
/** The hanging indent level shift. */
#define RTSTRMWRAPPED_F_HANGING_INDENT_SHIFT 20
/** Hanging indent. Used for command synopsis and such. */
#define RTSTRMWRAPPED_F_HANGING_INDENT UINT32_C(0x80000000)
/** @} */
/**
* Dumper vprintf-like function outputting to a stream.
*
* @param pvUser The stream to print to. NULL means standard output.
* @param pszFormat Runtime format string.
* @param va Arguments specified by pszFormat.
*/
RTR3DECL(void) RTStrmDumpPrintfV(void *pvUser, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
/**
* Prints a formatted string to the standard output stream (g_pStdOut).
*
* @returns Number of bytes printed.
* @param pszFormat Runtime format string.
* @param ... Arguments specified by pszFormat.
*/
RTR3DECL(int) RTPrintf(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
/**
* Prints a formatted string to the standard output stream (g_pStdOut).
*
* @returns Number of bytes printed.
* @param pszFormat Runtime format string.
* @param args Arguments specified by pszFormat.
*/
RTR3DECL(int) RTPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
/** @} */
RT_C_DECLS_END
#endif /* !IPRT_INCLUDED_stream_h */