| 1 |
/* SPDX-License-Identifier: LGPL-2.1-or-later */ |
| 2 |
#pragma once |
| 3 |
|
| 4 |
#include "shared-forward.h" |
| 5 |
|
| 6 |
/* Option namespace/group explanation: |
| 7 |
* the list of options is split into namespaces, and a namespace is split into groups. |
| 8 |
* By default, options defined in a single program are all placed in a single (unnamed) namespace |
| 9 |
* and in a single (unnamed) group. OPTION_NAMESPACE() marks the beginning of a named namespace. |
| 10 |
* OPTION_GROUP() marks the beginning of a named group. |
| 11 |
* |
| 12 |
* Note: if multiple namespaces are used, they should all be named, i.e. each separate parse_argv |
| 13 |
* instance should have OPTION_NAMESPACE first, and then its set of OPTION()s. (This is because |
| 14 |
* clang reorders OPTIONs coming from different functions. So an unnamed group could end up being |
| 15 |
* merged with one of the earlier groups. It seems that reordering within a single function does |
| 16 |
* not happen.) |
| 17 |
* |
| 18 |
* When groups are used, the first group may be named (with OPTION_GROUP appearing before any |
| 19 |
* options), or it may be unnamed. Both variants should work fine. |
| 20 |
*/ |
| 21 |
|
| 22 |
typedef enum OptionFlags { |
| 23 |
OPTION_OPTIONAL_ARG = 1U << 0, /* Same as optional_argument in getopt */ |
| 24 |
OPTION_POSITIONAL_ENTRY = 1U << 1, /* The "option" to handle positional arguments */ |
| 25 |
OPTION_STOPS_PARSING = 1U << 2, /* This option acts like "--" */ |
| 26 |
OPTION_NAMESPACE_MARKER = 1U << 3, /* Fake option entry to separate namespaces */ |
| 27 |
OPTION_GROUP_MARKER = 1U << 4, /* Fake option entry to separate groups */ |
| 28 |
OPTION_HELP_ENTRY = 1U << 5, /* Fake option entry to insert an additional help line */ |
| 29 |
OPTION_HELP_ENTRY_VERBATIM = 1U << 6, /* Same, but use the long_code in the first column as written */ |
| 30 |
} OptionFlags; |
| 31 |
|
| 32 |
/* Note: the alignment attribute must match the one applied to each variable via _alignptr_ in |
| 33 |
* _OPTION() below. Otherwise the struct's sizeof and the actual stride between consecutive entries |
| 34 |
* placed in the SYSTEMD_OPTIONS section would not match on architectures where the natural |
| 35 |
* alignment of the struct is smaller than sizeof(void*) (e.g. m68k). That would cause the |
| 36 |
* pointer-arithmetic-based iteration over the section to read from padding bytes. */ |
| 37 |
typedef struct _alignptr_ Option { |
| 38 |
int id; |
| 39 |
OptionFlags flags; |
| 40 |
char short_code; |
| 41 |
const char *long_code; |
| 42 |
const char *metavar; |
| 43 |
uintptr_t data; |
| 44 |
const char *help; |
| 45 |
} Option; |
| 46 |
assert_cc(sizeof(Option) % sizeof(void*) == 0); |
| 47 |
|
| 48 |
#define _OPTION(counter, fl, sc, lc, mv, d, h) \ |
| 49 |
_section_("SYSTEMD_OPTIONS") \ |
| 50 |
_alignptr_ \ |
| 51 |
_used_ \ |
| 52 |
_retain_ \ |
| 53 |
_no_reorder_ \ |
| 54 |
_variable_no_sanitize_address_ \ |
| 55 |
static const Option CONCATENATE(option, counter) = { \ |
| 56 |
.id = 0x100 + counter, \ |
| 57 |
.flags = fl, \ |
| 58 |
.short_code = sc, \ |
| 59 |
.long_code = lc, \ |
| 60 |
.metavar = mv, \ |
| 61 |
.data = d, \ |
| 62 |
.help = h, \ |
| 63 |
}; \ |
| 64 |
case (0x100 + counter) |
| 65 |
|
| 66 |
/* Magic entry in the table (which will not be returned) that designates the start of the namespace <ns>. |
| 67 |
* The define is structured as 'case' so that it can be followed by ':' and indented appropriately. */ |
| 68 |
#define OPTION_NAMESPACE(ns) \ |
| 69 |
_OPTION(__COUNTER__, OPTION_NAMESPACE_MARKER, /* sc= */ 0, /* lc= */ ns, /* mv= */ NULL, /* d= */ 0u, /* h= */ NULL) |
| 70 |
|
| 71 |
/* Magic entry in the table (which will not be returned) that designates the start of the group <gr>. |
| 72 |
* The define is structured as 'case' so that it can be followed by ':' and indented appropriately. */ |
| 73 |
#define OPTION_GROUP(gr) \ |
| 74 |
_OPTION(__COUNTER__, OPTION_GROUP_MARKER, /* sc= */ 0, /* lc= */ gr, /* mv= */ NULL, /* d= */ 0u, /* h= */ NULL) |
| 75 |
|
| 76 |
#define OPTION_FULL_DATA(fl, sc, lc, mv, d, h) _OPTION(__COUNTER__, fl, sc, lc, mv, d, h) |
| 77 |
#define OPTION_FULL(fl, sc, lc, mv, h) OPTION_FULL_DATA(fl, sc, lc, mv, /* d= */ 0u, h) |
| 78 |
#define OPTION(sc, lc, mv, h) OPTION_FULL(/* fl= */ 0, sc, lc, mv, h) |
| 79 |
#define OPTION_LONG(lc, mv, h) OPTION(/* sc= */ 0, lc, mv, h) |
| 80 |
#define OPTION_LONG_FLAGS(fl, lc, mv, h) OPTION_FULL(fl, /* sc= */ 0, lc, mv, h) |
| 81 |
#define OPTION_LONG_DATA(lc, mv, d, h) OPTION_FULL_DATA(/* fl= */ 0, /* sc= */ 0, lc, mv, d, h) |
| 82 |
#define OPTION_SHORT(sc, mv, h) OPTION(sc, /* lc= */ NULL, mv, h) |
| 83 |
#define OPTION_SHORT_FLAGS(fl, sc, mv, h) OPTION_FULL(fl, sc, /* lc= */ NULL, mv, h) |
| 84 |
#define OPTION_SHORT_DATA(sc, mv, d, h) OPTION_FULL_DATA(/* fl= */ 0, sc, /* lc= */ NULL, mv, d, h) |
| 85 |
#define OPTION_POSITIONAL OPTION_FULL(OPTION_POSITIONAL_ENTRY, /* sc= */ 0, "(positional)", /* mv= */ NULL, /* h= */ NULL) |
| 86 |
#define OPTION_HELP_VERBATIM(lc, h) OPTION_FULL(OPTION_HELP_ENTRY_VERBATIM, /* sc= */ 0, lc, /* mv= */ NULL, h) |
| 87 |
|
| 88 |
/* This can be used when custom error handling is needed. */ |
| 89 |
#define OPTION_ERROR \ |
| 90 |
case INT_MIN ... -1 |
| 91 |
|
| 92 |
#define OPTION_COMMON_HELP \ |
| 93 |
OPTION('h', "help", NULL, "Show this help") |
| 94 |
|
| 95 |
#define OPTION_COMMON_VERSION \ |
| 96 |
OPTION_LONG("version", NULL, "Show package version") |
| 97 |
|
| 98 |
#define OPTION_COMMON_NO_PAGER \ |
| 99 |
OPTION_LONG("no-pager", NULL, "Do not start a pager") |
| 100 |
|
| 101 |
#define OPTION_COMMON_NO_LEGEND \ |
| 102 |
OPTION_LONG("no-legend", NULL, "Do not show headers and footers") |
| 103 |
|
| 104 |
#define OPTION_COMMON_LOG_LEVEL \ |
| 105 |
OPTION_LONG("log-level", "LEVEL", \ |
| 106 |
"Set log level (debug, info, notice, warning, err, crit, alert, emerg)") |
| 107 |
|
| 108 |
#define OPTION_COMMON_LOG_TARGET \ |
| 109 |
OPTION_LONG("log-target", "TARGET", \ |
| 110 |
"Set log target (console, journal, journal-or-kmsg, kmsg, null)") |
| 111 |
|
| 112 |
#define OPTION_COMMON_LOG_COLOR \ |
| 113 |
OPTION_LONG("log-color", "BOOL", "Highlight important messages") |
| 114 |
|
| 115 |
#define OPTION_COMMON_LOG_LOCATION \ |
| 116 |
OPTION_LONG("log-location", "BOOL", "Include code location in messages") |
| 117 |
|
| 118 |
#define OPTION_COMMON_LOG_TIME \ |
| 119 |
OPTION_LONG("log-time", "BOOL", "Prefix messages with current time") |
| 120 |
|
| 121 |
#define OPTION_COMMON_CAT_CONFIG \ |
| 122 |
OPTION_LONG("cat-config", NULL, "Show configuration files") |
| 123 |
|
| 124 |
#define OPTION_COMMON_TLDR \ |
| 125 |
OPTION_LONG("tldr", NULL, "Show non-comment parts of configuration") |
| 126 |
|
| 127 |
#define OPTION_COMMON_NO_ASK_PASSWORD \ |
| 128 |
OPTION_LONG("no-ask-password", NULL, "Do not prompt for password") |
| 129 |
|
| 130 |
#define OPTION_COMMON_HOST \ |
| 131 |
OPTION('H', "host", "[USER@]HOST", "Operate on remote host") |
| 132 |
|
| 133 |
#define OPTION_COMMON_MACHINE \ |
| 134 |
OPTION('M', "machine", "CONTAINER", "Operate on local container") |
| 135 |
|
| 136 |
#define OPTION_COMMON_SYSTEM \ |
| 137 |
OPTION_LONG("system", NULL, "Operate in system mode") |
| 138 |
|
| 139 |
#define OPTION_COMMON_USER \ |
| 140 |
OPTION_LONG("user", NULL, "Operate in per-user mode") |
| 141 |
|
| 142 |
#define OPTION_COMMON_JSON \ |
| 143 |
OPTION_LONG("json", "FORMAT", "Generate JSON output (pretty, short, or off)") |
| 144 |
|
| 145 |
#define OPTION_COMMON_LOWERCASE_J \ |
| 146 |
OPTION_SHORT('j', NULL, \ |
| 147 |
"Equivalent to --json=pretty (on TTY) or --json=short (otherwise)") |
| 148 |
|
| 149 |
#define OPTION_COMMON_ENTRY_TOKEN \ |
| 150 |
OPTION_LONG("entry-token", "TOKEN", \ |
| 151 |
"Entry token to use for this installation " \ |
| 152 |
"(machine-id, os-id, os-image-id, auto, literal:…)") |
| 153 |
|
| 154 |
#define OPTION_COMMON_MAKE_ENTRY_DIRECTORY \ |
| 155 |
OPTION_LONG("make-entry-directory", \ |
| 156 |
"BOOL|auto", "Create $BOOT/ENTRY-TOKEN/ directory") |
| 157 |
|
| 158 |
#define OPTION_COMMON_PRIVATE_KEY(purpose) \ |
| 159 |
OPTION_LONG("private-key", "PATH|URI", purpose) |
| 160 |
|
| 161 |
#define OPTION_COMMON_PRIVATE_KEY_SOURCE \ |
| 162 |
OPTION_LONG("private-key-source", "SOURCE", \ |
| 163 |
"Specify how to use the private key " \ |
| 164 |
"(file, provider:PROVIDER, engine:ENGINE)") |
| 165 |
|
| 166 |
#define OPTION_COMMON_CERTIFICATE(purpose) \ |
| 167 |
OPTION_LONG("certificate", "PATH|URI", purpose \ |
| 168 |
", or a provider-specific designation if --certificate-source= is used") |
| 169 |
|
| 170 |
#define OPTION_COMMON_CERTIFICATE_SOURCE \ |
| 171 |
OPTION_LONG("certificate-source", "SOURCE", \ |
| 172 |
"Specify how to interpret the certificate from --certificate=. " \ |
| 173 |
"Allows the certificate to be loaded from an OpenSSL provider " \ |
| 174 |
"(file, provider:PROVIDER)") |
| 175 |
|
| 176 |
/* A form used in udev code for compatibility. -V is accepted but not documented. */ |
| 177 |
#define OPTION_COMMON_VERSION_WITH_HIDDEN_V \ |
| 178 |
OPTION_COMMON_VERSION: {} \ |
| 179 |
OPTION_SHORT('V', NULL, /* help= */ NULL) |
| 180 |
|
| 181 |
#define OPTION_COMMON_RESOLVE_NAMES \ |
| 182 |
OPTION('N', "resolve-names", "MODE", \ |
| 183 |
"When to resolve users and groups (early, late, or never)") |
| 184 |
|
| 185 |
/* This is magically mapped to the beginning and end of the section */ |
| 186 |
extern const Option __start_SYSTEMD_OPTIONS[]; |
| 187 |
extern const Option __stop_SYSTEMD_OPTIONS[]; |
| 188 |
|
| 189 |
typedef enum OptionParserMode { |
| 190 |
/* The default mode. This is the implicit default and doesn't have to be specified. */ |
| 191 |
OPTION_PARSER_NORMAL, |
| 192 |
|
| 193 |
/* Same as "+…" for getopt_long — only parse options before the first positional argument. */ |
| 194 |
OPTION_PARSER_STOP_AT_FIRST_NONOPTION, |
| 195 |
|
| 196 |
/* Same as "-…" for getopt_long — return positional arguments as "options" to be handled by the |
| 197 |
* option handler specified with OPTION_POSITIONAL. */ |
| 198 |
OPTION_PARSER_RETURN_POSITIONAL_ARGS, |
| 199 |
|
| 200 |
_OPTION_PARSER_MODE_MAX, |
| 201 |
} OptionParserMode; |
| 202 |
|
| 203 |
typedef enum OptionParserState { |
| 204 |
OPTION_PARSER_INIT, |
| 205 |
OPTION_PARSER_RUNNING, |
| 206 |
OPTION_PARSER_STOPPING, /* We processed an option with OPTION_STOPS_PARSING, and will eat up one |
| 207 |
* more "--", but nothing else. */ |
| 208 |
OPTION_PARSER_DONE, /* Option parsing completed (could be because we reached the end, or because |
| 209 |
* "--" was fully processed, or because we hit a terminating option). */ |
| 210 |
OPTION_PARSER_FAILED, /* We encountered a parse error, and terminated option parsing. */ |
| 211 |
_OPTION_PARSER_MAX, |
| 212 |
} OptionParserState; |
| 213 |
|
| 214 |
typedef struct OptionParser { |
| 215 |
/* Those four should stay first so that it's possible to initialize the struct as { argc, argv } |
| 216 |
* or { argc, argv, mode } or { argc, argv, mode, namespace }. */ |
| 217 |
int argc; /* The original argc. */ |
| 218 |
char **argv; /* The argv array, possibly reordered. */ |
| 219 |
OptionParserMode mode; |
| 220 |
const char *namespace; /* The namespace, may be NULL. */ |
| 221 |
int log_level_shift; /* The log level difference from the default of LOG_ERR. |
| 222 |
* Allowed values are -3..4. |
| 223 |
* Use 4 == LOG_DEBUG - LOG_ERR to log at debug level. */ |
| 224 |
|
| 225 |
const Option *namespace_start, *namespace_end; /* The range of options that are part of our namespace. */ |
| 226 |
|
| 227 |
OptionParserState state; |
| 228 |
int optind; /* Position of the parameter being handled. |
| 229 |
* 0 → option parsing hasn't been started yet. */ |
| 230 |
int short_option_offset; /* Set when we're parsing an argument with one or more short options. |
| 231 |
* 0 → we're not parsing short options. */ |
| 232 |
int positional_offset; /* Offset to where positional parameters are. After processing has been |
| 233 |
* finished, all options and their args are to the left of this offset. */ |
| 234 |
|
| 235 |
/* The two variables below encompass the state of the last option_parse() call. |
| 236 |
* Before parsing has commenced, and after it has finished, they will be NULL. */ |
| 237 |
const Option *opt; /* … the matched option or NULL */ |
| 238 |
const char *arg; /* … the argument or NULL */ |
| 239 |
} OptionParser; |
| 240 |
|
| 241 |
int option_parse( |
| 242 |
const Option options[], |
| 243 |
const Option options_end[], |
| 244 |
OptionParser *state); |
| 245 |
|
| 246 |
/* Iterate over options. Don't forget to handle errors (negative c)! */ |
| 247 |
#define FOREACH_OPTION(c, state) \ |
| 248 |
for (int c; (c = option_parse(__start_SYSTEMD_OPTIONS, __stop_SYSTEMD_OPTIONS, state)) != 0; ) |
| 249 |
|
| 250 |
#define FOREACH_OPTION_OR_RETURN(c, state) \ |
| 251 |
for (int c; (c = option_parse(__start_SYSTEMD_OPTIONS, __stop_SYSTEMD_OPTIONS, state)) != 0; ) \ |
| 252 |
if (c < 0) \ |
| 253 |
return c; \ |
| 254 |
else |
| 255 |
|
| 256 |
/* Those helpers are used *during* option parsing and allow looking at or taking the next item in |
| 257 |
* the argv array, either an option or a positional parameter. */ |
| 258 |
char* option_parser_peek_next_arg(const OptionParser *state); |
| 259 |
char* option_parser_consume_next_arg(OptionParser *state); |
| 260 |
|
| 261 |
/* Those helpers are used *after* option parsing and return the positional arguments (and unparsed |
| 262 |
* options in case option parsing was stopped early, e.g. via "--"). */ |
| 263 |
char** option_parser_get_args(const OptionParser *state); |
| 264 |
size_t option_parser_get_n_args(const OptionParser *state); |
| 265 |
char* option_parser_get_arg(const OptionParser *state, size_t i); |
| 266 |
|
| 267 |
char* option_get_synopsis(const Option *opt, const char *joiner, bool show_metavar); |
| 268 |
|
| 269 |
int _option_parser_get_help_table_full( |
| 270 |
const Option options[], |
| 271 |
const Option options_end[], |
| 272 |
const char *namespace, |
| 273 |
const char *group, |
| 274 |
Table **ret); |
| 275 |
#define option_parser_get_help_table_full(namespace, group, ret) \ |
| 276 |
_option_parser_get_help_table_full(__start_SYSTEMD_OPTIONS, __stop_SYSTEMD_OPTIONS, namespace, group, ret) |
| 277 |
#define option_parser_get_help_table_ns(ns, ret) \ |
| 278 |
option_parser_get_help_table_full(ns, /* group= */ NULL, ret) |
| 279 |
#define option_parser_get_help_table_group(group, ret) \ |
| 280 |
option_parser_get_help_table_full(/* namespace= */ NULL, group, ret) |
| 281 |
#define option_parser_get_help_table(ret) \ |
| 282 |
option_parser_get_help_table_group(/* group= */ NULL, ret) |