]>
Commit | Line | Data |
---|---|---|
f4407385 RS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
b0f96018 | 5 | OPTIONS, OPT_PAIR, OPT_COMMON, OPT_ERR, OPT_EOF, OPT_HELP, |
28407698 | 6 | opt_init, opt_progname, opt_appname, opt_getprog, opt_help, |
6920055e P |
7 | opt_begin, opt_next, opt_flag, opt_arg, opt_unknown, opt_cipher, |
8 | opt_cipher_any, opt_cipher_silent, opt_md, | |
28407698 DDO |
9 | opt_int, opt_int_arg, opt_long, opt_ulong, opt_intmax, opt_uintmax, |
10 | opt_format, opt_isdir, opt_string, opt_pair, | |
d19dacd5 | 11 | opt_num_rest, opt_rest, opt_legacy_okay |
f4407385 RS |
12 | - Option parsing for commands and tests |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include "opt.h" | |
17 | ||
18 | typedef struct { ... } OPTIONS; | |
19 | typedef struct { ... } OPT_PAIR; | |
b0f96018 DDO |
20 | #define OPT_COMMON |
21 | #define OPT_ERR | |
22 | #define OPT_EOF | |
23 | #define OPT_HELP | |
f4407385 | 24 | |
28407698 | 25 | char *opt_init(int argc, char **argv, const OPTIONS *o); |
f4407385 | 26 | char *opt_progname(const char *argv0); |
28407698 | 27 | char *opt_appname(const char *argv0); |
f4407385 | 28 | char *opt_getprog(void); |
28407698 | 29 | void opt_help(const OPTIONS *list); |
f4407385 | 30 | |
28407698 | 31 | void opt_begin(void); |
f4407385 | 32 | int opt_next(void); |
f4407385 | 33 | char *opt_flag(void); |
28407698 | 34 | char *opt_arg(void); |
f4407385 RS |
35 | char *opt_unknown(void); |
36 | int opt_cipher(const char *name, EVP_CIPHER **cipherp); | |
6920055e P |
37 | int opt_cipher_any(const char *name, EVP_CIPHER **cipherp); |
38 | int opt_cipher_silent(const char *name, EVP_CIPHER **cipherp); | |
f4407385 RS |
39 | int opt_md(const char *name, EVP_MD **mdp); |
40 | ||
41 | int opt_int(const char *value, int *result); | |
28407698 | 42 | int opt_int_arg(void); |
f4407385 | 43 | int opt_long(const char *value, long *result); |
f4407385 | 44 | int opt_ulong(const char *value, unsigned long *result); |
28407698 DDO |
45 | int opt_intmax(const char *value, intmax_t *result); |
46 | int opt_uintmax(const char *value, uintmax_t *result); | |
f4407385 RS |
47 | |
48 | int opt_format(const char *s, unsigned long flags, int *result); | |
28407698 | 49 | int opt_isdir(const char *name); |
f4407385 RS |
50 | int opt_string(const char *name, const char **options); |
51 | int opt_pair(const char *name, const OPT_PAIR* pairs, int *result); | |
52 | ||
53 | int opt_num_rest(void); | |
54 | char **opt_rest(void); | |
55 | ||
d19dacd5 P |
56 | int opt_legacy_okay(void); |
57 | ||
f4407385 RS |
58 | =head1 DESCRIPTION |
59 | ||
60 | The functions on this page provide a common set of option-parsing for | |
61 | the OpenSSL command and the internal test programs. | |
62 | It is intended to be used like the standard getopt(3) routine, except | |
63 | that multi-character flag names are supported, and a variety of parsing | |
64 | and other utility functions are also provided. | |
65 | ||
66 | Programs that use this should make sure to set the appropriate C<-I> | |
67 | flag. | |
68 | ||
69 | These routines expect a global B<BIO> named B<bio_err> to point to | |
70 | the equivalent of B<stderr>. This is already done in the OpenSSL | |
71 | application. | |
72 | ||
73 | =head2 Data Types | |
74 | ||
75 | Each program should define, near the main() routine, an enumeration | |
76 | that is the set of options the program accepts. For example: | |
77 | ||
78 | typedef enum OPTION_choice { | |
b0f96018 | 79 | OPT_COMMON, |
f4407385 RS |
80 | OPT_YES, OPT_NAME, OPT_COUNT, OPT_OFILE, |
81 | ... | |
82 | } OPTION_CHOICE; | |
83 | ||
b0f96018 DDO |
84 | The first two lines must appear exactly as shown. |
85 | OPT_COMMON is a macro that expands to C<OPT_ERR = -1, OPT_EOF = 0, OPT_HELP>. | |
86 | In addition to defining symbolic names for the constants that opt_next() | |
87 | returns, it also helps guarantee that every command has a C<-help> option. | |
f4407385 RS |
88 | The third line is a sample |
89 | set of flags, and the closing C<typedef> name is used for error-checking | |
90 | as discussed below. | |
91 | By declaring the variable as an C<OPTION_CHOICE>, with the right warning | |
92 | flags, the compiler could check that all specified options are handled. | |
93 | ||
94 | The B<OPTIONS> C<typedef> specifies an option: what type of argument | |
95 | it takes (if any), and an optional "help" string. It is a C<struct> | |
96 | containing these fields: | |
97 | ||
98 | const char *name; | |
99 | int retval; | |
100 | int valtype; | |
101 | const char *helpstr; | |
102 | ||
103 | The B<name> is the name of the option that the user would type. Options | |
104 | are words prefaced with a minus sign. If the user uses two minus signs, | |
105 | this is also accepted for compatibility with other GNU software. Some | |
106 | names are special, and are described below. | |
107 | ||
108 | The B<retval> is the value to return if the option is found. It should be | |
109 | one of the choices in the enumeration above. | |
110 | ||
111 | The B<valtype> defines what the option's parameter must be. It should | |
112 | be chosen from the following set: | |
113 | ||
114 | \0 No value | |
115 | '-' No value | |
116 | 's' A text string | |
117 | '/' A directory | |
118 | '<' Name of file to open for input | |
119 | '>' Name of file to open for output | |
120 | 'n' A signed number that fits in the C<int> type | |
121 | 'p' A positive number that fits in the C<int> type | |
122 | 'N' A nonnegative number that fits in the C<int> type | |
123 | 'M' A signed number that fits in the C<intmax_t> type | |
124 | 'U' An unsigned number that fits in the C<uintmax_t> type | |
125 | 'l' A signed number that fits in the C<long> type | |
126 | 'u' An unsigned number that fits in the C<unsigned long> type | |
127 | 'c' File in PEM, DER, or S/MIME format | |
128 | 'F' A file in PEM or DER format | |
129 | 'E' Like 'F' but also allows ENGINE | |
130 | 'f' Any file format | |
131 | ||
132 | The B<helpstr> is what to display when the user uses the help option, | |
133 | which should be C<"help">. | |
134 | ||
135 | A program should declare its options right after the enumeration, | |
136 | and should follow the ordering of the enumeration as this helps | |
137 | readability and maintainability: | |
138 | ||
139 | static OPTIONS my_options[] = { | |
140 | {"help", OPT_HELP, '-', "Display this summary"}, | |
141 | {"yes", OPT_YES, '-', "Print an affirmative reply"}, | |
142 | {"count", OPT_COUNT, 'p', "Repeat count"}, | |
143 | {"output" OPT_OFILE, '>', "Output file; default is stdout"}, | |
144 | {NULL} | |
145 | }; | |
146 | ||
147 | Note that the B<OPT_HELP> option is explicitly listed, and the list ends with | |
148 | an entry of all-null's. The other two special options, B<OPT_ERR> and B<OPT_EOF> | |
149 | should not appear in the array. | |
150 | ||
151 | If the help string is too long to fit into one line, it may be continued | |
152 | on multiple lines; each entry should use B<OPT_MORE_STR>, like this: | |
153 | ||
154 | {"output" OPT_OFILE, '>', "Output file; default is stdout"}, | |
155 | {OPT_MORE_STR, 0, 0, | |
156 | "This flag is not really needed on Unix systems"}, | |
157 | {OPT_MORE_STR, 0, 0, | |
e304aa87 | 158 | "(Unix and descendents for the win!)"} |
f4407385 RS |
159 | |
160 | Each subsequent line will be indented the correct amount. | |
161 | ||
162 | By default, the help display will include a standard prolog: | |
163 | ||
164 | Usage: PROGRAM [options] | |
165 | Valid options are: | |
166 | ...detailed list of options... | |
167 | ||
168 | Sometimes there are parameters that should appear in the synopsis. | |
169 | Use B<OPT_HELP_STR> as the first entry in your array: | |
170 | ||
171 | {OPT_HELP_STR, 1, '-', Usage: %s [options] [text...]\n"} | |
172 | ||
173 | The B<retval> and B<valtype> are ignored, and the B<helpstr> should | |
174 | follow the general construction as shown. The C<%s> will get the program | |
175 | name. | |
176 | ||
177 | If a command has a large set of options, it can be useful to break them | |
178 | into sections. Use the macro B<OPT_SECTION> or B<OPT_SECTION_STR> | |
179 | to indicate this. The two lines below are equivalent: | |
180 | ||
181 | OPT_SECTION("Validation"), | |
182 | {OPT_SECTION_STR, 1, '-', "Validation options:\n"}, | |
183 | ||
184 | In addition to providing help about options, you can provide a description | |
185 | of the parameters a command takes. These should appear at the end of | |
186 | the options and are indicated by using B<OPT_PARAM_STR> or the | |
187 | B<OPT_PARAMETERS> macro: | |
188 | ||
189 | OPT_PARAMETERS() | |
190 | {OPT_PARAM_STR, 1, '-', "Parameters:\n"} | |
191 | ||
57cd10dd | 192 | Every "option" after after this should contain the parameter and |
f4407385 RS |
193 | the help string: |
194 | ||
195 | {"text", 0, 0, "Words to display (optional)"}, | |
196 | ||
197 | =head2 Functions | |
198 | ||
28407698 DDO |
199 | The opt_init() function takes the I<argc> and I<argv> arguments given to main() |
200 | and a pointer I<o> to the list of options. It returns the simple program | |
f4407385 RS |
201 | name, as defined by opt_progname(). |
202 | ||
28407698 DDO |
203 | The opt_progname() function takes the full pathname C<argv[0]> in its I<arg0> |
204 | parameter and returns | |
f4407385 | 205 | the simple short name of the executable, to be used for error messages and |
28407698 DDO |
206 | the like. |
207 | ||
208 | The opt_appname() function takes in its I<argv0> parameter | |
209 | the "application" name (such | |
f4407385 | 210 | as the specific command from L<openssl(1)> and appends it to the program |
28407698 DDO |
211 | name. This function should only be called once. |
212 | ||
213 | The opt_getprog() function returns the value set by opt_appname(). | |
214 | ||
215 | The opt_help() function takes a list of option definitions and prints a | |
216 | nicely-formatted output. | |
217 | ||
218 | The opt_begin() function, which is called automatically by opt_init(), | |
219 | can be used to reset the option parsing loop. | |
f4407385 | 220 | |
28407698 | 221 | The opt_next() function is called, once opt_init() has been called, |
b0f96018 | 222 | in a loop to fetch each option in turn. It returns -1, or B<OPT_EOF> when the |
f4407385 RS |
223 | end of arguments has been reached. This is typically done like this: |
224 | ||
225 | prog = opt_init(argc, argv, my_options); | |
226 | while ((o = opt_next()) != OPT_EOF) { | |
227 | switch (o) { | |
228 | case OPT_EOF: | |
229 | case OPT_ERR: | |
230 | opthelp: | |
231 | fprintf(stderr, "%s: Use -help for summary\n", prog); | |
232 | exit(1); | |
233 | case OPT_HELP: | |
234 | opt_help(my_options); | |
235 | exit(0); | |
236 | ...other options... | |
237 | } | |
238 | } | |
239 | ||
28407698 DDO |
240 | Within the option parsing loop, the following functions may be called. |
241 | ||
242 | The opt_flag() function returns the most recent option name | |
243 | including the preceding C<->. | |
f4407385 | 244 | |
28407698 | 245 | The opt_arg() function returns the option's argument value, if there is one. |
f4407385 | 246 | |
28407698 | 247 | The opt_unknown() function returns the unknown option. |
f4407385 RS |
248 | In an option list, there can be at most one option with the empty string. |
249 | This is a "wildcard" or "unknown" option. For example, it allows an | |
6920055e P |
250 | option to be be taken as digest algorithm, like C<-sha1>. The function |
251 | opt_md() takes the specified I<name> and fills in the digest into I<mdp>. | |
252 | The functions opt_cipher(), opt_cipher_any() and opt_cipher_silent() | |
253 | each takes the specified I<name> and fills in the cipher into I<cipherp>. | |
254 | The function opt_cipher() only accepts ciphers which are not | |
255 | AEAD and are not using XTS mode. The functions opt_cipher_any() and | |
256 | opt_cipher_silent() accept any cipher, the latter not emitting an error | |
257 | if the cipher is not located. | |
f4407385 RS |
258 | |
259 | There are a several useful functions for parsing numbers. These are | |
28407698 | 260 | opt_int(), opt_long(), opt_ulong(), opt_intmax(), and opt_uintmax(). They all |
f4407385 RS |
261 | take C<0x> to mean hexadecimal and C<0> to mean octal, and will do the |
262 | necessary range-checking. They return 1 if successful and fill in the | |
263 | C<result> pointer with the value, or 0 on error. Note that opt_next() | |
264 | will also do range-check on the argument if the appropriate B<valtype> | |
265 | field is specified for the option. This means that error-checking inside | |
266 | the C<switch> C<case> can often be elided. | |
267 | ||
28407698 DDO |
268 | The opt_int_arg() function is a convenience abbreviation to opt_int(). |
269 | It parses and returns an integer, assuming its range has been checked before. | |
270 | ||
271 | The opt_format() function takes a string value, | |
f4407385 RS |
272 | such as used with the B<-informat> or similar option, and fills |
273 | the value from the constants in F<fmt.h> file. | |
274 | ||
28407698 DDO |
275 | The opt_isdir() function returns 1 if the specified I<name> is |
276 | a directory, or 0 if not. | |
277 | ||
f4407385 RS |
278 | The opt_string() function checks that I<name> appears in the |
279 | NULL-terminated array of strings. It returns 1 if found, | |
280 | or prints a diagnostic and returns 0 if not. | |
281 | ||
282 | The opt_pair() function takes a list of I<pairs>, each of which | |
283 | has a text name and an integer. The specified I<name> is | |
284 | found on the list, it puts the index in I<*result>, and returns | |
285 | 1. If not found, it returns 0. | |
286 | ||
28407698 DDO |
287 | The following functions can be used after processing all the options. |
288 | ||
289 | The opt_num_rest() function returns what is left. | |
290 | ||
291 | The opt_rest() function returns a pointer to the first non-option. | |
f4407385 | 292 | If there were no parameters, it will point to the NULL that is |
28407698 | 293 | at the end of the standard I<argv> array. |
f4407385 | 294 | |
d19dacd5 P |
295 | The opt_legacy_okay() function returns true if no options have been |
296 | specified that would preclude using legacy code paths. Currently, | |
297 | the various provider options preclude legacy operation. This means, | |
298 | for example, that specifying both B<-provider> and B<-engine> in the | |
299 | same command line will not work as expected. | |
300 | ||
f4407385 RS |
301 | =head2 Common Options |
302 | ||
303 | There are a few groups of options that are common to many OpenSSL programs. | |
304 | These are handled with sets of macros that define common option names | |
305 | and common code to handle them. The categories are identified by a | |
306 | letter: | |
307 | ||
308 | V Validation | |
309 | X Extended certificate | |
310 | S TLS/SSL | |
311 | R Random state | |
312 | ||
313 | The B<OPT_x_ENUM> macro is used to define the numeration values, where B<x> | |
314 | is one of the letters above. The B<OPT_x_OPTIONS> macro is used to | |
315 | list the set of common options, and the B<OPT_x_CASES> is used in | |
316 | the C<switch> statement. | |
317 | ||
318 | The common options are used throughout the sources for the OpenSSL commands. | |
319 | They are also used with common descriptions when generating the | |
320 | manpages, in the file F<doc/perlvars.pm>, which follow a similar naming | |
321 | convention. | |
322 | ||
323 | =head1 RETURN VALUES | |
324 | ||
325 | Detailed above. | |
326 | ||
327 | =head1 EXAMPLES | |
328 | ||
329 | The best examples can be found in sources for the commands in the F<apps> | |
330 | directory of the source tree. | |
331 | A notable exception is F<apps/cmp.c> which uses this API, but does | |
332 | things very differently. | |
333 | ||
334 | =head1 COPYRIGHT | |
335 | ||
fecb3aae | 336 | Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved. |
f4407385 RS |
337 | |
338 | Licensed under the Apache License 2.0 (the "License"). You may not use this | |
339 | file except in compliance with the License. You can obtain a copy in the file | |
340 | LICENSE in the source distribution or at | |
341 | L<https://www.openssl.org/source/license.html>. | |
342 | ||
343 | =cut |