VirtualBox

source: vbox/trunk/include/iprt/message.h@ 85416

Last change on this file since 85416 was 82968, checked in by vboxsync, 5 years ago

Copyright year updates by scm.

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