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