summaryrefslogtreecommitdiffstats
path: root/include/iprt/message.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/iprt/message.h')
-rw-r--r--include/iprt/message.h394
1 files changed, 394 insertions, 0 deletions
diff --git a/include/iprt/message.h b/include/iprt/message.h
new file mode 100644
index 00000000..b5a912c7
--- /dev/null
+++ b/include/iprt/message.h
@@ -0,0 +1,394 @@
+/** @file
+ * IPRT - Message Formatting.
+ */
+
+/*
+ * Copyright (C) 2009-2022 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_message_h
+#define IPRT_INCLUDED_message_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_msg RTMsg - Message Formatting
+ * @ingroup grp_rt
+ * @{
+ */
+
+/**
+ * Sets the program name to use.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The program name format string.
+ * @param ... Format arguments.
+ */
+RTDECL(int) RTMsgSetProgName(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
+
+/**
+ * Print error message to standard error.
+ *
+ * The message will be prefixed with the file name part of process image name
+ * (i.e. no path) and "error: ". If the message doesn't end with a new line,
+ * one will be added. The caller should call this with an empty string if
+ * unsure whether the cursor is currently position at the start of a new line.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The message format string.
+ * @param ... Format arguments.
+ */
+RTDECL(int) RTMsgError(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
+
+/**
+ * Print error message to standard error.
+ *
+ * The message will be prefixed with the file name part of process image name
+ * (i.e. no path) and "error: ". If the message doesn't end with a new line,
+ * one will be added. The caller should call this with an empty string if
+ * unsure whether the cursor is currently position at the start of a new line.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The message format string.
+ * @param va Format arguments.
+ */
+RTDECL(int) RTMsgErrorV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
+
+/**
+ * Same as RTMsgError() except for the return value.
+ *
+ * @returns @a enmExitCode
+ * @param enmExitCode What to exit code to return. This is mainly for
+ * saving some vertical space in the source file.
+ * @param pszFormat The message format string.
+ * @param ... Format arguments.
+ */
+RTDECL(RTEXITCODE) RTMsgErrorExit(RTEXITCODE enmExitCode, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
+
+/**
+ * Same as RTMsgErrorV() except for the return value.
+ *
+ * @returns @a enmExitCode
+ * @param enmExitCode What to exit code to return. This is mainly for
+ * saving some vertical space in the source file.
+ * @param pszFormat The message format string.
+ * @param va Format arguments.
+ */
+RTDECL(RTEXITCODE) RTMsgErrorExitV(RTEXITCODE enmExitCode, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
+
+/**
+ * Same as RTMsgError() except for always returning RTEXITCODE_FAILURE.
+ *
+ * @returns RTEXITCODE_FAILURE
+ * @param pszFormat The message format string.
+ * @param ... Format arguments.
+ */
+RTDECL(RTEXITCODE) RTMsgErrorExitFailure(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
+
+/**
+ * Same as RTMsgErrorV() except for always returning RTEXITCODE_FAILURE.
+ *
+ * @returns RTEXITCODE_FAILURE
+ * @param pszFormat The message format string.
+ * @param va Format arguments.
+ */
+RTDECL(RTEXITCODE) RTMsgErrorExitFailureV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
+
+/**
+ * Same as RTMsgError() except for the return value.
+ *
+ * @returns @a rcRet
+ * @param rcRet What IPRT status to return. This is mainly for
+ * saving some vertical space in the source file.
+ * @param pszFormat The message format string.
+ * @param ... Format arguments.
+ */
+RTDECL(int) RTMsgErrorRc(int rcRet, const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(2, 3);
+
+/**
+ * Same as RTMsgErrorV() except for the return value.
+ *
+ * @returns @a rcRet
+ * @param rcRet What IPRT status to return. This is mainly for
+ * saving some vertical space in the source file.
+ * @param pszFormat The message format string.
+ * @param va Format arguments.
+ */
+RTDECL(int) RTMsgErrorRcV(int rcRet, const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
+
+/**
+ * For reporting syntax errors.
+ *
+ * @returns RTEXITCODE_SYNTAX
+ * @param pszFormat The message format string. Newline not needed.
+ * @param ... Format arguments.
+ */
+RTDECL(RTEXITCODE) RTMsgSyntax(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
+
+/**
+ * For reporting syntax errors.
+ *
+ * @returns RTEXITCODE_SYNTAX
+ * @param pszFormat The message format string. Newline not needed.
+ * @param va Format arguments.
+ */
+RTDECL(RTEXITCODE) RTMsgSyntaxV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
+
+/**
+ * Print an error message for a RTR3Init failure and suggest an exit code.
+ *
+ * @code
+ *
+ * int rc = RTR3Init();
+ * if (RT_FAILURE(rc))
+ * return RTMsgInitFailure(rc);
+ *
+ * @endcode
+ *
+ * @returns Appropriate exit code.
+ * @param rcRTR3Init The status code returned by RTR3Init.
+ */
+RTDECL(RTEXITCODE) RTMsgInitFailure(int rcRTR3Init);
+
+/**
+ * Print informational message to standard error.
+ *
+ * The message will be prefixed with the file name part of process image name
+ * (i.e. no path) and "warning: ". If the message doesn't end with a new line,
+ * one will be added. The caller should call this with an empty string if
+ * unsure whether the cursor is currently position at the start of a new line.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The message format string.
+ * @param ... Format arguments.
+ */
+RTDECL(int) RTMsgWarning(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
+
+/**
+ * Print informational message to standard error.
+ *
+ * The message will be prefixed with the file name part of process image name
+ * (i.e. no path) and "warning: ". If the message doesn't end with a new line,
+ * one will be added. The caller should call this with an empty string if
+ * unsure whether the cursor is currently position at the start of a new line.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The message format string.
+ * @param va Format arguments.
+ */
+RTDECL(int) RTMsgWarningV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
+
+/**
+ * Print informational message to standard output.
+ *
+ * The message will be prefixed with the file name part of process image name
+ * (i.e. no path) and "info: ". If the message doesn't end with a new line,
+ * one will be added. The caller should call this with an empty string if
+ * unsure whether the cursor is currently position at the start of a new line.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The message format string.
+ * @param ... Format arguments.
+ */
+RTDECL(int) RTMsgInfo(const char *pszFormat, ...) RT_IPRT_FORMAT_ATTR(1, 2);
+
+/**
+ * Print informational message to standard output.
+ *
+ * The message will be prefixed with the file name part of process image name
+ * (i.e. no path) and "info: ". If the message doesn't end with a new line,
+ * one will be added. The caller should call this with an empty string if
+ * unsure whether the cursor is currently position at the start of a new line.
+ *
+ * @returns IPRT status code.
+ * @param pszFormat The message format string.
+ * @param va Format arguments.
+ */
+RTDECL(int) RTMsgInfoV(const char *pszFormat, va_list va) RT_IPRT_FORMAT_ATTR(1, 0);
+
+
+
+/** @defgroup grp_rt_msg_refentry Help generated from refentry/manpage.
+ *
+ * The refentry/manpage docbook source in doc/manual/en_US/man_* is processed by
+ * doc/manual/docbook-refentry-to-C-help.xsl and turned a set of the structures
+ * defined here.
+ *
+ * @{
+ */
+
+/** The non-breaking space character.
+ * @remarks We could've used U+00A0, but it is easier both to encode and to
+ * search and replace a single ASCII character. */
+#define RTMSGREFENTRY_NBSP '\b'
+
+/** @name REFENTRYSTR_SCOPE_XXX - Common string scoping and flags.
+ * @{ */
+/** Same scope as previous string table entry, flags are reset and can be
+ * ORed in. */
+#define RTMSGREFENTRYSTR_SCOPE_SAME UINT64_C(0)
+/** Global scope. */
+#define RTMSGREFENTRYSTR_SCOPE_GLOBAL UINT64_C(0x0fffffffffffffff)
+/** Scope mask. */
+#define RTMSGREFENTRYSTR_SCOPE_MASK UINT64_C(0x0fffffffffffffff)
+/** Flags mask. */
+#define RTMSGREFENTRYSTR_FLAGS_MASK UINT64_C(0xf000000000000000)
+/** Command synopsis, special hanging indent rules applies. */
+#define RTMSGREFENTRYSTR_FLAGS_SYNOPSIS RT_BIT_64(63)
+/** @} */
+
+/** String table entry for a refentry. */
+typedef struct RTMSGREFENTRYSTR
+{
+ /** The scope of the string. There are two predefined scopes,
+ * REFENTRYSTR_SCOPE_SAME and REFENTRYSTR_SCOPE_GLOBAL. The rest are
+ * reference entry specific. */
+ uint64_t fScope;
+ /** The string. Non-breaking space is represented by the char
+ * REFENTRY_NBSP defines, just in case the string needs wrapping. There is
+ * no trailing newline, that's implicit. */
+ const char *psz;
+} RTMSGREFENTRYSTR;
+/** Pointer to a read-only string table entry. */
+typedef const RTMSGREFENTRYSTR *PCRTMSGREFENTRYSTR;
+
+/** Refentry string table. */
+typedef struct RTMSGREFENTRYSTRTAB
+{
+ /** Number of strings. */
+ uint16_t cStrings;
+ /** Reserved for future use. */
+ uint16_t fReserved;
+ /** Pointer to the string table. */
+ PCRTMSGREFENTRYSTR paStrings;
+} RTMSGREFENTRYSTRTAB;
+/** Pointer to a read-only string table. */
+typedef RTMSGREFENTRYSTRTAB const *PCRTMSGREFENTRYSTRTAB;
+
+/**
+ * Help extracted from a docbook refentry document.
+ */
+typedef struct RTMSGREFENTRY
+{
+ /** Internal reference entry identifier. */
+ int64_t idInternal;
+ /** Usage synopsis. */
+ RTMSGREFENTRYSTRTAB Synopsis;
+ /** Full help. */
+ RTMSGREFENTRYSTRTAB Help;
+ /** Brief command description. */
+ const char *pszBrief;
+} RTMSGREFENTRY;
+/** Pointer to a read-only refentry help extract structure. */
+typedef RTMSGREFENTRY const *PCRTMSGREFENTRY;
+
+
+#ifndef IPRT_INCLUDED_stream_h
+typedef struct RTSTREAM *PRTSTREAM;
+#endif
+
+
+/**
+ * Print the synopsis to the given stream.
+ *
+ * @returns Current number of pending blank lines.
+ * @param pStrm The output stream.
+ * @param pEntry The refentry to print the help for.
+ */
+RTDECL(int) RTMsgRefEntrySynopsis(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry);
+
+
+/**
+ * Print the synopsis to the given stream.
+ *
+ * @returns Current number of pending blank lines.
+ * @param pStrm The output stream.
+ * @param pEntry The refentry to print the help for.
+ * @param fScope The scope inclusion mask.
+ * @param fFlags RTMSGREFENTRY_SYNOPSIS_F_XXX.
+ */
+RTDECL(int) RTMsgRefEntrySynopsisEx(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry, uint64_t fScope, uint32_t fFlags);
+/** @name RTMSGREFENTRY_SYNOPSIS_F_XXX - Flags for RTMsgRefEntrySynopsisEx.
+ * @{ */
+/** Prefix the output with 'Usage:'. */
+#define RTMSGREFENTRY_SYNOPSIS_F_USAGE RT_BIT_32(0)
+/** @} */
+
+
+/**
+ * Print the help text to the given stream.
+ *
+ * @returns Current number of pending blank lines.
+ * @param pStrm The output stream.
+ * @param pEntry The refentry to print the help for.
+ */
+RTDECL(int) RTMsgRefEntryHelp(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry);
+
+/**
+ * Print the help text to the given stream, extended version.
+ *
+ * @returns Current number of pending blank lines.
+ * @param pStrm The output stream.
+ * @param pEntry The refentry to print the help for.
+ * @param fScope The scope inclusion mask.
+ * @param fFlags Reserved, MBZ.
+ */
+RTDECL(int) RTMsgRefEntryHelpEx(PRTSTREAM pStrm, PCRTMSGREFENTRY pEntry, uint64_t fScope, uint32_t fFlags);
+
+/**
+ * Prints a string table.
+ *
+ * @returns Current number of pending blank lines.
+ * @param pStrm The output stream.
+ * @param pStrTab The string table.
+ * @param fScope The selection scope.
+ * @param pcPendingBlankLines In: Pending blank lines from previous string
+ * table. Out: Pending blank lines.
+ * @param pcLinesWritten Pointer to variable that should be incremented
+ * by the number of lines written. Optional.
+ */
+RTDECL(int) RTMsgRefEntryPrintStringTable(PRTSTREAM pStrm, PCRTMSGREFENTRYSTRTAB pStrTab, uint64_t fScope,
+ uint32_t *pcPendingBlankLines, uint32_t *pcLinesWritten);
+
+/** @} */
+
+
+/** @} */
+
+RT_C_DECLS_END
+
+#endif /* !IPRT_INCLUDED_message_h */
+