include/iprt/message.h

   1 /** @file
   2  * IPRT - Message Formatting.
   3  */
   4
   5 /*
   6  * Copyright (C) 2009-2024 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
  46 RT_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  */
  60 RTDECL(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  */
  74 RTDECL(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  */
  88 RTDECL(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  */
  99 RTDECL(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  */
 110 RTDECL(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  */
 119 RTDECL(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  */
 128 RTDECL(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  */
 139 RTDECL(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  */
 150 RTDECL(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  */
 159 RTDECL(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  */
 168 RTDECL(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  */
 184 RTDECL(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  */
 198 RTDECL(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  */
 212 RTDECL(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  */
 226 RTDECL(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  */
 240 RTDECL(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. */
 274 typedef 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. */
 286 typedef const RTMSGREFENTRYSTR *PCRTMSGREFENTRYSTR;
 287
 288 /** Refentry string table. */
 289 typedef 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. */
 299 typedef RTMSGREFENTRYSTRTAB const *PCRTMSGREFENTRYSTRTAB;
 300
 301 /**
 302  * Help extracted from a docbook refentry document.
 303  */
 304 typedef 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. */
 316 typedef RTMSGREFENTRY const *PCRTMSGREFENTRY;
 317
 318
 319 #ifndef IPRT_INCLUDED_stream_h
 320 typedef 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  */
 331 RTDECL(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  */
 343 RTDECL(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  */
 358 RTDECL(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  */
 369 RTDECL(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  */
 383 RTDECL(int) RTMsgRefEntryPrintStringTable(PRTSTREAM pStrm, PCRTMSGREFENTRYSTRTAB pStrTab, uint64_t fScope,
 384                                           uint32_t *pcPendingBlankLines, uint32_t *pcLinesWritten);
 385
 386 /** @} */
 387
 388
 389 /** @} */
 390
 391 RT_C_DECLS_END
 392
 393 #endif /* !IPRT_INCLUDED_message_h */
 394