/thirdparty/breakpad/third_party/linux/include/gflags/gflags.h
C++ Header | 533 lines | 179 code | 62 blank | 292 comment | 3 complexity | 41634cf10972e2a80ee346b7bc34fec7 MD5 | raw file
1// Copyright (c) 2006, Google Inc. 2// All rights reserved. 3// 4// Redistribution and use in source and binary forms, with or without 5// modification, are permitted provided that the following conditions are 6// met: 7// 8// * Redistributions of source code must retain the above copyright 9// notice, this list of conditions and the following disclaimer. 10// * Redistributions in binary form must reproduce the above 11// copyright notice, this list of conditions and the following disclaimer 12// in the documentation and/or other materials provided with the 13// distribution. 14// * Neither the name of Google Inc. nor the names of its 15// contributors may be used to endorse or promote products derived from 16// this software without specific prior written permission. 17// 18// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30// --- 31// Author: Ray Sidney 32// Revamped and reorganized by Craig Silverstein 33// 34// This is the file that should be included by any file which declares 35// or defines a command line flag or wants to parse command line flags 36// or print a program usage message (which will include information about 37// flags). Executive summary, in the form of an example foo.cc file: 38// 39// #include "foo.h" // foo.h has a line "DECLARE_int32(start);" 40// 41// DEFINE_int32(end, 1000, "The last record to read"); 42// DECLARE_bool(verbose); // some other file has a DEFINE_bool(verbose, ...) 43// 44// void MyFunc() { 45// if (FLAGS_verbose) printf("Records %d-%d\n", FLAGS_start, FLAGS_end); 46// } 47// 48// Then, at the command-line: 49// ./foo --noverbose --start=5 --end=100 50// 51// For more details, see 52// doc/gflags.html 53// 54// --- A note about thread-safety: 55// 56// We describe many functions in this routine as being thread-hostile, 57// thread-compatible, or thread-safe. Here are the meanings we use: 58// 59// thread-safe: it is safe for multiple threads to call this routine 60// (or, when referring to a class, methods of this class) 61// concurrently. 62// thread-hostile: it is not safe for multiple threads to call this 63// routine (or methods of this class) concurrently. In gflags, 64// most thread-hostile routines are intended to be called early in, 65// or even before, main() -- that is, before threads are spawned. 66// thread-compatible: it is safe for multiple threads to read from 67// this variable (when applied to variables), or to call const 68// methods of this class (when applied to classes), as long as no 69// other thread is writing to the variable or calling non-const 70// methods of this class. 71 72#ifndef GOOGLE_GFLAGS_H_ 73#define GOOGLE_GFLAGS_H_ 74 75#include <string> 76#include <vector> 77 78// We care a lot about number of bits things take up. Unfortunately, 79// systems define their bit-specific ints in a lot of different ways. 80// We use our own way, and have a typedef to get there. 81// Note: these commands below may look like "#if 1" or "#if 0", but 82// that's because they were constructed that way at ./configure time. 83// Look at gflags.h.in to see how they're calculated (based on your config). 84#if 1 85#include <stdint.h> // the normal place uint16_t is defined 86#endif 87#if 1 88#include <sys/types.h> // the normal place u_int16_t is defined 89#endif 90#if 1 91#include <inttypes.h> // a third place for uint16_t or u_int16_t 92#endif 93 94namespace google { 95 96#if 1 // the C99 format 97typedef int32_t int32; 98typedef uint32_t uint32; 99typedef int64_t int64; 100typedef uint64_t uint64; 101#elif 1 // the BSD format 102typedef int32_t int32; 103typedef u_int32_t uint32; 104typedef int64_t int64; 105typedef u_int64_t uint64; 106#elif 0 // the windows (vc7) format 107typedef __int32 int32; 108typedef unsigned __int32 uint32; 109typedef __int64 int64; 110typedef unsigned __int64 uint64; 111#else 112#error Do not know how to define a 32-bit integer quantity on your system 113#endif 114 115// -------------------------------------------------------------------- 116// To actually define a flag in a file, use DEFINE_bool, 117// DEFINE_string, etc. at the bottom of this file. You may also find 118// it useful to register a validator with the flag. This ensures that 119// when the flag is parsed from the commandline, or is later set via 120// SetCommandLineOption, we call the validation function. 121// 122// The validation function should return true if the flag value is valid, and 123// false otherwise. If the function returns false for the new setting of the 124// flag, the flag will retain its current value. If it returns false for the 125// default value, InitGoogle will die. 126// 127// This function is safe to call at global construct time (as in the 128// example below). 129// 130// Example use: 131// static bool ValidatePort(const char* flagname, int32 value) { 132// if (value > 0 && value < 32768) // value is ok 133// return true; 134// printf("Invalid value for --%s: %d\n", flagname, (int)value); 135// return false; 136// } 137// DEFINE_int32(port, 0, "What port to listen on"); 138// static bool dummy = RegisterFlagValidator(&FLAGS_port, &ValidatePort); 139 140// Returns true if successfully registered, false if not (because the 141// first argument doesn't point to a command-line flag, or because a 142// validator is already registered for this flag). 143bool RegisterFlagValidator(const bool* flag, 144 bool (*validate_fn)(const char*, bool)); 145bool RegisterFlagValidator(const int32* flag, 146 bool (*validate_fn)(const char*, int32)); 147bool RegisterFlagValidator(const int64* flag, 148 bool (*validate_fn)(const char*, int64)); 149bool RegisterFlagValidator(const uint64* flag, 150 bool (*validate_fn)(const char*, uint64)); 151bool RegisterFlagValidator(const double* flag, 152 bool (*validate_fn)(const char*, double)); 153bool RegisterFlagValidator(const std::string* flag, 154 bool (*validate_fn)(const char*, const std::string&)); 155 156 157// -------------------------------------------------------------------- 158// These methods are the best way to get access to info about the 159// list of commandline flags. Note that these routines are pretty slow. 160// GetAllFlags: mostly-complete info about the list, sorted by file. 161// ShowUsageWithFlags: pretty-prints the list to stdout (what --help does) 162// ShowUsageWithFlagsRestrict: limit to filenames with restrict as a substr 163// 164// In addition to accessing flags, you can also access argv[0] (the program 165// name) and argv (the entire commandline), which we sock away a copy of. 166// These variables are static, so you should only set them once. 167 168struct CommandLineFlagInfo { 169 std::string name; // the name of the flag 170 std::string type; // the type of the flag: int32, etc 171 std::string description; // the "help text" associated with the flag 172 std::string current_value; // the current value, as a string 173 std::string default_value; // the default value, as a string 174 std::string filename; // 'cleaned' version of filename holding the flag 175 bool has_validator_fn; // true if RegisterFlagValidator called on flag 176 bool is_default; // true if the flag has default value 177}; 178 179extern void GetAllFlags(std::vector<CommandLineFlagInfo>* OUTPUT); 180// These two are actually defined in commandlineflags_reporting.cc. 181extern void ShowUsageWithFlags(const char *argv0); // what --help does 182extern void ShowUsageWithFlagsRestrict(const char *argv0, const char *restrict); 183 184// Create a descriptive string for a flag. 185// Goes to some trouble to make pretty line breaks. 186extern std::string DescribeOneFlag(const CommandLineFlagInfo& flag); 187 188// Thread-hostile; meant to be called before any threads are spawned. 189extern void SetArgv(int argc, const char** argv); 190// The following functions are thread-safe as long as SetArgv() is 191// only called before any threads start. 192extern const std::vector<std::string>& GetArgvs(); // all of argv as a vector 193extern const char* GetArgv(); // all of argv as a string 194extern const char* GetArgv0(); // only argv0 195extern uint32 GetArgvSum(); // simple checksum of argv 196extern const char* ProgramInvocationName(); // argv0, or "UNKNOWN" if not set 197extern const char* ProgramInvocationShortName(); // basename(argv0) 198// ProgramUsage() is thread-safe as long as SetUsageMessage() is only 199// called before any threads start. 200extern const char* ProgramUsage(); // string set by SetUsageMessage() 201 202 203// -------------------------------------------------------------------- 204// Normally you access commandline flags by just saying "if (FLAGS_foo)" 205// or whatever, and set them by calling "FLAGS_foo = bar" (or, more 206// commonly, via the DEFINE_foo macro). But if you need a bit more 207// control, we have programmatic ways to get/set the flags as well. 208// These programmatic ways to access flags are thread-safe, but direct 209// access is only thread-compatible. 210 211// Return true iff the flagname was found. 212// OUTPUT is set to the flag's value, or unchanged if we return false. 213extern bool GetCommandLineOption(const char* name, std::string* OUTPUT); 214 215// Return true iff the flagname was found. OUTPUT is set to the flag's 216// CommandLineFlagInfo or unchanged if we return false. 217extern bool GetCommandLineFlagInfo(const char* name, 218 CommandLineFlagInfo* OUTPUT); 219 220// Return the CommandLineFlagInfo of the flagname. exit() if name not found. 221// Example usage, to check if a flag's value is currently the default value: 222// if (GetCommandLineFlagInfoOrDie("foo").is_default) ... 223extern CommandLineFlagInfo GetCommandLineFlagInfoOrDie(const char* name); 224 225enum FlagSettingMode { 226 // update the flag's value (can call this multiple times). 227 SET_FLAGS_VALUE, 228 // update the flag's value, but *only if* it has not yet been updated 229 // with SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef". 230 SET_FLAG_IF_DEFAULT, 231 // set the flag's default value to this. If the flag has not yet updated 232 // yet (via SET_FLAGS_VALUE, SET_FLAG_IF_DEFAULT, or "FLAGS_xxx = nondef") 233 // change the flag's current value to the new default value as well. 234 SET_FLAGS_DEFAULT 235}; 236 237// Set a particular flag ("command line option"). Returns a string 238// describing the new value that the option has been set to. The 239// return value API is not well-specified, so basically just depend on 240// it to be empty if the setting failed for some reason -- the name is 241// not a valid flag name, or the value is not a valid value -- and 242// non-empty else. 243 244// SetCommandLineOption uses set_mode == SET_FLAGS_VALUE (the common case) 245extern std::string SetCommandLineOption(const char* name, const char* value); 246extern std::string SetCommandLineOptionWithMode(const char* name, const char* value, 247 FlagSettingMode set_mode); 248 249 250// -------------------------------------------------------------------- 251// Saves the states (value, default value, whether the user has set 252// the flag, registered validators, etc) of all flags, and restores 253// them when the FlagSaver is destroyed. This is very useful in 254// tests, say, when you want to let your tests change the flags, but 255// make sure that they get reverted to the original states when your 256// test is complete. 257// 258// Example usage: 259// void TestFoo() { 260// FlagSaver s1; 261// FLAG_foo = false; 262// FLAG_bar = "some value"; 263// 264// // test happens here. You can return at any time 265// // without worrying about restoring the FLAG values. 266// } 267// 268// Note: This class is marked with __attribute__((unused)) because all the 269// work is done in the constructor and destructor, so in the standard 270// usage example above, the compiler would complain that it's an 271// unused variable. 272// 273// This class is thread-safe. 274 275class FlagSaver { 276 public: 277 FlagSaver(); 278 ~FlagSaver(); 279 280 private: 281 class FlagSaverImpl* impl_; // we use pimpl here to keep API steady 282 283 FlagSaver(const FlagSaver&); // no copying! 284 void operator=(const FlagSaver&); 285} __attribute__ ((unused)); 286 287// -------------------------------------------------------------------- 288// Some deprecated or hopefully-soon-to-be-deprecated functions. 289 290// This is often used for logging. TODO(csilvers): figure out a better way 291extern std::string CommandlineFlagsIntoString(); 292// Usually where this is used, a FlagSaver should be used instead. 293extern bool ReadFlagsFromString(const std::string& flagfilecontents, 294 const char* prog_name, 295 bool errors_are_fatal); // uses SET_FLAGS_VALUE 296 297// These let you manually implement --flagfile functionality. 298// DEPRECATED. 299extern bool AppendFlagsIntoFile(const std::string& filename, const char* prog_name); 300extern bool SaveCommandFlags(); // actually defined in google.cc ! 301extern bool ReadFromFlagsFile(const std::string& filename, const char* prog_name, 302 bool errors_are_fatal); // uses SET_FLAGS_VALUE 303 304 305// -------------------------------------------------------------------- 306// Useful routines for initializing flags from the environment. 307// In each case, if 'varname' does not exist in the environment 308// return defval. If 'varname' does exist but is not valid 309// (e.g., not a number for an int32 flag), abort with an error. 310// Otherwise, return the value. NOTE: for booleans, for true use 311// 't' or 'T' or 'true' or '1', for false 'f' or 'F' or 'false' or '0'. 312 313extern bool BoolFromEnv(const char *varname, bool defval); 314extern int32 Int32FromEnv(const char *varname, int32 defval); 315extern int64 Int64FromEnv(const char *varname, int64 defval); 316extern uint64 Uint64FromEnv(const char *varname, uint64 defval); 317extern double DoubleFromEnv(const char *varname, double defval); 318extern const char *StringFromEnv(const char *varname, const char *defval); 319 320 321// -------------------------------------------------------------------- 322// The next two functions parse commandlineflags from main(): 323 324// Set the "usage" message for this program. For example: 325// string usage("This program does nothing. Sample usage:\n"); 326// usage += argv[0] + " <uselessarg1> <uselessarg2>"; 327// SetUsageMessage(usage); 328// Do not include commandline flags in the usage: we do that for you! 329// Thread-hostile; meant to be called before any threads are spawned. 330extern void SetUsageMessage(const std::string& usage); 331 332// Looks for flags in argv and parses them. Rearranges argv to put 333// flags first, or removes them entirely if remove_flags is true. 334// If a flag is defined more than once in the command line or flag 335// file, the last definition is used. 336// See top-of-file for more details on this function. 337#ifndef SWIG // In swig, use ParseCommandLineFlagsScript() instead. 338extern uint32 ParseCommandLineFlags(int *argc, char*** argv, 339 bool remove_flags); 340#endif 341 342 343// Calls to ParseCommandLineNonHelpFlags and then to 344// HandleCommandLineHelpFlags can be used instead of a call to 345// ParseCommandLineFlags during initialization, in order to allow for 346// changing default values for some FLAGS (via 347// e.g. SetCommandLineOptionWithMode calls) between the time of 348// command line parsing and the time of dumping help information for 349// the flags as a result of command line parsing. 350// If a flag is defined more than once in the command line or flag 351// file, the last definition is used. 352extern uint32 ParseCommandLineNonHelpFlags(int *argc, char*** argv, 353 bool remove_flags); 354// This is actually defined in commandlineflags_reporting.cc. 355// This function is misnamed (it also handles --version, etc.), but 356// it's too late to change that now. :-( 357extern void HandleCommandLineHelpFlags(); // in commandlineflags_reporting.cc 358 359// Allow command line reparsing. Disables the error normally 360// generated when an unknown flag is found, since it may be found in a 361// later parse. Thread-hostile; meant to be called before any threads 362// are spawned. 363extern void AllowCommandLineReparsing(); 364 365// Reparse the flags that have not yet been recognized. 366// Only flags registered since the last parse will be recognized. 367// Any flag value must be provided as part of the argument using "=", 368// not as a separate command line argument that follows the flag argument. 369// Intended for handling flags from dynamically loaded libraries, 370// since their flags are not registered until they are loaded. 371extern uint32 ReparseCommandLineNonHelpFlags(); 372 373 374// -------------------------------------------------------------------- 375// Now come the command line flag declaration/definition macros that 376// will actually be used. They're kind of hairy. A major reason 377// for this is initialization: we want people to be able to access 378// variables in global constructors and have that not crash, even if 379// their global constructor runs before the global constructor here. 380// (Obviously, we can't guarantee the flags will have the correct 381// default value in that case, but at least accessing them is safe.) 382// The only way to do that is have flags point to a static buffer. 383// So we make one, using a union to ensure proper alignment, and 384// then use placement-new to actually set up the flag with the 385// correct default value. In the same vein, we have to worry about 386// flag access in global destructors, so FlagRegisterer has to be 387// careful never to destroy the flag-values it constructs. 388// 389// Note that when we define a flag variable FLAGS_<name>, we also 390// preemptively define a junk variable, FLAGS_no<name>. This is to 391// cause a link-time error if someone tries to define 2 flags with 392// names like "logging" and "nologging". We do this because a bool 393// flag FLAG can be set from the command line to true with a "-FLAG" 394// argument, and to false with a "-noFLAG" argument, and so this can 395// potentially avert confusion. 396// 397// We also put flags into their own namespace. It is purposefully 398// named in an opaque way that people should have trouble typing 399// directly. The idea is that DEFINE puts the flag in the weird 400// namespace, and DECLARE imports the flag from there into the current 401// namespace. The net result is to force people to use DECLARE to get 402// access to a flag, rather than saying "extern bool FLAGS_whatever;" 403// or some such instead. We want this so we can put extra 404// functionality (like sanity-checking) in DECLARE if we want, and 405// make sure it is picked up everywhere. 406// 407// We also put the type of the variable in the namespace, so that 408// people can't DECLARE_int32 something that they DEFINE_bool'd 409// elsewhere. 410 411class FlagRegisterer { 412 public: 413 FlagRegisterer(const char* name, const char* type, 414 const char* help, const char* filename, 415 void* current_storage, void* defvalue_storage); 416}; 417 418extern bool FlagsTypeWarn(const char *name); 419 420// If your application #defines STRIP_FLAG_HELP to a non-zero value 421// before #including this file, we remove the help message from the 422// binary file. This can reduce the size of the resulting binary 423// somewhat, and may also be useful for security reasons. 424 425extern const char kStrippedFlagHelp[]; 426 427} 428 429#ifndef SWIG // In swig, ignore the main flag declarations 430 431#if defined(STRIP_FLAG_HELP) && STRIP_FLAG_HELP > 0 432// Need this construct to avoid the 'defined but not used' warning. 433#define MAYBE_STRIPPED_HELP(txt) (false ? (txt) : kStrippedFlagHelp) 434#else 435#define MAYBE_STRIPPED_HELP(txt) txt 436#endif 437 438// Each command-line flag has two variables associated with it: one 439// with the current value, and one with the default value. However, 440// we have a third variable, which is where value is assigned; it's a 441// constant. This guarantees that FLAG_##value is initialized at 442// static initialization time (e.g. before program-start) rather than 443// than global construction time (which is after program-start but 444// before main), at least when 'value' is a compile-time constant. We 445// use a small trick for the "default value" variable, and call it 446// FLAGS_no<name>. This serves the second purpose of assuring a 447// compile error if someone tries to define a flag named no<name> 448// which is illegal (--foo and --nofoo both affect the "foo" flag). 449#define DEFINE_VARIABLE(type, shorttype, name, value, help) \ 450 namespace fL##shorttype { \ 451 static const type FLAGS_nono##name = value; \ 452 type FLAGS_##name = FLAGS_nono##name; \ 453 type FLAGS_no##name = FLAGS_nono##name; \ 454 static ::google::FlagRegisterer o_##name( \ 455 #name, #type, MAYBE_STRIPPED_HELP(help), __FILE__, \ 456 &FLAGS_##name, &FLAGS_no##name); \ 457 } \ 458 using fL##shorttype::FLAGS_##name 459 460#define DECLARE_VARIABLE(type, shorttype, name) \ 461 namespace fL##shorttype { \ 462 extern type FLAGS_##name; \ 463 } \ 464 using fL##shorttype::FLAGS_##name 465 466// For DEFINE_bool, we want to do the extra check that the passed-in 467// value is actually a bool, and not a string or something that can be 468// coerced to a bool. These declarations (no definition needed!) will 469// help us do that, and never evaluate From, which is important. 470// We'll use 'sizeof(IsBool(val))' to distinguish. This code requires 471// that the compiler have different sizes for bool & double. Since 472// this is not guaranteed by the standard, we check it with a 473// compile-time assert (msg[-1] will give a compile-time error). 474namespace fLB { 475struct CompileAssert {}; 476typedef CompileAssert expected_sizeof_double_neq_sizeof_bool[ 477 (sizeof(double) != sizeof(bool)) ? 1 : -1]; 478template<typename From> double IsBoolFlag(const From& from); 479bool IsBoolFlag(bool from); 480} // namespace fLB 481 482#define DECLARE_bool(name) DECLARE_VARIABLE(bool,B, name) 483#define DEFINE_bool(name,val,txt) \ 484 namespace fLB { \ 485 typedef CompileAssert FLAG_##name##_value_is_not_a_bool[ \ 486 (sizeof(::fLB::IsBoolFlag(val)) != sizeof(double)) ? 1 : -1]; \ 487 } \ 488 DEFINE_VARIABLE(bool,B, name, val, txt) 489 490#define DECLARE_int32(name) DECLARE_VARIABLE(::google::int32,I, name) 491#define DEFINE_int32(name,val,txt) DEFINE_VARIABLE(::google::int32,I, name, val, txt) 492 493#define DECLARE_int64(name) DECLARE_VARIABLE(::google::int64,I64, name) 494#define DEFINE_int64(name,val,txt) DEFINE_VARIABLE(::google::int64,I64, name, val, txt) 495 496#define DECLARE_uint64(name) DECLARE_VARIABLE(::google::uint64,U64, name) 497#define DEFINE_uint64(name,val,txt) DEFINE_VARIABLE(::google::uint64,U64, name, val, txt) 498 499#define DECLARE_double(name) DECLARE_VARIABLE(double,D, name) 500#define DEFINE_double(name,val,txt) DEFINE_VARIABLE(double,D, name, val, txt) 501 502// Strings are trickier, because they're not a POD, so we can't 503// construct them at static-initialization time (instead they get 504// constructed at global-constructor time, which is much later). To 505// try to avoid crashes in that case, we use a char buffer to store 506// the string, which we can static-initialize, and then placement-new 507// into it later. It's not perfect, but the best we can do. 508#define DECLARE_string(name) namespace fLS { extern std::string& FLAGS_##name; } \ 509 using fLS::FLAGS_##name 510 511// We need to define a var named FLAGS_no##name so people don't define 512// --string and --nostring. And we need a temporary place to put val 513// so we don't have to evaluate it twice. Two great needs that go 514// great together! 515// The weird 'using' + 'extern' inside the fLS namespace is to work around 516// an unknown compiler bug/issue with the gcc 4.2.1 on SUSE 10. See 517// http://code.google.com/p/google-gflags/issues/detail?id=20 518#define DEFINE_string(name, val, txt) \ 519 namespace fLS { \ 520 static union { void* align; char s[sizeof(std::string)]; } s_##name[2]; \ 521 const std::string* const FLAGS_no##name = new (s_##name[0].s) std::string(val); \ 522 static ::google::FlagRegisterer o_##name( \ 523 #name, "string", MAYBE_STRIPPED_HELP(txt), __FILE__, \ 524 s_##name[0].s, new (s_##name[1].s) std::string(*FLAGS_no##name)); \ 525 extern std::string& FLAGS_##name; \ 526 using fLS::FLAGS_##name; \ 527 std::string& FLAGS_##name = *(reinterpret_cast<std::string*>(s_##name[0].s)); \ 528 } \ 529 using fLS::FLAGS_##name 530 531#endif // SWIG 532 533#endif // GOOGLE_GFLAGS_H_