stream.h@ 101665

Last change on this file since 101665 was 98103, checked in by vboxsync, 22 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
46	RT_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. */
55	typedef struct RTSTREAM *PRTSTREAM;
56	#endif
57
58	/** Pointer to the standard input stream. */
59	extern RTDATADECL(PRTSTREAM) g_pStdIn;
60
61	/** Pointer to the standard error stream. */
62	extern RTDATADECL(PRTSTREAM) g_pStdErr;
63
64	/** Pointer to the standard output stream. */
65	extern 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	*/
89	RTR3DECL(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	*/
113	RTR3DECL(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	*/
138	RTR3DECL(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	*/
153	RTR3DECL(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	*/
166	RTR3DECL(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	*/
179	RTR3DECL(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	*/
187	RTR3DECL(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	*/
198	RTR3DECL(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	*/
211	RTR3DECL(int) RTStrmSetMode(PRTSTREAM pStream, int fBinary, int fCurrentCodeSet);
212
213	/** Stream buffering modes. */
214	typedef 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	*/
231	RTR3DECL(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	*/
243	RTR3DECL(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	*/
255	RTR3DECL(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	*/
263	RTR3DECL(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	*/
274	RTR3DECL(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	*/
288	RTR3DECL(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	*/
302	RTR3DECL(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	*/
315	RTR3DECL(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	*/
328	RTR3DECL(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	*/
340	RTR3DECL(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	*/
351	DECLINLINE(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	*/
364	DECLINLINE(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	*/
376	RTR3DECL(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	*/
385	RTR3DECL(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	*/
396	RTR3DECL(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	*/
414	RTR3DECL(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	*/
422	RTR3DECL(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	*/
432	RTR3DECL(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	*/
442	RTR3DECL(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	*/
464	RTDECL(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	*/
486	RTDECL(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	*/
517	RTR3DECL(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	*/
526	RTR3DECL(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	*/
535	RTR3DECL(int) RTPrintfV(const char *pszFormat, va_list args) RT_IPRT_FORMAT_ATTR(1, 0);
536
537	/** @} */
538
539	RT_C_DECLS_END
540
541	#endif /* !IPRT_INCLUDED_stream_h */
542

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: