include/pub_tool_options.h

   1
   2 /*--------------------------------------------------------------------*/
   3 /*--- Command line options.                     pub_tool_options.h ---*/
   4 /*--------------------------------------------------------------------*/
   5
   6 /*
   7    This file is part of Valgrind, a dynamic binary instrumentation
   8    framework.
   9
  10    Copyright (C) 2000-2017 Julian Seward
  11       jseward@acm.org
  12
  13    This program is free software; you can redistribute it and/or
  14    modify it under the terms of the GNU General Public License as
  15    published by the Free Software Foundation; either version 2 of the
  16    License, or (at your option) any later version.
  17
  18    This program is distributed in the hope that it will be useful, but
  19    WITHOUT ANY WARRANTY; without even the implied warranty of
  20    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21    General Public License for more details.
  22
  23    You should have received a copy of the GNU General Public License
  24    along with this program; if not, see <http://www.gnu.org/licenses/>.
  25
  26    The GNU General Public License is contained in the file COPYING.
  27 */
  28
  29 #ifndef __PUB_TOOL_OPTIONS_H
  30 #define __PUB_TOOL_OPTIONS_H
  31
  32 #include "pub_tool_basics.h"     // for VG_ macro
  33 #include "pub_tool_libcbase.h"   // for VG__ str functions
  34 #include "pub_tool_libcprint.h"  // for VG_(fmsg_bad_option)
  35 #include "libvex.h"              // for VexControl
  36
  37 // Command line option parsing happens in the following modes:
  38 //   cloE : Early processing, used by coregrind m_main.c to parse the
  39 //      command line  options that must be handled early on.
  40 //   cloP : Processing,  used by coregrind and tools during startup, when
  41 //      doing command line options Processing.
  42 //   clodD : Dynamic, used to dynamically change options after startup.
  43 //      A subset of the command line options can be changed dynamically
  44 //      after startup.
  45 //   cloH : Help, special mode to produce the list of dynamically changeable
  46 //      options for --help-dyn-options.
  47 typedef
  48    enum {
  49       cloE = 1,
  50       cloP = 2,
  51       cloD = 4,
  52       cloH = 8
  53    } Clo_Mode;
  54
  55 // Defines often used mode sets, e.g. for options used in several modes.
  56 #define cloEP (cloE | cloP)
  57 #define cloED (cloE | cloD)
  58 #define cloPD (cloP | cloD)
  59
  60 // Sets and gets the current option parsing mode.
  61 // VG_(set_Clo_Mode) also resets the value of VG_(Clo_Recognised) to False.
  62 void VG_(set_Clo_Mode) (Clo_Mode mode);
  63
  64 Clo_Mode VG_(Clo_Mode) (void);
  65
  66 // This is called by the various macros below to indicate that
  67 // the currently parsed option has been recognised.
  68 void VG_(set_Clo_Recognised) (void);
  69 Bool VG_(Clo_Recognised) (void);
  70
  71
  72 /* Once the system is started up, the dynamic options can be changed
  73    (mode CloD) or listed (mode cloH) using the below.  */
  74 void VG_(process_dynamic_option) (Clo_Mode mode, HChar *value);
  75
  76 // Macros below are calling VG_(check_clom) to handle an option according
  77 // to the current Clo_Mode.
  78 // If recognised, it marks the option as recognised, and then returns True
  79 // if the current mode matches the modes allowed for this option,
  80 // False if option should not be processed according to current mode
  81 // and qq_mode.
  82 // It produces a warning if mode is cloD and cloD is not allowed by
  83 // modes.  If current mode is cloH, CHECK_CLOM calls VG_(list_clo) if cloD
  84 // is allowed by modes.
  85 Bool VG_(check_clom) (Clo_Mode modes, const HChar* arg, const HChar* option,
  86                       Bool recognised);
  87
  88 // Higher-level command-line option recognisers;  use in if/else chains.
  89 // Note that they assign a value to the 'qq_var' argument.  So often they
  90 // can be used like this:
  91 //
  92 //   if VG_STR_CLO(arg, "--foo", clo_foo) { }
  93 //
  94 // But if you want to do further checking or processing, you can do this:
  95 //
  96 //   if VG_STR_CLO(arg, "--foo", clo_foo) { <checking or processing> }
  97 //
  98 // The recognisers above are only modifying their argument in the relevant
  99 // parsing mode (by default, only during cloP mode).
 100 // If an option is handled during other modes than cloP, use the *M
 101 // variants of the recognisers to specify the mode.
 102 //
 103 // They use GNU statement expressions to do the qq_var assignment within a
 104 // conditional expression.
 105
 106 // Used to produce the list of dynamically changeable options.
 107 extern void VG_(list_clo)(const HChar *qq_option);
 108
 109 // True if current option parsing mode matches qq_mode
 110 // and the first qq_len characters of qq_arg match qq_option.
 111 #define VG_STREQN_CLOM(qq_mode, qq_len, qq_arg, qq_option) \
 112    (VG_(check_clom)                                        \
 113     (qq_mode, qq_arg, qq_option,                           \
 114      VG_STREQN(qq_len, qq_arg, qq_option)))
 115
 116 // True if current option parsing mode matches qq_mode
 117 // and qq_arg match qq_option.
 118 #define VG_STREQ_CLOM(qq_mode, qq_arg, qq_option)       \
 119    (VG_(check_clom)                                     \
 120     (qq_mode, qq_arg, qq_option,                        \
 121      VG_STREQ(qq_arg, qq_option)))
 122
 123 static inline
 124 Bool VG_(bool_clom)(Clo_Mode qq_mode, const HChar* qq_arg, const HChar* qq_option, Bool* qq_var, Bool qq_vareq_arg)
 125 {
 126    Bool res = False;
 127    if (VG_(check_clom)(qq_mode, qq_arg, qq_option, qq_vareq_arg))
 128    {
 129       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];
 130       if (VG_(strcmp)(val, "yes") == 0)
 131       {
 132          *qq_var = True;
 133          res = True;
 134       }
 135       else if (VG_(strcmp)(val, "no") == 0)
 136       {
 137          *qq_var = False;
 138          res = True;
 139       }
 140       else
 141       {
 142          VG_(fmsg_bad_option)(qq_arg, "Invalid boolean value '%s'"
 143                                       " (should be 'yes' or 'no')\n",
 144           /* gcc 10 (20200119) complains that |val| could be null here. */
 145           /* I think it is wrong, but anyway, to placate it .. */
 146                                               (val ? val : "(null)"));
 147       }
 148    } else if (VG_STREQN(VG_(strlen)(qq_option), qq_arg, qq_option) &&
 149               VG_(strlen)(qq_option) == VG_(strlen)(qq_arg))
 150    {
 151       VG_(fmsg_bad_option)(qq_arg,
 152                            "Missing boolean value, did you mean '%s=yes'?\n",
 153                            qq_arg);
 154    }
 155
 156    return res;
 157 }
 158
 159 // String argument, eg. --foo=yes or --foo=no
 160 #define VG_BOOL_CLOM(qq_mode, qq_arg, qq_option, qq_var)        \
 161    (VG_(bool_clom)((qq_mode), (qq_arg), (qq_option), &(qq_var), \
 162    VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"="))   \
 163    )
 164
 165 #define VG_BOOL_CLO(qq_arg, qq_option, qq_var) \
 166    VG_BOOL_CLOM(cloP, qq_arg, qq_option, qq_var)
 167
 168 // String argument, eg. --foo=bar
 169 #define VG_STR_CLOM(qq_mode, qq_arg, qq_option, qq_var)                 \
 170    (VG_(check_clom)                                                     \
 171     (qq_mode, qq_arg, qq_option,                                        \
 172      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 173     ({const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 174       (qq_var) = val;                                                   \
 175       True; }))
 176
 177 #define VG_STR_CLO(qq_arg, qq_option, qq_var) \
 178    VG_STR_CLOM(cloP, qq_arg, qq_option, qq_var)
 179
 180 // UInt enum set arg, eg. --foo=fubar,bar,baz or --foo=none
 181 // or --foo=all  (if qq_all is True)
 182 #define VG_USETGEN_CLOM(qq_mode, qq_arg, qq_option, qq_vals, qq_var, qq_all) \
 183    (VG_(check_clom)                                                     \
 184     (qq_mode, qq_arg, qq_option,                                        \
 185      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 186     ({Bool res = True;                                                  \
 187        const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];        \
 188       if (!VG_(parse_enum_set)(qq_vals,                                 \
 189                                qq_all,/*allow_all*/                     \
 190                                val,                                     \
 191                                &(qq_var))) {                            \
 192          VG_(fmsg_bad_option)(qq_arg, "%s is an invalid %s set\n",      \
 193                               val, &qq_option[2]);                        \
 194          res = False; }                                                 \
 195       res; }))
 196
 197 // UInt enum set arg, eg. --foo=fubar,bar,baz or --foo=none or --foo=all
 198 #define VG_USET_CLO(qq_arg, qq_option, qq_vals, qq_var) \
 199    VG_USETGEN_CLOM(cloP, (qq_arg), qq_option, (qq_vals), (qq_var), True)
 200 #define VG_USET_CLOM(qq_mode, qq_arg, qq_option, qq_vals, qq_var) \
 201    VG_USETGEN_CLOM(qq_mode, (qq_arg), qq_option, (qq_vals), (qq_var), True)
 202
 203 /* Same as VG_USET_CLO but not allowing --foo=all.
 204    To be used when some or all of the enum set are mutually eXclusive. */
 205 #define VG_USETX_CLO(qq_arg, qq_option, qq_vals, qq_var) \
 206    VG_USETGEN_CLOM(cloP, (qq_arg), qq_option, (qq_vals), (qq_var), False)
 207 #define VG_USETX_CLOM(qq_mode, qq_arg, qq_option, qq_vals, qq_var) \
 208    VG_USETGEN_CLOM(qq_mode, (qq_arg), qq_option, (qq_vals), (qq_var), False)
 209
 210 // Unbounded integer arg, eg. --foo=10
 211 #define VG_INT_CLOM(qq_mode, qq_arg, qq_option, qq_var)                 \
 212    (VG_(check_clom)                                                     \
 213     (qq_mode, qq_arg, qq_option,                                        \
 214      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 215     ({Bool res = True;                                                  \
 216       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 217       HChar* s;                                                         \
 218       Long n = VG_(strtoll10)( val, &s );                               \
 219       (qq_var) = n;                                                     \
 220       /* Check for non-numeralness, or overflow. */                     \
 221       if ('\0' != s[0] || (qq_var) != n) {                              \
 222          VG_(fmsg_bad_option)(qq_arg,                                   \
 223                               "Invalid integer value '%s'\n", val);     \
 224          res = False; }                                                 \
 225       res; }))
 226
 227 #define VG_INT_CLO(qq_arg, qq_option, qq_var) \
 228    VG_INT_CLOM(cloP, qq_arg, qq_option, qq_var)
 229
 230 // Bounded integer arg, eg. --foo=10 ;  if the value exceeds the bounds it
 231 // causes an abort.  'qq_base' can be 10 or 16.
 232 #define VG_BINTN_CLOM(qq_mode, qq_base, qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 233    (VG_(check_clom)                                                     \
 234     (qq_mode, qq_arg, qq_option,                                        \
 235      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 236     ({Bool res = True;                                                  \
 237       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 238       HChar* s;                                                         \
 239       Long n = VG_(strtoll##qq_base)( val, &s );                        \
 240       (qq_var) = n;                                                     \
 241       /* MMM: separate the two cases, and explain the problem;  likewise */ \
 242       /* for all the other macros in this file. */                      \
 243       /* Check for non-numeralness, or overflow. */                     \
 244       /* Nb: it will overflow if qq_var is unsigned and qq_val is negative! */ \
 245       if ('\0' != s[0] || (qq_var) != n) {                              \
 246          VG_(fmsg_bad_option)(qq_arg,                                   \
 247                               "Invalid integer value '%s'\n", val);     \
 248          res = False; }                                                 \
 249       /* Check bounds. */                                               \
 250       if ((qq_var) < (qq_lo) || (qq_var) > (qq_hi)) {                   \
 251          VG_(fmsg_bad_option)(qq_arg,                                   \
 252             "'%s' argument must be between %lld and %lld\n",            \
 253                               (qq_option), (Long)(qq_lo), (Long)(qq_hi)); \
 254          res = False;                                                  \
 255       }                                                                \
 256       res;}))
 257
 258 // As above, but for unsigned int arguments with a lower bound of 0
 259 #define VG_BUINTN_CLOM(qq_mode, qq_base, qq_arg, qq_option, qq_var, qq_hi) \
 260 (VG_(check_clom)                                                     \
 261  (qq_mode, qq_arg, qq_option,                                        \
 262   VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 263  ({Bool res = True;                                                  \
 264       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 265       HChar* s;                                                         \
 266       Long n = VG_(strtoll##qq_base)( val, &s );                        \
 267       (qq_var) = n;                                                     \
 268       if ('\0' != s[0] || (qq_var) != n) {                              \
 269          VG_(fmsg_bad_option)(qq_arg,                                   \
 270                               "Invalid integer value '%s'\n", val);     \
 271          res = False; }                                                 \
 272       /* Check bounds. */                                               \
 273       if ((qq_var) > (qq_hi)) {                                         \
 274          VG_(fmsg_bad_option)(qq_arg,                                   \
 275             "'%s' argument must be <= %lld\n",            \
 276                               (qq_option), (Long)(qq_hi));              \
 277          res = False;                                                  \
 278       }                                                                \
 279       res;}))
 280
 281 // Bounded decimal integer arg, eg. --foo=100
 282 #define VG_BINT_CLO(qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 283    VG_BINTN_CLOM(cloP, 10, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 284 #define VG_BINT_CLOM(qq_mode, qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 285    VG_BINTN_CLOM(qq_mode, 10, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 286 #define VG_BUINT_CLOM(qq_mode, qq_arg, qq_option, qq_var, qq_hi) \
 287    VG_BUINTN_CLOM(qq_mode, 10, (qq_arg), qq_option, (qq_var), (qq_hi))
 288
 289 // Bounded hexadecimal integer arg, eg. --foo=0x1fa8
 290 #define VG_BHEX_CLO(qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 291    VG_BINTN_CLOM(cloP, 16, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 292
 293 // Double (decimal) arg, eg. --foo=4.6
 294 // XXX: there's not VG_BDBL_CLO because we don't have a good way of printing
 295 // floats at the moment!
 296 #define VG_DBL_CLOM(qq_mode, qq_arg, qq_option, qq_var) \
 297    (VG_(check_clom)                                                     \
 298     (qq_mode, qq_arg, qq_option,                                        \
 299      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 300     ({Bool res = True;                                                  \
 301       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 302       HChar* s;                                                         \
 303       double n = VG_(strtod)( val, &s );                                \
 304       (qq_var) = n;                                                     \
 305       /* Check for non-numeralness */                                   \
 306       if ('\0' != s[0]) {                                               \
 307          VG_(fmsg_bad_option)(qq_arg,                                   \
 308                               "Invalid floating point value '%s'\n",val); \
 309          res = False; }                                                 \
 310       res;}))
 311
 312 #define VG_DBL_CLO( qq_arg, qq_option, qq_var) \
 313    VG_DBL_CLOM(cloP, qq_arg, qq_option, qq_var)
 314
 315 // Arg whose value is denoted by the exact presence of the given string;
 316 // if it matches, qq_var is assigned the value in qq_val.
 317 #define VG_XACT_CLOM(qq_mode, qq_arg, qq_option, qq_var, qq_val) \
 318    (VG_(check_clom) \
 319     (qq_mode, qq_arg, qq_option,                                \
 320      VG_STREQ((qq_arg), (qq_option))) &&                        \
 321     ({(qq_var) = (qq_val);                                      \
 322        True; }))
 323
 324 #define VG_XACT_CLO(qq_arg, qq_option, qq_var, qq_val) \
 325    VG_XACT_CLOM(cloP, qq_arg, qq_option, qq_var, qq_val)
 326
 327 // Arg that can be one of a set of strings, as specified in an NULL
 328 // terminated array.  Returns the index of the string in |qq_ix|, or
 329 // aborts if not found.
 330 #define VG_STRINDEX_CLOM(qq_mode, qq_arg, qq_option, qq_strings, qq_ix) \
 331    (VG_(check_clom)                                                     \
 332     (qq_mode, qq_arg, qq_option,                                        \
 333      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 334     ({Bool res = True;                                                  \
 335       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 336       for (qq_ix = 0; (qq_strings)[qq_ix]; qq_ix++) {                   \
 337          if (VG_STREQ(val, (qq_strings)[qq_ix]))                        \
 338             break;                                                      \
 339       }                                                                 \
 340       if ((qq_strings)[qq_ix] == NULL) {                                \
 341          VG_(fmsg_bad_option)(qq_arg,                                   \
 342                               "Invalid string '%s' in '%s'\n", val, qq_arg); \
 343          res = False;                                                   \
 344       } \
 345       res; }))
 346
 347 #define VG_STRINDEX_CLO(qq_arg, qq_option, qq_strings, qq_ix) \
 348    VG_STRINDEX_CLOM(cloP, qq_arg, qq_option, qq_strings, qq_ix)
 349
 350 /* Verbosity level: 0 = silent, 1 (default), > 1 = more verbose. */
 351 extern Int  VG_(clo_verbosity);
 352
 353 /* Show tool and core statistics */
 354 extern Bool VG_(clo_stats);
 355
 356 /* wait for vgdb/gdb after reporting that amount of error.
 357    Note that this value can be changed dynamically. */
 358 extern Int VG_(clo_vgdb_error);
 359
 360 /* Set by vgdb in --multi mode when launching valgrind. This suppresses
 361    the "TO DEBUG" banner because vgdb will take care of attaching in that
 362    case.  */
 363 extern Bool VG_(clo_launched_with_multi);
 364
 365 /* If user has provided the --vgdb-prefix command line option,
 366    VG_(arg_vgdb_prefix) points at the provided argument (including the
 367    '--vgdb-prefix=' string).
 368    Otherwise, it is NULL.
 369    Typically, this is used by tools to produce user message with the
 370    expected vgdb prefix argument, if the user has changed the default. */
 371 extern const HChar *VG_(arg_vgdb_prefix);
 372
 373 /* Emit all messages as XML? default: NO */
 374 /* If clo_xml is set, various other options are set in a non-default
 375    way.  See vg_main.c and mc_main.c. */
 376 extern Bool VG_(clo_xml);
 377
 378 /* An arbitrary user-supplied string which is copied into the
 379    XML output, in between <usercomment> tags. */
 380 extern const HChar* VG_(clo_xml_user_comment);
 381
 382 /* Vex iropt control.  Tool-visible so tools can make Vex optimise
 383    less aggressively if that is needed (callgrind needs this). */
 384 extern VexControl VG_(clo_vex_control);
 385 extern VexRegisterUpdates VG_(clo_px_file_backed);
 386
 387 extern Int VG_(clo_redzone_size);
 388
 389 typedef
 390    enum {
 391       Vg_XTMemory_None,   // Do not do any xtree memory profiling.
 392       Vg_XTMemory_Allocs, // Currently allocated size xtree memory profiling
 393       Vg_XTMemory_Full,   // Full profiling : Current allocated size, total
 394       // allocated size, nr of blocks, total freed size, ...
 395    }
 396    VgXTMemory;
 397 // Tools that replace malloc can optionally implement memory profiling
 398 // following the value of VG_(clo_xtree_profile_memory) to produce a report
 399 // at the end of execution.
 400 extern VgXTMemory VG_(clo_xtree_memory);
 401 /* Holds the filename to use for xtree memory profiling output, before expansion
 402    of %p and %q templates. */
 403 extern const HChar* VG_(clo_xtree_memory_file);
 404 /* Compress strings in xtree dumps. */
 405 extern Bool VG_(clo_xtree_compress_strings);
 406
 407 /* Number of parents of a backtrace.  Default: 12  */
 408 extern Int   VG_(clo_backtrace_size);
 409
 410 /* Continue stack traces below main()?  Default: NO */
 411 extern Bool VG_(clo_show_below_main);
 412
 413 /* Keep symbols (and all other debuginfo) for code that is unloaded (dlclose
 414    or similar) so that stack traces can still give line/file info for
 415    previously captured stack traces.  e.g. ... showing where a block was
 416    allocated e.g. leaks of or accesses just outside a block. */
 417 extern Bool VG_(clo_keep_debuginfo);
 418
 419
 420 /* Used to expand file names.  "option_name" is the option name, eg.
 421    "--log-file".  'format' is what follows, eg. "cachegrind.out.%p".  In
 422    'format':
 423    - "%p" is replaced with PID.
 424    - "%q{QUAL}" is replaced with the environment variable $QUAL.  If $QUAL
 425      isn't set, we abort.  If the "{QUAL}" part is malformed, we abort.
 426    - "%%" is replaced with "%".
 427    Anything else after '%' causes an abort.
 428    If the format specifies a relative file name, it's put in the program's
 429    initial working directory.  If it specifies an absolute file name (ie.
 430    starts with '/') then it is put there.
 431
 432    Note that "option_name" has no effect on the returned string: the
 433    returned string depends only on "format" and the PIDs and
 434    environment variables that it references (if any). "option_name" is
 435    merely used in printing error messages, if an error message needs
 436    to be printed due to malformedness of the "format" argument.
 437 */
 438 extern HChar* VG_(expand_file_name)(const HChar* option_name,
 439                                     const HChar* format);
 440
 441 #endif   // __PUB_TOOL_OPTIONS_H
 442
 443 /*--------------------------------------------------------------------*/
 444 /*--- end                                                          ---*/
 445 /*--------------------------------------------------------------------*/