Bitcoin Core  26.99.0
P2P Digital Currency
args.h
Go to the documentation of this file.
1 // Copyright (c) 2023 The Bitcoin Core developers
2 // Distributed under the MIT software license, see the accompanying
3 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
4 
5 #ifndef BITCOIN_COMMON_ARGS_H
6 #define BITCOIN_COMMON_ARGS_H
7 
8 #include <common/settings.h>
9 #include <compat/compat.h>
10 #include <sync.h>
11 #include <util/chaintype.h>
12 #include <util/fs.h>
13 
14 #include <iosfwd>
15 #include <list>
16 #include <map>
17 #include <optional>
18 #include <set>
19 #include <stdint.h>
20 #include <string>
21 #include <variant>
22 #include <vector>
23 
24 class ArgsManager;
25 
26 extern const char * const BITCOIN_CONF_FILENAME;
27 extern const char * const BITCOIN_SETTINGS_FILENAME;
28 
29 // Return true if -datadir option points to a valid directory or is not specified.
31 
41 fs::path AbsPathForConfigVal(const ArgsManager& args, const fs::path& path, bool net_specific = true);
42 
43 inline bool IsSwitchChar(char c)
44 {
45 #ifdef WIN32
46  return c == '-' || c == '/';
47 #else
48  return c == '-';
49 #endif
50 }
51 
52 enum class OptionsCategory {
53  OPTIONS,
54  CONNECTION,
55  WALLET,
57  ZMQ,
58  DEBUG_TEST,
60  NODE_RELAY,
62  RPC,
63  GUI,
64  COMMANDS,
66 
67  HIDDEN // Always the last option to avoid printing these in the help
68 };
69 
70 struct KeyInfo {
71  std::string name;
72  std::string section;
73  bool negated{false};
74 };
75 
76 KeyInfo InterpretKey(std::string key);
77 
78 std::optional<common::SettingsValue> InterpretValue(const KeyInfo& key, const std::string* value,
79  unsigned int flags, std::string& error);
80 
81 struct SectionInfo {
82  std::string m_name;
83  std::string m_file;
84  int m_line;
85 };
86 
87 std::string SettingToString(const common::SettingsValue&, const std::string&);
88 std::optional<std::string> SettingToString(const common::SettingsValue&);
89 
90 int64_t SettingToInt(const common::SettingsValue&, int64_t);
91 std::optional<int64_t> SettingToInt(const common::SettingsValue&);
92 
93 bool SettingToBool(const common::SettingsValue&, bool);
94 std::optional<bool> SettingToBool(const common::SettingsValue&);
95 
97 {
98 public:
103  enum Flags : uint32_t {
104  ALLOW_ANY = 0x01,
105  // ALLOW_BOOL = 0x02, //!< unimplemented, draft implementation in #16545
106  // ALLOW_INT = 0x04, //!< unimplemented, draft implementation in #16545
107  // ALLOW_STRING = 0x08, //!< unimplemented, draft implementation in #16545
108  // ALLOW_LIST = 0x10, //!< unimplemented, draft implementation in #16545
111 
112  DEBUG_ONLY = 0x100,
113  /* Some options would cause cross-contamination if values for
114  * mainnet were used while running on regtest/testnet (or vice-versa).
115  * Setting them as NETWORK_ONLY ensures that sharing a config file
116  * between mainnet and regtest/testnet won't cause problems due to these
117  * parameters by accident. */
118  NETWORK_ONLY = 0x200,
119  // This argument's value is sensitive (such as a password).
120  SENSITIVE = 0x400,
121  COMMAND = 0x800,
122  };
123 
124 protected:
125  struct Arg
126  {
127  std::string m_help_param;
128  std::string m_help_text;
129  unsigned int m_flags;
130  };
131 
134  std::vector<std::string> m_command GUARDED_BY(cs_args);
135  std::string m_network GUARDED_BY(cs_args);
136  std::set<std::string> m_network_only_args GUARDED_BY(cs_args);
137  std::map<OptionsCategory, std::map<std::string, Arg>> m_available_args GUARDED_BY(cs_args);
138  bool m_accept_any_command GUARDED_BY(cs_args){true};
139  std::list<SectionInfo> m_config_sections GUARDED_BY(cs_args);
140  std::optional<fs::path> m_config_path GUARDED_BY(cs_args);
141  mutable fs::path m_cached_blocks_path GUARDED_BY(cs_args);
142  mutable fs::path m_cached_datadir_path GUARDED_BY(cs_args);
143  mutable fs::path m_cached_network_datadir_path GUARDED_BY(cs_args);
144 
145  [[nodiscard]] bool ReadConfigStream(std::istream& stream, const std::string& filepath, std::string& error, bool ignore_invalid_keys = false);
146 
152  bool UseDefaultSection(const std::string& arg) const EXCLUSIVE_LOCKS_REQUIRED(cs_args);
153 
154  public:
162  common::SettingsValue GetSetting(const std::string& arg) const;
163 
167  std::vector<common::SettingsValue> GetSettingsList(const std::string& arg) const;
168 
171 
175  void SelectConfigNetwork(const std::string& network);
176 
177  [[nodiscard]] bool ParseParameters(int argc, const char* const argv[], std::string& error);
178 
182  fs::path GetConfigFilePath() const;
184  [[nodiscard]] bool ReadConfigFiles(std::string& error, bool ignore_invalid_keys = false);
185 
192  std::set<std::string> GetUnsuitableSectionOnlyArgs() const;
193 
197  std::list<SectionInfo> GetUnrecognizedSections() const;
198 
199  struct Command {
201  std::string command;
206  std::vector<std::string> args;
207  };
211  std::optional<const Command> GetCommand() const;
212 
218  fs::path GetBlocksDirPath() const;
219 
225  fs::path GetDataDirBase() const { return GetDataDir(false); }
226 
232  fs::path GetDataDirNet() const { return GetDataDir(true); }
233 
237  void ClearPathCache();
238 
245  std::vector<std::string> GetArgs(const std::string& strArg) const;
246 
253  bool IsArgSet(const std::string& strArg) const;
254 
262  bool IsArgNegated(const std::string& strArg) const;
263 
271  std::string GetArg(const std::string& strArg, const std::string& strDefault) const;
272  std::optional<std::string> GetArg(const std::string& strArg) const;
273 
284  fs::path GetPathArg(std::string arg, const fs::path& default_value = {}) const;
285 
293  int64_t GetIntArg(const std::string& strArg, int64_t nDefault) const;
294  std::optional<int64_t> GetIntArg(const std::string& strArg) const;
295 
303  bool GetBoolArg(const std::string& strArg, bool fDefault) const;
304  std::optional<bool> GetBoolArg(const std::string& strArg) const;
305 
313  bool SoftSetArg(const std::string& strArg, const std::string& strValue);
314 
322  bool SoftSetBoolArg(const std::string& strArg, bool fValue);
323 
324  // Forces an arg setting. Called by SoftSetArg() if the arg hasn't already
325  // been set. Also called directly in testing.
326  void ForceSetArg(const std::string& strArg, const std::string& strValue);
327 
333  ChainType GetChainType() const;
334 
340  std::string GetChainTypeString() const;
341 
345  void AddArg(const std::string& name, const std::string& help, unsigned int flags, const OptionsCategory& cat);
346 
350  void AddCommand(const std::string& cmd, const std::string& help);
351 
355  void AddHiddenArgs(const std::vector<std::string>& args);
356 
360  void ClearArgs() {
361  LOCK(cs_args);
362  m_available_args.clear();
363  m_network_only_args.clear();
364  }
365 
369  std::string GetHelpMessage() const;
370 
375  std::optional<unsigned int> GetArgFlags(const std::string& name) const;
376 
381  bool GetSettingsPath(fs::path* filepath = nullptr, bool temp = false, bool backup = false) const;
382 
386  bool ReadSettingsFile(std::vector<std::string>* errors = nullptr);
387 
392  bool WriteSettingsFile(std::vector<std::string>* errors = nullptr, bool backup = false) const;
393 
398  common::SettingsValue GetPersistentSetting(const std::string& name) const;
399 
403  template <typename Fn>
404  void LockSettings(Fn&& fn)
405  {
406  LOCK(cs_args);
407  fn(m_settings);
408  }
409 
414  void LogArgs() const;
415 
416 private:
423  fs::path GetDataDir(bool net_specific) const;
424 
431  std::variant<ChainType, std::string> GetChainArg() const;
432 
433  // Helper function for LogArgs().
434  void logArgsPrefix(
435  const std::string& prefix,
436  const std::string& section,
437  const std::map<std::string, std::vector<common::SettingsValue>>& args) const;
438 };
439 
440 extern ArgsManager gArgs;
441 
445 bool HelpRequested(const ArgsManager& args);
446 
449 
456 std::string HelpMessageGroup(const std::string& message);
457 
465 std::string HelpMessageOpt(const std::string& option, const std::string& message);
466 
467 namespace common {
468 #ifdef WIN32
469 class WinCmdLineArgs
470 {
471 public:
472  WinCmdLineArgs();
473  ~WinCmdLineArgs();
474  std::pair<int, char**> get();
475 
476 private:
477  int argc;
478  char** argv;
479  std::vector<std::string> args;
480 };
481 #endif
482 } // namespace common
483 
484 #endif // BITCOIN_COMMON_ARGS_H
bool HelpRequested(const ArgsManager &args)
Definition: args.cpp:659
void SetupHelpOptions(ArgsManager &args)
Add help options to the args manager.
Definition: args.cpp:664
std::string SettingToString(const common::SettingsValue &, const std::string &)
Definition: args.cpp:475
bool SettingToBool(const common::SettingsValue &, bool)
Definition: args.cpp:523
OptionsCategory
Definition: args.h:52
const char *const BITCOIN_SETTINGS_FILENAME
Definition: args.cpp:39
std::optional< common::SettingsValue > InterpretValue(const KeyInfo &key, const std::string *value, unsigned int flags, std::string &error)
Interpret settings value based on registered flags.
Definition: args.cpp:106
bool CheckDataDirOption(const ArgsManager &args)
Definition: args.cpp:710
fs::path AbsPathForConfigVal(const ArgsManager &args, const fs::path &path, bool net_specific=true)
Most paths passed as configuration arguments are treated as relative to the datadir if they are not a...
Definition: config.cpp:211
int64_t SettingToInt(const common::SettingsValue &, int64_t)
Definition: args.cpp:500
ArgsManager gArgs
Definition: args.cpp:41
std::string HelpMessageGroup(const std::string &message)
Format a string to be used as group of options in help messages.
Definition: args.cpp:674
KeyInfo InterpretKey(std::string key)
Parse "name", "section.name", "noname", "section.noname" settings keys.
Definition: args.cpp:78
const char *const BITCOIN_CONF_FILENAME
Definition: args.cpp:38
bool IsSwitchChar(char c)
Definition: args.h:43
std::string HelpMessageOpt(const std::string &option, const std::string &message)
Format a string to be used as option description in help messages.
Definition: args.cpp:678
int flags
Definition: bitcoin-tx.cpp:530
const auto cmd
ArgsManager & args
Definition: bitcoind.cpp:268
ChainType
Definition: chaintype.h:11
std::set< std::string > GetUnsuitableSectionOnlyArgs() const
Log warnings for options in m_section_only_args when they are specified in the default section but no...
Definition: args.cpp:135
std::optional< const Command > GetCommand() const
Get the command and command args (returns std::nullopt if no command provided)
Definition: args.cpp:340
bool IsArgNegated(const std::string &strArg) const
Return true if the argument was originally passed as a negated option, i.e.
Definition: args.cpp:450
std::list< SectionInfo > GetUnrecognizedSections() const
Log warnings for unrecognized section names in the config file.
Definition: args.cpp:155
Flags
Flags controlling how config and command line arguments are validated and interpreted.
Definition: args.h:103
@ NETWORK_ONLY
Definition: args.h:118
@ ALLOW_ANY
disable validation
Definition: args.h:104
@ DISALLOW_NEGATION
disallow -nofoo syntax
Definition: args.h:109
@ DISALLOW_ELISION
disallow -foo syntax that doesn't assign any value
Definition: args.h:110
@ DEBUG_ONLY
Definition: args.h:112
@ COMMAND
Definition: args.h:121
@ SENSITIVE
Definition: args.h:120
common::SettingsValue GetSetting(const std::string &arg) const
Get setting value.
Definition: args.cpp:778
bool ReadSettingsFile(std::vector< std::string > *errors=nullptr)
Read settings file.
Definition: args.cpp:400
ChainType GetChainType() const
Returns the appropriate chain type from the program arguments.
Definition: args.cpp:729
void ForceSetArg(const std::string &strArg, const std::string &strValue)
Definition: args.cpp:544
fs::path m_cached_datadir_path GUARDED_BY(cs_args)
std::string GetChainTypeString() const
Returns the appropriate chain type string from the program arguments.
Definition: args.cpp:736
bool ParseParameters(int argc, const char *const argv[], std::string &error)
Definition: args.cpp:177
std::vector< std::string > GetArgs(const std::string &strArg) const
Return a vector of strings of the given argument.
Definition: args.cpp:360
fs::path GetDataDirNet() const
Get data directory path with appended network identifier.
Definition: args.h:232
std::optional< unsigned int > GetArgFlags(const std::string &name) const
Return Flags for known arg.
Definition: args.cpp:258
void SetConfigFilePath(fs::path)
Definition: args.cpp:722
std::string m_network GUARDED_BY(cs_args)
bool GetSettingsPath(fs::path *filepath=nullptr, bool temp=false, bool backup=false) const
Get settings file path, or return false if read-write settings were disabled with -nosettings.
Definition: args.cpp:374
void LockSettings(Fn &&fn)
Access settings with lock held.
Definition: args.h:404
bool SoftSetArg(const std::string &strArg, const std::string &strValue)
Set an argument if it doesn't already have a value.
Definition: args.cpp:528
void SelectConfigNetwork(const std::string &network)
Select the network in use.
Definition: args.cpp:171
std::string GetHelpMessage() const
Get the help string.
Definition: args.cpp:590
void ClearPathCache()
Clear cached directory paths.
Definition: args.cpp:331
fs::path m_cached_blocks_path GUARDED_BY(cs_args)
bool IsArgSet(const std::string &strArg) const
Return true if the given argument has been manually set.
Definition: args.cpp:369
bool WriteSettingsFile(std::vector< std::string > *errors=nullptr, bool backup=false) const
Write settings file or backup settings file.
Definition: args.cpp:423
std::optional< fs::path > m_config_path GUARDED_BY(cs_args)
void logArgsPrefix(const std::string &prefix, const std::string &section, const std::map< std::string, std::vector< common::SettingsValue >> &args) const
Definition: args.cpp:792
int64_t GetIntArg(const std::string &strArg, int64_t nDefault) const
Return integer argument or default value.
Definition: args.cpp:480
std::map< OptionsCategory, std::map< std::string, Arg > > m_available_args GUARDED_BY(cs_args)
std::vector< std::string > m_command GUARDED_BY(cs_args)
void ClearArgs()
Clear available arguments.
Definition: args.h:360
fs::path GetDataDirBase() const
Get data directory path.
Definition: args.h:225
fs::path GetBlocksDirPath() const
Get blocks directory path.
Definition: args.cpp:280
common::Settings m_settings GUARDED_BY(cs_args)
fs::path GetConfigFilePath() const
Return config file path (read-only)
Definition: args.cpp:716
std::vector< common::SettingsValue > GetSettingsList(const std::string &arg) const
Get list of setting values.
Definition: args.cpp:786
void AddCommand(const std::string &cmd, const std::string &help)
Add subcommand.
Definition: args.cpp:550
std::variant< ChainType, std::string > GetChainArg() const
Return -regtest/-signet/-testnet/-chain= setting as a ChainType enum if a recognized chain type was s...
Definition: args.cpp:743
bool m_accept_any_command GUARDED_BY(cs_args)
Definition: args.h:138
void LogArgs() const
Log the config file options and the command line arguments, useful for troubleshooting.
Definition: args.cpp:809
fs::path GetDataDir(bool net_specific) const
Get data directory path.
Definition: args.cpp:305
RecursiveMutex cs_args
Definition: args.h:132
fs::path m_cached_network_datadir_path GUARDED_BY(cs_args)
common::SettingsValue GetPersistentSetting(const std::string &name) const
Get current setting from config file or read/write settings file, ignoring nonpersistent command line...
Definition: args.cpp:443
bool UseDefaultSection(const std::string &arg) const EXCLUSIVE_LOCKS_REQUIRED(cs_args)
Returns true if settings values from the default section should be used, depending on the current net...
Definition: args.cpp:773
std::string GetArg(const std::string &strArg, const std::string &strDefault) const
Return string argument or default value.
Definition: args.cpp:455
std::set< std::string > m_network_only_args GUARDED_BY(cs_args)
bool ReadConfigStream(std::istream &stream, const std::string &filepath, std::string &error, bool ignore_invalid_keys=false)
Definition: config.cpp:89
bool SoftSetBoolArg(const std::string &strArg, bool fValue)
Set a boolean argument if it doesn't already have a value.
Definition: args.cpp:536
bool ReadConfigFiles(std::string &error, bool ignore_invalid_keys=false)
Definition: config.cpp:118
bool GetBoolArg(const std::string &strArg, bool fDefault) const
Return boolean argument or default value.
Definition: args.cpp:505
void AddHiddenArgs(const std::vector< std::string > &args)
Add many hidden arguments.
Definition: args.cpp:583
void AddArg(const std::string &name, const std::string &help, unsigned int flags, const OptionsCategory &cat)
Add argument.
Definition: args.cpp:562
fs::path GetPathArg(std::string arg, const fs::path &default_value={}) const
Return path argument or default value.
Definition: args.cpp:270
std::list< SectionInfo > m_config_sections GUARDED_BY(cs_args)
Path class wrapper to block calls to the fs::path(std::string) implicit constructor and the fs::path:...
Definition: fs.h:33
bool error(const char *fmt, const Args &... args)
Definition: logging.h:267
Definition: args.cpp:821
CRPCCommand m_command
Definition: interfaces.cpp:514
const char * prefix
Definition: rest.cpp:1005
const char * name
Definition: rest.cpp:49
static RPCHelpMan help()
Definition: server.cpp:143
std::string m_help_param
Definition: args.h:127
unsigned int m_flags
Definition: args.h:129
std::string m_help_text
Definition: args.h:128
std::vector< std::string > args
If command is non-empty: Any args that followed it If command is empty: The unregistered command and ...
Definition: args.h:206
std::string command
The command (if one has been registered with AddCommand), or empty.
Definition: args.h:201
Definition: args.h:70
std::string name
Definition: args.h:71
bool negated
Definition: args.h:73
std::string section
Definition: args.h:72
int m_line
Definition: args.h:84
std::string m_file
Definition: args.h:83
std::string m_name
Definition: args.h:82
Stored settings.
Definition: settings.h:32
#define LOCK(cs)
Definition: sync.h:257
#define EXCLUSIVE_LOCKS_REQUIRED(...)
Definition: threadsafety.h:49