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, write to the Free Software
  25    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  26    02111-1307, USA.
  27
  28    The GNU General Public License is contained in the file COPYING.
  29 */
  30
  31 #ifndef __PUB_TOOL_OPTIONS_H
  32 #define __PUB_TOOL_OPTIONS_H
  33
  34 #include "pub_tool_basics.h"     // for VG_ macro
  35 #include "libvex.h"              // for VexControl
  36
  37
  38 // Higher-level command-line option recognisers;  use in if/else chains.
  39 // Note that they assign a value to the 'qq_var' argument.  So often they
  40 // can be used like this:
  41 //
  42 //   if VG_STR_CLO(arg, "--foo", clo_foo) { }
  43 //
  44 // But if you want to do further checking or processing, you can do this:
  45 //
  46 //   if VG_STR_CLO(arg, "--foo", clo_foo) { <further checking or processing> }
  47 //
  48 // They use GNU statement expressions to do the qq_var assignment within a
  49 // conditional expression.
  50
  51 // String argument, eg. --foo=yes or --foo=no
  52 #define VG_BOOL_CLO(qq_arg, qq_option, qq_var) \
  53    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
  54     ({ \
  55       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
  56       if      VG_STREQ(val, "yes") (qq_var) = True; \
  57       else if VG_STREQ(val, "no")  (qq_var) = False; \
  58       else VG_(fmsg_bad_option)(qq_arg, "Invalid boolean value '%s'" \
  59                                 " (should be 'yes' or 'no')\n", val);    \
  60       True; \
  61     }) \
  62    )
  63
  64 // String argument, eg. --foo=bar
  65 #define VG_STR_CLO(qq_arg, qq_option, qq_var) \
  66    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
  67     ({ \
  68       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
  69       (qq_var) = val; \
  70       True; \
  71     }) \
  72    )
  73
  74 // UInt enum set arg, eg. --foo=fubar,bar,baz or --foo=none
  75 // or --foo=all  (if qq_all is True)
  76 #define VG_USETGEN_CLO(qq_arg, qq_option, qq_vals, qq_var, qq_all) \
  77    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
  78     ({ \
  79       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
  80       if (!VG_(parse_enum_set)(qq_vals, \
  81                                qq_all,/*allow_all*/ \
  82                                val, \
  83                                &(qq_var))) \
  84             VG_(fmsg_bad_option)(qq_arg, "%s is an invalid %s set\n", \
  85                                  val, qq_option+2); \
  86       True; \
  87      }) \
  88     )
  89
  90 // UInt enum set arg, eg. --foo=fubar,bar,baz or --foo=none or --foo=all
  91 #define VG_USET_CLO(qq_arg, qq_option, qq_vals, qq_var) \
  92    VG_USETGEN_CLO((qq_arg), qq_option, (qq_vals), (qq_var), True)
  93
  94 /* Same as VG_USET_CLO but not allowing --foo=all.
  95    To be used when some or all of the enum set are mutually eXclusive. */
  96 #define VG_USETX_CLO(qq_arg, qq_option, qq_vals, qq_var) \
  97    VG_USETGEN_CLO((qq_arg), qq_option, (qq_vals), (qq_var), False)
  98
  99 // Unbounded integer arg, eg. --foo=10
 100 #define VG_INT_CLO(qq_arg, qq_option, qq_var) \
 101    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
 102     ({ \
 103       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
 104       HChar* s; \
 105       Long n = VG_(strtoll10)( val, &s ); \
 106       (qq_var) = n; \
 107       /* Check for non-numeralness, or overflow. */ \
 108       if ('\0' != s[0] || (qq_var) != n) VG_(fmsg_bad_option)(qq_arg, \
 109                                   "Invalid integer value '%s'\n", val); \
 110       True; \
 111      }) \
 112     )
 113
 114 // Bounded integer arg, eg. --foo=10 ;  if the value exceeds the bounds it
 115 // causes an abort.  'qq_base' can be 10 or 16.
 116 #define VG_BINTN_CLO(qq_base, qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 117    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
 118     ({ \
 119       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
 120       HChar* s; \
 121       Long n = VG_(strtoll##qq_base)( val, &s ); \
 122       (qq_var) = n; \
 123       /* MMM: separate the two cases, and explain the problem;  likewise */ \
 124       /* for all the other macros in this file. */ \
 125       /* Check for non-numeralness, or overflow. */ \
 126       /* Nb: it will overflow if qq_var is unsigned and qq_val is negative! */ \
 127       if ('\0' != s[0] || (qq_var) != n) VG_(fmsg_bad_option)(qq_arg, \
 128                                   "Invalid integer value '%s'\n", val); \
 129       /* Check bounds. */ \
 130       if ((qq_var) < (qq_lo) || (qq_var) > (qq_hi)) { \
 131          VG_(fmsg_bad_option)(qq_arg, \
 132             "'%s' argument must be between %lld and %lld\n", \
 133             (qq_option), (Long)(qq_lo), (Long)(qq_hi)); \
 134       } \
 135       True; \
 136      }) \
 137     )
 138
 139 // Bounded decimal integer arg, eg. --foo=100
 140 #define VG_BINT_CLO(qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 141    VG_BINTN_CLO(10, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 142
 143 // Bounded hexadecimal integer arg, eg. --foo=0x1fa8
 144 #define VG_BHEX_CLO(qq_arg, qq_option, qq_var, qq_lo, qq_hi) \
 145    VG_BINTN_CLO(16, (qq_arg), qq_option, (qq_var), (qq_lo), (qq_hi))
 146
 147 // Double (decimal) arg, eg. --foo=4.6
 148 // XXX: there's not VG_BDBL_CLO because we don't have a good way of printing
 149 // floats at the moment!
 150 #define VG_DBL_CLO(qq_arg, qq_option, qq_var) \
 151    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
 152     ({ \
 153       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
 154       HChar* s; \
 155       double n = VG_(strtod)( val, &s ); \
 156       (qq_var) = n; \
 157       /* Check for non-numeralness */ \
 158       if ('\0' != s[0]) VG_(fmsg_bad_option)(qq_arg, \
 159                             "Invalid floating point value '%s'\n",val); \
 160       True; \
 161      }) \
 162     )
 163
 164 // Arg whose value is denoted by the exact presence of the given string;
 165 // if it matches, qq_var is assigned the value in qq_val.
 166 #define VG_XACT_CLO(qq_arg, qq_option, qq_var, qq_val) \
 167    (VG_STREQ((qq_arg), (qq_option)) && \
 168     ({ \
 169       (qq_var) = (qq_val); \
 170       True; \
 171     }) \
 172    )
 173
 174 // Arg that can be one of a set of strings, as specified in an NULL
 175 // terminated array.  Returns the index of the string in |qq_ix|, or
 176 // aborts if not found.
 177 #define VG_STRINDEX_CLO(qq_arg, qq_option, qq_strings, qq_ix) \
 178    (VG_STREQN(VG_(strlen)(qq_option)+1, qq_arg, qq_option"=") && \
 179     ({ \
 180       const HChar* val = &(qq_arg)[ VG_(strlen)(qq_option)+1 ]; \
 181       for (qq_ix = 0; (qq_strings)[qq_ix]; qq_ix++) { \
 182          if (VG_STREQ(val, (qq_strings)[qq_ix])) \
 183             break; \
 184       } \
 185       if ((qq_strings)[qq_ix] == NULL) \
 186          VG_(fmsg_bad_option)(qq_arg, \
 187                               "Invalid string '%s' in '%s'\n", val, qq_arg); \
 188       True; \
 189      }) \
 190     )
 191
 192 /* Verbosity level: 0 = silent, 1 (default), > 1 = more verbose. */
 193 extern Int  VG_(clo_verbosity);
 194
 195 /* Show tool and core statistics */
 196 extern Bool VG_(clo_stats);
 197
 198 /* wait for vgdb/gdb after reporting that amount of error.
 199    Note that this is the initial value provided from the command line.
 200    The real value is maintained in VG_(dyn_vgdb_error) and
 201    can be changed dynamically.*/
 202 extern Int VG_(clo_vgdb_error);
 203
 204 /* If user has provided the --vgdb-prefix command line option,
 205    VG_(arg_vgdb_prefix) points at the provided argument (including the
 206    '--vgdb-prefix=' string).
 207    Otherwise, it is NULL.
 208    Typically, this is used by tools to produce user message with the
 209    expected vgdb prefix argument, if the user has changed the default. */
 210 extern const HChar *VG_(arg_vgdb_prefix);
 211
 212 /* Emit all messages as XML? default: NO */
 213 /* If clo_xml is set, various other options are set in a non-default
 214    way.  See vg_main.c and mc_main.c. */
 215 extern Bool VG_(clo_xml);
 216
 217 /* An arbitrary user-supplied string which is copied into the
 218    XML output, in between <usercomment> tags. */
 219 extern const HChar* VG_(clo_xml_user_comment);
 220
 221 /* Vex iropt control.  Tool-visible so tools can make Vex optimise
 222    less aggressively if that is needed (callgrind needs this). */
 223 extern VexControl VG_(clo_vex_control);
 224 extern VexRegisterUpdates VG_(clo_px_file_backed);
 225
 226 extern Int VG_(clo_redzone_size);
 227
 228 typedef
 229    enum {
 230       Vg_XTMemory_None,   // Do not do any xtree memory profiling.
 231       Vg_XTMemory_Allocs, // Currently allocated size xtree memory profiling
 232       Vg_XTMemory_Full,   // Full profiling : Current allocated size, total
 233       // allocated size, nr of blocks, total freed size, ...
 234    }
 235    VgXTMemory;
 236 // Tools that replace malloc can optionally implement memory profiling
 237 // following the value of VG_(clo_xtree_profile_memory) to produce a report
 238 // at the end of execution.
 239 extern VgXTMemory VG_(clo_xtree_memory);
 240 /* Holds the filename to use for xtree memory profiling output, before expansion
 241    of %p and %q templates. */
 242 extern const HChar* VG_(clo_xtree_memory_file);
 243 /* Compress strings in xtree dumps. */
 244 extern Bool VG_(clo_xtree_compress_strings);
 245
 246 /* Number of parents of a backtrace.  Default: 12  */
 247 extern Int   VG_(clo_backtrace_size);
 248
 249 /* Continue stack traces below main()?  Default: NO */
 250 extern Bool VG_(clo_show_below_main);
 251
 252 /* Keep symbols (and all other debuginfo) for code that is unloaded (dlclose
 253    or similar) so that stack traces can still give line/file info for
 254    previously captured stack traces.  e.g. ... showing where a block was
 255    allocated e.g. leaks of or accesses just outside a block. */
 256 extern Bool VG_(clo_keep_debuginfo);
 257
 258
 259 /* Used to expand file names.  "option_name" is the option name, eg.
 260    "--log-file".  'format' is what follows, eg. "cachegrind.out.%p".  In
 261    'format':
 262    - "%p" is replaced with PID.
 263    - "%q{QUAL}" is replaced with the environment variable $QUAL.  If $QUAL
 264      isn't set, we abort.  If the "{QUAL}" part is malformed, we abort.
 265    - "%%" is replaced with "%".
 266    Anything else after '%' causes an abort.
 267    If the format specifies a relative file name, it's put in the program's
 268    initial working directory.  If it specifies an absolute file name (ie.
 269    starts with '/') then it is put there.
 270
 271    Note that "option_name" has no effect on the returned string: the
 272    returned string depends only on "format" and the PIDs and
 273    environment variables that it references (if any). "option_name" is
 274    merely used in printing error messages, if an error message needs
 275    to be printed due to malformedness of the "format" argument.
 276 */
 277 extern HChar* VG_(expand_file_name)(const HChar* option_name,
 278                                     const HChar* format);
 279
 280 #endif   // __PUB_TOOL_OPTIONS_H
 281
 282 /*--------------------------------------------------------------------*/
 283 /*--- end                                                          ---*/
 284 /*--------------------------------------------------------------------*/