VirtualBox

source: vbox/trunk/include/iprt/message.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: 13.7 KB
Line 
1/** @file
2 * IPRT - Message Formatting.
3 */
4
5/*
6 * Copyright (C) 2009-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_message_h
37#define IPRT_INCLUDED_message_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_msg RTMsg - Message Formatting
49 * @ingroup grp_rt
50 * @{
51 */
52
53/**
54 * Sets the program name to use.
55 *
56 * @returns IPRT status code.
57 * @param pszFormat The program name format string.
58 * @param ... Format arguments.
59 */
60RTDECL(int) RTMsgSetProgName(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
61
62/**
63 * Print error message to standard error.
64 *
65 * The message will be prefixed with the file name part of process image name
66 * (i.e. no path) and "error: ". If the message doesn't end with a new line,
67 * one will be added. The caller should call this with an empty string if
68 * unsure whether the cursor is currently position at the start of a new line.
69 *
70 * @returns IPRT status code.
71 * @param pszFormat The message format string.
72 * @param ... Format arguments.
73 */
74RTDECL(int) RTMsgError(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
75
76/**
77 * Print error message to standard error.
78 *
79 * The message will be prefixed with the file name part of process image name
80 * (i.e. no path) and "error: ". If the message doesn't end with a new line,
81 * one will be added. The caller should call this with an empty string if
82 * unsure whether the cursor is currently position at the start of a new line.
83 *
84 * @returns IPRT status code.
85 * @param pszFormat The message format string.
86 * @param va Format arguments.
87 */
88RTDECL(int) RTMsgErrorV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
89
90/**
91 * Same as RTMsgError() except for the return value.
92 *
93 * @returns @a enmExitCode
94 * @param enmExitCode What to exit code to return. This is mainly for
95 * saving some vertical space in the source file.
96 * @param pszFormat The message format string.
97 * @param ... Format arguments.
98 */
99RTDECL(RTEXITCODE) RTMsgErrorExit(RTEXITCODE enmExitCode, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
100
101/**
102 * Same as RTMsgErrorV() except for the return value.
103 *
104 * @returns @a enmExitCode
105 * @param enmExitCode What to exit code to return. This is mainly for
106 * saving some vertical space in the source file.
107 * @param pszFormat The message format string.
108 * @param va Format arguments.
109 */
110RTDECL(RTEXITCODE) RTMsgErrorExitV(RTEXITCODE enmExitCode, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
111
112/**
113 * Same as RTMsgError() except for always returning RTEXITCODE_FAILURE.
114 *
115 * @returns RTEXITCODE_FAILURE
116 * @param pszFormat The message format string.
117 * @param ... Format arguments.
118 */
119RTDECL(RTEXITCODE) RTMsgErrorExitFailure(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
120
121/**
122 * Same as RTMsgErrorV() except for always returning RTEXITCODE_FAILURE.
123 *
124 * @returns RTEXITCODE_FAILURE
125 * @param pszFormat The message format string.
126 * @param va Format arguments.
127 */
128RTDECL(RTEXITCODE) RTMsgErrorExitFailureV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
129
130/**
131 * Same as RTMsgError() except for the return value.
132 *
133 * @returns @a rcRet
134 * @param rcRet What IPRT status to return. This is mainly for
135 * saving some vertical space in the source file.
136 * @param pszFormat The message format string.
137 * @param ... Format arguments.
138 */
139RTDECL(int) RTMsgErrorRc(int rcRet, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
140
141/**
142 * Same as RTMsgErrorV() except for the return value.
143 *
144 * @returns @a rcRet
145 * @param rcRet What IPRT status to return. This is mainly for
146 * saving some vertical space in the source file.
147 * @param pszFormat The message format string.
148 * @param va Format arguments.
149 */
150RTDECL(int) RTMsgErrorRcV(int rcRet, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
151
152/**
153 * For reporting syntax errors.
154 *
155 * @returns RTEXITCODE_SYNTAX
156 * @param pszFormat The message format string. Newline not needed.
157 * @param ... Format arguments.
158 */
159RTDECL(RTEXITCODE) RTMsgSyntax(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
160
161/**
162 * For reporting syntax errors.
163 *
164 * @returns RTEXITCODE_SYNTAX
165 * @param pszFormat The message format string. Newline not needed.
166 * @param va Format arguments.
167 */
168RTDECL(RTEXITCODE) RTMsgSyntaxV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
169
170/**
171 * Print an error message for a RTR3Init failure and suggest an exit code.
172 *
173 * @code
174 *
175 * int rc = RTR3Init();
176 * if (RT_FAILURE(rc))
177 * return RTMsgInitFailure(rc);
178 *
179 * @endcode
180 *
181 * @returns Appropriate exit code.
182 * @param rcRTR3Init The status code returned by RTR3Init.
183 */
184RTDECL(RTEXITCODE) RTMsgInitFailure(int rcRTR3Init);
185
186/**
187 * Print informational message to standard error.
188 *
189 * The message will be prefixed with the file name part of process image name
190 * (i.e. no path) and "warning: ". If the message doesn't end with a new line,
191 * one will be added. The caller should call this with an empty string if
192 * unsure whether the cursor is currently position at the start of a new line.
193 *
194 * @returns IPRT status code.
195 * @param pszFormat The message format string.
196 * @param ... Format arguments.
197 */
198RTDECL(int) RTMsgWarning(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
199
200/**
201 * Print informational message to standard error.
202 *
203 * The message will be prefixed with the file name part of process image name
204 * (i.e. no path) and "warning: ". If the message doesn't end with a new line,
205 * one will be added. The caller should call this with an empty string if
206 * unsure whether the cursor is currently position at the start of a new line.
207 *
208 * @returns IPRT status code.
209 * @param pszFormat The message format string.
210 * @param va Format arguments.
211 */
212RTDECL(int) RTMsgWarningV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
213
214/**
215 * Print informational message to standard output.
216 *
217 * The message will be prefixed with the file name part of process image name
218 * (i.e. no path) and "info: ". If the message doesn't end with a new line,
219 * one will be added. The caller should call this with an empty string if
220 * unsure whether the cursor is currently position at the start of a new line.
221 *
222 * @returns IPRT status code.
223 * @param pszFormat The message format string.
224 * @param ... Format arguments.
225 */
226RTDECL(int) RTMsgInfo(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
227
228/**
229 * Print informational message to standard output.
230 *
231 * The message will be prefixed with the file name part of process image name
232 * (i.e. no path) and "info: ". If the message doesn't end with a new line,
233 * one will be added. The caller should call this with an empty string if
234 * unsure whether the cursor is currently position at the start of a new line.
235 *
236 * @returns IPRT status code.
237 * @param pszFormat The message format string.
238 * @param va Format arguments.
239 */
240RTDECL(int) RTMsgInfoV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
241
242
243
244/** @defgroup grp_rt_msg_refentry Help generated from refentry/manpage.
245 *
246 * The refentry/manpage docbook source in doc/manual/en_US/man_* is processed by
247 * doc/manual/docbook-refentry-to-C-help.xsl and turned a set of the structures
248 * defined here.
249 *
250 * @{
251 */
252
253/** The non-breaking space character.
254 * @remarks We could've used U+00A0, but it is easier both to encode and to
255 * search and replace a single ASCII character. */
256#define RTMSGREFENTRY_NBSP '\b'
257
258/** @name REFENTRYSTR_SCOPE_XXX - Common string scoping and flags.
259 * @{ */
260/** Same scope as previous string table entry, flags are reset and can be
261 * ORed in. */
262#define RTMSGREFENTRYSTR_SCOPE_SAME UINT64_C(0)
263/** Global scope. */
264#define RTMSGREFENTRYSTR_SCOPE_GLOBAL UINT64_C(0x0fffffffffffffff)
265/** Scope mask. */
266#define RTMSGREFENTRYSTR_SCOPE_MASK UINT64_C(0x0fffffffffffffff)
267/** Flags mask. */
268#define RTMSGREFENTRYSTR_FLAGS_MASK UINT64_C(0xf000000000000000)
269/** Command synopsis, special hanging indent rules applies. */
270#define RTMSGREFENTRYSTR_FLAGS_SYNOPSIS RT_BIT_64(63)
271/** @} */
272
273/** String table entry for a refentry. */
274typedef struct RTMSGREFENTRYSTR
275{
276 /** The scope of the string. There are two predefined scopes,
277 * REFENTRYSTR_SCOPE_SAME and REFENTRYSTR_SCOPE_GLOBAL. The rest are
278 * reference entry specific. */
279 uint64_t fScope;
280 /** The string. Non-breaking space is represented by the char
281 * REFENTRY_NBSP defines, just in case the string needs wrapping. There is
282 * no trailing newline, that's implicit. */
283 const char *psz;
284} RTMSGREFENTRYSTR;
285/** Pointer to a read-only string table entry. */
286typedef const RTMSGREFENTRYSTR *PCRTMSGREFENTRYSTR;
287
288/** Refentry string table. */
289typedef struct RTMSGREFENTRYSTRTAB
290{
291 /** Number of strings. */
292 uint16_t cStrings;
293 /** Reserved for future use. */
294 uint16_t fReserved;
295 /** Pointer to the string table. */
296 PCRTMSGREFENTRYSTR paStrings;
297} RTMSGREFENTRYSTRTAB;
298/** Pointer to a read-only string table. */
299typedef RTMSGREFENTRYSTRTAB const *PCRTMSGREFENTRYSTRTAB;
300
301/**
302 * Help extracted from a docbook refentry document.
303 */
304typedef struct RTMSGREFENTRY
305{
306 /** Internal reference entry identifier. */
307 int64_t idInternal;
308 /** Usage synopsis. */
309 RTMSGREFENTRYSTRTAB Synopsis;
310 /** Full help. */
311 RTMSGREFENTRYSTRTAB Help;
312 /** Brief command description. */
313 const char *pszBrief;
314} RTMSGREFENTRY;
315/** Pointer to a read-only refentry help extract structure. */
316typedef RTMSGREFENTRY const *PCRTMSGREFENTRY;
317
318
319#ifndef IPRT_INCLUDED_stream_h
320typedef struct RTSTREAM *PRTSTREAM;
321#endif
322
323
324/**
325 * Print the synopsis to the given stream.
326 *
327 * @returns Current number of pending blank lines.
328 * @param pStrm The output stream.
329 * @param pEntry The refentry to print the help for.
330 */
331RTDECL(int) RTMsgRefEntrySynopsis(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry);
332
333
334/**
335 * Print the synopsis to the given stream.
336 *
337 * @returns Current number of pending blank lines.
338 * @param pStrm The output stream.
339 * @param pEntry The refentry to print the help for.
340 * @param fScope The scope inclusion mask.
341 * @param fFlags RTMSGREFENTRY_SYNOPSIS_F_XXX.
342 */
343RTDECL(int) RTMsgRefEntrySynopsisEx(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry, uint64_t fScope, uint32_t fFlags);
344/** @name RTMSGREFENTRY_SYNOPSIS_F_XXX - Flags for RTMsgRefEntrySynopsisEx.
345 * @{ */
346/** Prefix the output with 'Usage:'. */
347#define RTMSGREFENTRY_SYNOPSIS_F_USAGE RT_BIT_32(0)
348/** @} */
349
350
351/**
352 * Print the help text to the given stream.
353 *
354 * @returns Current number of pending blank lines.
355 * @param pStrm The output stream.
356 * @param pEntry The refentry to print the help for.
357 */
358RTDECL(int) RTMsgRefEntryHelp(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry);
359
360/**
361 * Print the help text to the given stream, extended version.
362 *
363 * @returns Current number of pending blank lines.
364 * @param pStrm The output stream.
365 * @param pEntry The refentry to print the help for.
366 * @param fScope The scope inclusion mask.
367 * @param fFlags Reserved, MBZ.
368 */
369RTDECL(int) RTMsgRefEntryHelpEx(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry, uint64_t fScope, uint32_t fFlags);
370
371/**
372 * Prints a string table.
373 *
374 * @returns Current number of pending blank lines.
375 * @param pStrm The output stream.
376 * @param pStrTab The string table.
377 * @param fScope The selection scope.
378 * @param pcPendingBlankLines In: Pending blank lines from previous string
379 * table. Out: Pending blank lines.
380 * @param pcLinesWritten Pointer to variable that should be incremented
381 * by the number of lines written. Optional.
382 */
383RTDECL(int) RTMsgRefEntryPrintStringTable(PRTSTREAM pStrm, PCRTMSGREFENTRYSTRTAB pStrTab, uint64_t fScope,
384 uint32_t *pcPendingBlankLines, uint32_t *pcLinesWritten);
385
386/** @} */
387
388
389/** @} */
390
391RT_C_DECLS_END
392
393#endif /* !IPRT_INCLUDED_message_h */
394
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