Debian Codegraph @

src/shared/options.h

raw
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)