Bitcoin Core 30.99.0
P2P Digital Currency
args.h
Go to the documentation of this file.
1// Copyright (c) 2023-present 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 <cstdint>
15#include <iosfwd>
16#include <list>
17#include <map>
18#include <optional>
19#include <set>
20#include <string>
21#include <variant>
22#include <vector>
23
24class ArgsManager;
25
26extern const char * const BITCOIN_CONF_FILENAME;
27extern const char * const BITCOIN_SETTINGS_FILENAME;
28
29// Return true if -datadir option points to a valid directory or is not specified.
31
41fs::path AbsPathForConfigVal(const ArgsManager& args, const fs::path& path, bool net_specific = true);
42
43inline bool IsSwitchChar(char c)
44{
45#ifdef WIN32
46 return c == '-' || c == '/';
47#else
48 return c == '-';
49#endif
50}
51
52enum class OptionsCategory {
53 OPTIONS,
55 WALLET,
57 ZMQ,
62 RPC,
63 GUI,
67 IPC,
68
69 HIDDEN // Always the last option to avoid printing these in the help
70};
71
72struct KeyInfo {
73 std::string name;
74 std::string section;
75 bool negated{false};
76};
77
78KeyInfo InterpretKey(std::string key);
79
80std::optional<common::SettingsValue> InterpretValue(const KeyInfo& key, const std::string* value,
81 unsigned int flags, std::string& error);
82
84 std::string m_name;
85 std::string m_file;
86 int m_line;
87};
88
89std::string SettingToString(const common::SettingsValue&, const std::string&);
90std::optional<std::string> SettingToString(const common::SettingsValue&);
91
92int64_t SettingToInt(const common::SettingsValue&, int64_t);
93std::optional<int64_t> SettingToInt(const common::SettingsValue&);
94
95bool SettingToBool(const common::SettingsValue&, bool);
96std::optional<bool> SettingToBool(const common::SettingsValue&);
97
99{
100public:
105 enum Flags : uint32_t {
106 ALLOW_ANY = 0x01,
107 // ALLOW_BOOL = 0x02, //!< unimplemented, draft implementation in #16545
108 // ALLOW_INT = 0x04, //!< unimplemented, draft implementation in #16545
109 // ALLOW_STRING = 0x08, //!< unimplemented, draft implementation in #16545
110 // ALLOW_LIST = 0x10, //!< unimplemented, draft implementation in #16545
113
114 DEBUG_ONLY = 0x100,
115 /* Some options would cause cross-contamination if values for
116 * mainnet were used while running on regtest/testnet (or vice-versa).
117 * Setting them as NETWORK_ONLY ensures that sharing a config file
118 * between mainnet and regtest/testnet won't cause problems due to these
119 * parameters by accident. */
121 // This argument's value is sensitive (such as a password).
122 SENSITIVE = 0x400,
123 COMMAND = 0x800,
124 };
125
126protected:
127 struct Arg
128 {
129 std::string m_help_param;
130 std::string m_help_text;
131 unsigned int m_flags;
132 };
133
136 std::vector<std::string> m_command GUARDED_BY(cs_args);
137 std::string m_network GUARDED_BY(cs_args);
138 std::set<std::string> m_network_only_args GUARDED_BY(cs_args);
139 std::map<OptionsCategory, std::map<std::string, Arg>> m_available_args GUARDED_BY(cs_args);
140 std::optional<unsigned int> m_default_flags GUARDED_BY(cs_args){};
141 bool m_accept_any_command GUARDED_BY(cs_args){true};
142 std::list<SectionInfo> m_config_sections GUARDED_BY(cs_args);
143 std::optional<fs::path> m_config_path GUARDED_BY(cs_args);
144 mutable fs::path m_cached_blocks_path GUARDED_BY(cs_args);
145 mutable fs::path m_cached_datadir_path GUARDED_BY(cs_args);
146 mutable fs::path m_cached_network_datadir_path GUARDED_BY(cs_args);
147
148 [[nodiscard]] bool ReadConfigStream(std::istream& stream, const std::string& filepath, std::string& error, bool ignore_invalid_keys = false);
149
155 bool UseDefaultSection(const std::string& arg) const EXCLUSIVE_LOCKS_REQUIRED(cs_args);
156
157 public:
165 common::SettingsValue GetSetting(const std::string& arg) const;
166
170 std::vector<common::SettingsValue> GetSettingsList(const std::string& arg) const;
171
174
178 void SelectConfigNetwork(const std::string& network);
179
180 [[nodiscard]] bool ParseParameters(int argc, const char* const argv[], std::string& error);
181
185 fs::path GetConfigFilePath() const;
186 void SetConfigFilePath(fs::path);
187 [[nodiscard]] bool ReadConfigFiles(std::string& error, bool ignore_invalid_keys = false);
188
195 std::set<std::string> GetUnsuitableSectionOnlyArgs() const;
196
200 std::list<SectionInfo> GetUnrecognizedSections() const;
201
202 struct Command {
204 std::string command;
209 std::vector<std::string> args;
210 };
214 std::optional<const Command> GetCommand() const;
215
221 fs::path GetBlocksDirPath() const;
222
228 fs::path GetDataDirBase() const { return GetDataDir(false); }
229
235 fs::path GetDataDirNet() const { return GetDataDir(true); }
236
240 void ClearPathCache();
241
248 std::vector<std::string> GetArgs(const std::string& strArg) const;
249
256 bool IsArgSet(const std::string& strArg) const;
257
265 bool IsArgNegated(const std::string& strArg) const;
266
274 std::string GetArg(const std::string& strArg, const std::string& strDefault) const;
275 std::optional<std::string> GetArg(const std::string& strArg) const;
276
287 fs::path GetPathArg(std::string arg, const fs::path& default_value = {}) const;
288
296 int64_t GetIntArg(const std::string& strArg, int64_t nDefault) const;
297 std::optional<int64_t> GetIntArg(const std::string& strArg) const;
298
306 bool GetBoolArg(const std::string& strArg, bool fDefault) const;
307 std::optional<bool> GetBoolArg(const std::string& strArg) const;
308
316 bool SoftSetArg(const std::string& strArg, const std::string& strValue);
317
325 bool SoftSetBoolArg(const std::string& strArg, bool fValue);
326
327 // Forces an arg setting. Called by SoftSetArg() if the arg hasn't already
328 // been set. Also called directly in testing.
329 void ForceSetArg(const std::string& strArg, const std::string& strValue);
330
336 ChainType GetChainType() const;
337
343 std::string GetChainTypeString() const;
344
348 void AddArg(const std::string& name, const std::string& help, unsigned int flags, const OptionsCategory& cat);
349
353 void AddCommand(const std::string& cmd, const std::string& help);
354
358 void AddHiddenArgs(const std::vector<std::string>& args);
359
363 void ClearArgs();
364
370 void CheckMultipleCLIArgs() const;
371
375 std::string GetHelpMessage() const;
376
381 std::optional<unsigned int> GetArgFlags(const std::string& name) const;
382
386 void SetDefaultFlags(std::optional<unsigned int>);
387
392 bool GetSettingsPath(fs::path* filepath = nullptr, bool temp = false, bool backup = false) const;
393
397 bool ReadSettingsFile(std::vector<std::string>* errors = nullptr);
398
403 bool WriteSettingsFile(std::vector<std::string>* errors = nullptr, bool backup = false) const;
404
409 common::SettingsValue GetPersistentSetting(const std::string& name) const;
410
414 template <typename Fn>
415 void LockSettings(Fn&& fn)
416 {
417 LOCK(cs_args);
418 fn(m_settings);
419 }
420
425 void LogArgs() const;
426
427private:
434 fs::path GetDataDir(bool net_specific) const;
435
442 std::variant<ChainType, std::string> GetChainArg() const;
443
444 // Helper function for LogArgs().
445 void logArgsPrefix(
446 const std::string& prefix,
447 const std::string& section,
448 const std::map<std::string, std::vector<common::SettingsValue>>& args) const;
449};
450
451extern ArgsManager gArgs;
452
456bool HelpRequested(const ArgsManager& args);
457
460
461extern const std::vector<std::string> TEST_OPTIONS_DOC;
462
464bool HasTestOption(const ArgsManager& args, const std::string& test_option);
465
472std::string HelpMessageGroup(const std::string& message);
473
481std::string HelpMessageOpt(const std::string& option, const std::string& message);
482
483namespace common {
484#ifdef WIN32
485class WinCmdLineArgs
486{
487public:
488 WinCmdLineArgs();
489 ~WinCmdLineArgs();
490 std::pair<int, char**> get();
491
492private:
493 int argc;
494 char** argv;
495 std::vector<std::string> args;
496};
497#endif
498} // namespace common
499
500#endif // BITCOIN_COMMON_ARGS_H
const std::vector< std::string > TEST_OPTIONS_DOC
Definition: args.cpp:724
bool HelpRequested(const ArgsManager &args)
Definition: args.cpp:698
void SetupHelpOptions(ArgsManager &args)
Add help options to the args manager.
Definition: args.cpp:703
std::string SettingToString(const common::SettingsValue &, const std::string &)
Definition: args.cpp:483
bool SettingToBool(const common::SettingsValue &, bool)
Definition: args.cpp:531
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:107
OptionsCategory
Definition: args.h:52
const char *const BITCOIN_SETTINGS_FILENAME
Definition: args.cpp:40
bool CheckDataDirOption(const ArgsManager &args)
Definition: args.cpp:770
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:226
int64_t SettingToInt(const common::SettingsValue &, int64_t)
Definition: args.cpp:508
ArgsManager gArgs
Definition: args.cpp:42
bool HasTestOption(const ArgsManager &args, const std::string &test_option)
Checks if a particular test option is present in -test command-line arg options.
Definition: args.cpp:730
std::string HelpMessageGroup(const std::string &message)
Format a string to be used as group of options in help messages.
Definition: args.cpp:713
KeyInfo InterpretKey(std::string key)
Parse "name", "section.name", "noname", "section.noname" settings keys.
Definition: args.cpp:79
const char *const BITCOIN_CONF_FILENAME
Definition: args.cpp:39
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:717
int flags
Definition: bitcoin-tx.cpp:529
const auto cmd
ArgsManager & args
Definition: bitcoind.cpp:282
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:136
std::optional< const Command > GetCommand() const
Get the command and command args (returns std::nullopt if no command provided)
Definition: args.cpp:348
std::optional< unsigned int > m_default_flags GUARDED_BY(cs_args)
Definition: args.h:140
bool IsArgNegated(const std::string &strArg) const
Return true if the argument was originally passed as a negated option, i.e.
Definition: args.cpp:458
void logArgsPrefix(const std::string &prefix, const std::string &section, const std::map< std::string, std::vector< common::SettingsValue > > &args) const
Definition: args.cpp:854
std::map< OptionsCategory, std::map< std::string, Arg > > m_available_args GUARDED_BY(cs_args)
std::list< SectionInfo > GetUnrecognizedSections() const
Log warnings for unrecognized section names in the config file.
Definition: args.cpp:156
Flags
Flags controlling how config and command line arguments are validated and interpreted.
Definition: args.h:105
@ NETWORK_ONLY
Definition: args.h:120
@ ALLOW_ANY
disable validation
Definition: args.h:106
@ DISALLOW_NEGATION
disallow -nofoo syntax
Definition: args.h:111
@ DISALLOW_ELISION
disallow -foo syntax that doesn't assign any value
Definition: args.h:112
@ DEBUG_ONLY
Definition: args.h:114
@ COMMAND
Definition: args.h:123
@ SENSITIVE
Definition: args.h:122
common::SettingsValue GetSetting(const std::string &arg) const
Get setting value.
Definition: args.cpp:840
bool ReadSettingsFile(std::vector< std::string > *errors=nullptr)
Read settings file.
Definition: args.cpp:408
ChainType GetChainType() const
Returns the appropriate chain type from the program arguments.
Definition: args.cpp:789
void ForceSetArg(const std::string &strArg, const std::string &strValue)
Definition: args.cpp:552
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:796
bool ParseParameters(int argc, const char *const argv[], std::string &error)
Definition: args.cpp:179
std::vector< std::string > GetArgs(const std::string &strArg) const
Return a vector of strings of the given argument.
Definition: args.cpp:368
void CheckMultipleCLIArgs() const
Check CLI command args.
Definition: args.cpp:606
void SetDefaultFlags(std::optional< unsigned int >)
Set default flags to return for an unknown arg.
Definition: args.cpp:272
fs::path GetDataDirNet() const
Get data directory path with appended network identifier.
Definition: args.h:235
std::optional< unsigned int > GetArgFlags(const std::string &name) const
Return Flags for known arg.
Definition: args.cpp:260
std::optional< fs::path > m_config_path GUARDED_BY(cs_args)
void SetConfigFilePath(fs::path)
Definition: args.cpp:782
std::list< SectionInfo > m_config_sections GUARDED_BY(cs_args)
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:382
void LockSettings(Fn &&fn)
Access settings with lock held.
Definition: args.h:415
bool SoftSetArg(const std::string &strArg, const std::string &strValue)
Set an argument if it doesn't already have a value.
Definition: args.cpp:536
void SelectConfigNetwork(const std::string &network)
Select the network in use.
Definition: args.cpp:173
std::string GetHelpMessage() const
Get the help string.
Definition: args.cpp:623
void ClearPathCache()
Clear cached directory paths.
Definition: args.cpp:339
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:377
std::set< std::string > m_network_only_args GUARDED_BY(cs_args)
bool WriteSettingsFile(std::vector< std::string > *errors=nullptr, bool backup=false) const
Write settings file or backup settings file.
Definition: args.cpp:431
int64_t GetIntArg(const std::string &strArg, int64_t nDefault) const
Return integer argument or default value.
Definition: args.cpp:488
std::vector< std::string > m_command GUARDED_BY(cs_args)
void ClearArgs()
Clear available arguments.
Definition: args.cpp:598
fs::path GetDataDirBase() const
Get data directory path.
Definition: args.h:228
fs::path GetBlocksDirPath() const
Get blocks directory path.
Definition: args.cpp:288
common::Settings m_settings GUARDED_BY(cs_args)
fs::path GetConfigFilePath() const
Return config file path (read-only)
Definition: args.cpp:776
std::vector< common::SettingsValue > GetSettingsList(const std::string &arg) const
Get list of setting values.
Definition: args.cpp:848
void AddCommand(const std::string &cmd, const std::string &help)
Add subcommand.
Definition: args.cpp:558
std::variant< ChainType, std::string > GetChainArg() const
Return -regtest/-signet/-testnet/-testnet4/-chain= setting as a ChainType enum if a recognized chain ...
Definition: args.cpp:803
bool m_accept_any_command GUARDED_BY(cs_args)
Definition: args.h:141
void LogArgs() const
Log the config file options and the command line arguments, useful for troubleshooting.
Definition: args.cpp:871
fs::path GetDataDir(bool net_specific) const
Get data directory path.
Definition: args.cpp:313
RecursiveMutex cs_args
Definition: args.h:134
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:451
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:835
std::string GetArg(const std::string &strArg, const std::string &strDefault) const
Return string argument or default value.
Definition: args.cpp:463
bool ReadConfigStream(std::istream &stream, const std::string &filepath, std::string &error, bool ignore_invalid_keys=false)
Definition: config.cpp:93
bool SoftSetBoolArg(const std::string &strArg, bool fValue)
Set a boolean argument if it doesn't already have a value.
Definition: args.cpp:544
bool ReadConfigFiles(std::string &error, bool ignore_invalid_keys=false)
Definition: config.cpp:122
bool GetBoolArg(const std::string &strArg, bool fDefault) const
Return boolean argument or default value.
Definition: args.cpp:513
void AddHiddenArgs(const std::vector< std::string > &args)
Add many hidden arguments.
Definition: args.cpp:591
void AddArg(const std::string &name, const std::string &help, unsigned int flags, const OptionsCategory &cat)
Add argument.
Definition: args.cpp:570
fs::path GetPathArg(std::string arg, const fs::path &default_value={}) const
Return path argument or default value.
Definition: args.cpp:278
Definition: args.cpp:883
CRPCCommand m_command
Definition: interfaces.cpp:538
const char * prefix
Definition: rest.cpp:1117
const char * name
Definition: rest.cpp:50
static RPCHelpMan help()
Definition: server.cpp:118
std::string m_help_param
Definition: args.h:129
unsigned int m_flags
Definition: args.h:131
std::string m_help_text
Definition: args.h:130
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:209
std::string command
The command (if one has been registered with AddCommand), or empty.
Definition: args.h:204
Definition: args.h:72
std::string name
Definition: args.h:73
bool negated
Definition: args.h:75
std::string section
Definition: args.h:74
int m_line
Definition: args.h:86
std::string m_file
Definition: args.h:85
std::string m_name
Definition: args.h:84
Stored settings.
Definition: settings.h:32
#define LOCK(cs)
Definition: sync.h:259
#define EXCLUSIVE_LOCKS_REQUIRED(...)
Definition: threadsafety.h:51