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", val);  \
 132          res = False; }                                                 \
 133       res; }))
 134
 135 #define VG_BOOL_CLO(qq_arg, qq_option, qq_var) \
 136    VG_BOOL_CLOM(cloP, qq_arg, qq_option, qq_var)
 137
 138 // String argument, eg. --foo=bar
 139 #define VG_STR_CLOM(qq_mode, qq_arg, qq_option, qq_var)                 \
 140    (VG_(check_clom)                                                     \
 141     (qq_mode, qq_arg, qq_option,                                        \
 142      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 143     ({const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 144       (qq_var) = val;                                                   \
 145       True; }))
 146
 147 #define VG_STR_CLO(qq_arg, qq_option, qq_var) \
 148    VG_STR_CLOM(cloP, qq_arg, qq_option, qq_var)
 149
 150 // UInt enum set arg, eg. --foo=fubar,bar,baz or --foo=none
 151 // or --foo=all  (if qq_all is True)
 152 #define VG_USETGEN_CLOM(qq_mode, qq_arg, qq_option, qq_vals, qq_var, qq_all) \
 153    (VG_(check_clom)                                                     \
 154     (qq_mode, qq_arg, qq_option,                                        \
 155      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 156     ({Bool res = True;                                                  \
 157        const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];        \
 158       if (!VG_(parse_enum_set)(qq_vals,                                 \
 159                                qq_all,/*allow_all*/                     \
 160                                val,                                     \
 161                                &(qq_var))) {                            \
 162          VG_(fmsg_bad_option)(qq_arg, "%s is an invalid %s set\n",      \
 163                               val, qq_option+2);                        \
 164          res = False; }                                                 \
 165       res; }))
 166
 167 // UInt enum set arg, eg. --foo=fubar,bar,baz or --foo=none or --foo=all
 168 #define VG_USET_CLO(qq_arg, qq_option, qq_vals, qq_var) \
 169    VG_USETGEN_CLOM(cloP, (qq_arg), qq_option, (qq_vals), (qq_var), True)
 170 #define VG_USET_CLOM(qq_mode, qq_arg, qq_option, qq_vals, qq_var) \
 171    VG_USETGEN_CLOM(qq_mode, (qq_arg), qq_option, (qq_vals), (qq_var), True)
 172
 173 /* Same as VG_USET_CLO but not allowing --foo=all.
 174    To be used when some or all of the enum set are mutually eXclusive. */
 175 #define VG_USETX_CLO(qq_arg, qq_option, qq_vals, qq_var) \
 176    VG_USETGEN_CLOM(cloP, (qq_arg), qq_option, (qq_vals), (qq_var), False)
 177 #define VG_USETX_CLOM(qq_mode, qq_arg, qq_option, qq_vals, qq_var) \
 178    VG_USETGEN_CLOM(qq_mode, (qq_arg), qq_option, (qq_vals), (qq_var), False)
 179
 180 // Unbounded integer arg, eg. --foo=10
 181 #define VG_INT_CLOM(qq_mode, qq_arg, qq_option, qq_var)                 \
 182    (VG_(check_clom)                                                     \
 183     (qq_mode, qq_arg, qq_option,                                        \
 184      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 185     ({Bool res = True;                                                  \
 186       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 187       HChar* s;                                                         \
 188       Long n = VG_(strtoll10)( val, &s );                               \
 189       (qq_var) = n;                                                     \
 190       /* Check for non-numeralness, or overflow. */                     \
 191       if ('\0' != s[0] || (qq_var) != n) {                              \
 192          VG_(fmsg_bad_option)(qq_arg,                                   \
 193                               "Invalid integer value '%s'\n", val);     \
 194          res = False; }                                                 \
 195       res; }))
 196
 197 #define VG_INT_CLO(qq_arg, qq_option, qq_var) \
 198    VG_INT_CLOM(cloP, qq_arg, qq_option, qq_var)
 199
 200 // Bounded integer arg, eg. --foo=10 ;  if the value exceeds the bounds it
 201 // causes an abort.  'qq_base' can be 10 or 16.
 202 #define VG_BINTN_CLOM(qq_mode, qq_base, qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 203    (VG_(check_clom)                                                     \
 204     (qq_mode, qq_arg, qq_option,                                        \
 205      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 206     ({Bool res = True;                                                  \
 207       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 208       HChar* s;                                                         \
 209       Long n = VG_(strtoll##qq_base)( val, &s );                        \
 210       (qq_var) = n;                                                     \
 211       /* MMM: separate the two cases, and explain the problem;  likewise */ \
 212       /* for all the other macros in this file. */                      \
 213       /* Check for non-numeralness, or overflow. */                     \
 214       /* Nb: it will overflow if qq_var is unsigned and qq_val is negative! */ \
 215       if ('\0' != s[0] || (qq_var) != n) {                              \
 216          VG_(fmsg_bad_option)(qq_arg,                                   \
 217                               "Invalid integer value '%s'\n", val);     \
 218          res = False; }                                                 \
 219       /* Check bounds. */                                               \
 220       if ((qq_var) < (qq_lo) || (qq_var) > (qq_hi)) {                   \
 221          VG_(fmsg_bad_option)(qq_arg,                                   \
 222             "'%s' argument must be between %lld and %lld\n",            \
 223                               (qq_option), (Long)(qq_lo), (Long)(qq_hi)); \
 224          res = False;                                                  \
 225       }                                                                \
 226       res;}))
 227
 228 // Bounded decimal integer arg, eg. --foo=100
 229 #define VG_BINT_CLO(qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 230    VG_BINTN_CLOM(cloP, 10, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 231 #define VG_BINT_CLOM(qq_mode, qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 232    VG_BINTN_CLOM(qq_mode, 10, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 233
 234 // Bounded hexadecimal integer arg, eg. --foo=0x1fa8
 235 #define VG_BHEX_CLO(qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 236    VG_BINTN_CLOM(cloP, 16, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 237
 238 // Double (decimal) arg, eg. --foo=4.6
 239 // XXX: there's not VG_BDBL_CLO because we don't have a good way of printing
 240 // floats at the moment!
 241 #define VG_DBL_CLOM(qq_mode, qq_arg, qq_option, qq_var) \
 242    (VG_(check_clom)                                                     \
 243     (qq_mode, qq_arg, qq_option,                                        \
 244      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 245     ({Bool res = True;                                                  \
 246       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 247       HChar* s;                                                         \
 248       double n = VG_(strtod)( val, &s );                                \
 249       (qq_var) = n;                                                     \
 250       /* Check for non-numeralness */                                   \
 251       if ('\0' != s[0]) {                                               \
 252          VG_(fmsg_bad_option)(qq_arg,                                   \
 253                               "Invalid floating point value '%s'\n",val); \
 254          res = False; }                                                 \
 255       res;}))
 256
 257 #define VG_DBL_CLO( qq_arg, qq_option, qq_var) \
 258    VG_DBL_CLOM(cloP, qq_arg, qq_option, qq_var)
 259
 260 // Arg whose value is denoted by the exact presence of the given string;
 261 // if it matches, qq_var is assigned the value in qq_val.
 262 #define VG_XACT_CLOM(qq_mode, qq_arg, qq_option, qq_var, qq_val) \
 263    (VG_(check_clom) \
 264     (qq_mode, qq_arg, qq_option,                                \
 265      VG_STREQ((qq_arg), (qq_option))) &&                        \
 266     ({(qq_var) = (qq_val);                                      \
 267        True; }))
 268
 269 #define VG_XACT_CLO(qq_arg, qq_option, qq_var, qq_val) \
 270    VG_XACT_CLOM(cloP, qq_arg, qq_option, qq_var, qq_val)
 271
 272 // Arg that can be one of a set of strings, as specified in an NULL
 273 // terminated array.  Returns the index of the string in |qq_ix|, or
 274 // aborts if not found.
 275 #define VG_STRINDEX_CLOM(qq_mode, qq_arg, qq_option, qq_strings, qq_ix) \
 276    (VG_(check_clom)                                                     \
 277     (qq_mode, qq_arg, qq_option,                                        \
 278      VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=")) &&      \
 279     ({Bool res = True;                                                  \
 280       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ];         \
 281       for (qq_ix = 0; (qq_strings)[qq_ix]; qq_ix++) {                   \
 282          if (VG_STREQ(val, (qq_strings)[qq_ix]))                        \
 283             break;                                                      \
 284       }                                                                 \
 285       if ((qq_strings)[qq_ix] == NULL) {                                \
 286          VG_(fmsg_bad_option)(qq_arg,                                   \
 287                               "Invalid string '%s' in '%s'\n", val, qq_arg); \
 288          res = False;                                                   \
 289       } \
 290       res; }))
 291
 292 #define VG_STRINDEX_CLO(qq_arg, qq_option, qq_strings, qq_ix) \
 293    VG_STRINDEX_CLOM(cloP, qq_arg, qq_option, qq_strings, qq_ix)
 294
 295 /* Verbosity level: 0 = silent, 1 (default), > 1 = more verbose. */
 296 extern Int  VG_(clo_verbosity);
 297
 298 /* Show tool and core statistics */
 299 extern Bool VG_(clo_stats);
 300
 301 /* wait for vgdb/gdb after reporting that amount of error.
 302    Note that this value can be changed dynamically. */
 303 extern Int VG_(clo_vgdb_error);
 304
 305 /* If user has provided the --vgdb-prefix command line option,
 306    VG_(arg_vgdb_prefix) points at the provided argument (including the
 307    '--vgdb-prefix=' string).
 308    Otherwise, it is NULL.
 309    Typically, this is used by tools to produce user message with the
 310    expected vgdb prefix argument, if the user has changed the default. */
 311 extern const HChar *VG_(arg_vgdb_prefix);
 312
 313 /* Emit all messages as XML? default: NO */
 314 /* If clo_xml is set, various other options are set in a non-default
 315    way.  See vg_main.c and mc_main.c. */
 316 extern Bool VG_(clo_xml);
 317
 318 /* An arbitrary user-supplied string which is copied into the
 319    XML output, in between <usercomment> tags. */
 320 extern const HChar* VG_(clo_xml_user_comment);
 321
 322 /* Vex iropt control.  Tool-visible so tools can make Vex optimise
 323    less aggressively if that is needed (callgrind needs this). */
 324 extern VexControl VG_(clo_vex_control);
 325 extern VexRegisterUpdates VG_(clo_px_file_backed);
 326
 327 extern Int VG_(clo_redzone_size);
 328
 329 typedef
 330    enum {
 331       Vg_XTMemory_None,   // Do not do any xtree memory profiling.
 332       Vg_XTMemory_Allocs, // Currently allocated size xtree memory profiling
 333       Vg_XTMemory_Full,   // Full profiling : Current allocated size, total
 334       // allocated size, nr of blocks, total freed size, ...
 335    }
 336    VgXTMemory;
 337 // Tools that replace malloc can optionally implement memory profiling
 338 // following the value of VG_(clo_xtree_profile_memory) to produce a report
 339 // at the end of execution.
 340 extern VgXTMemory VG_(clo_xtree_memory);
 341 /* Holds the filename to use for xtree memory profiling output, before expansion
 342    of %p and %q templates. */
 343 extern const HChar* VG_(clo_xtree_memory_file);
 344 /* Compress strings in xtree dumps. */
 345 extern Bool VG_(clo_xtree_compress_strings);
 346
 347 /* Number of parents of a backtrace.  Default: 12  */
 348 extern Int   VG_(clo_backtrace_size);
 349
 350 /* Continue stack traces below main()?  Default: NO */
 351 extern Bool VG_(clo_show_below_main);
 352
 353 /* Keep symbols (and all other debuginfo) for code that is unloaded (dlclose
 354    or similar) so that stack traces can still give line/file info for
 355    previously captured stack traces.  e.g. ... showing where a block was
 356    allocated e.g. leaks of or accesses just outside a block. */
 357 extern Bool VG_(clo_keep_debuginfo);
 358
 359
 360 /* Used to expand file names.  "option_name" is the option name, eg.
 361    "--log-file".  'format' is what follows, eg. "cachegrind.out.%p".  In
 362    'format':
 363    - "%p" is replaced with PID.
 364    - "%q{QUAL}" is replaced with the environment variable $QUAL.  If $QUAL
 365      isn't set, we abort.  If the "{QUAL}" part is malformed, we abort.
 366    - "%%" is replaced with "%".
 367    Anything else after '%' causes an abort.
 368    If the format specifies a relative file name, it's put in the program's
 369    initial working directory.  If it specifies an absolute file name (ie.
 370    starts with '/') then it is put there.
 371
 372    Note that "option_name" has no effect on the returned string: the
 373    returned string depends only on "format" and the PIDs and
 374    environment variables that it references (if any). "option_name" is
 375    merely used in printing error messages, if an error message needs
 376    to be printed due to malformedness of the "format" argument.
 377 */
 378 extern HChar* VG_(expand_file_name)(const HChar* option_name,
 379                                     const HChar* format);
 380
 381 #endif   // __PUB_TOOL_OPTIONS_H
 382
 383 /*--------------------------------------------------------------------*/
 384 /*--- end                                                          ---*/
 385 /*--------------------------------------------------------------------*/