| =pod |
| |
| =head1 NAME |
| |
| OPTIONS, OPT_PAIR, OPT_COMMON, OPT_ERR, OPT_EOF, OPT_HELP, |
| opt_init, opt_progname, opt_appname, opt_getprog, opt_help, |
| opt_begin, opt_next, opt_flag, opt_arg, opt_unknown, opt_cipher, |
| opt_cipher_any, opt_cipher_silent, opt_md, |
| opt_int, opt_int_arg, opt_long, opt_ulong, opt_intmax, opt_uintmax, |
| opt_format, opt_isdir, opt_string, opt_pair, |
| opt_num_rest, opt_rest, opt_legacy_okay |
| - Option parsing for commands and tests |
| |
| =head1 SYNOPSIS |
| |
| #include "opt.h" |
| |
| typedef struct { ... } OPTIONS; |
| typedef struct { ... } OPT_PAIR; |
| #define OPT_COMMON |
| #define OPT_ERR |
| #define OPT_EOF |
| #define OPT_HELP |
| |
| char *opt_init(int argc, char **argv, const OPTIONS *o); |
| char *opt_progname(const char *argv0); |
| char *opt_appname(const char *argv0); |
| char *opt_getprog(void); |
| void opt_help(const OPTIONS *list); |
| |
| void opt_begin(void); |
| int opt_next(void); |
| char *opt_flag(void); |
| char *opt_arg(void); |
| char *opt_unknown(void); |
| int opt_cipher(const char *name, EVP_CIPHER **cipherp); |
| int opt_cipher_any(const char *name, EVP_CIPHER **cipherp); |
| int opt_cipher_silent(const char *name, EVP_CIPHER **cipherp); |
| int opt_md(const char *name, EVP_MD **mdp); |
| |
| int opt_int(const char *value, int *result); |
| int opt_int_arg(void); |
| int opt_long(const char *value, long *result); |
| int opt_ulong(const char *value, unsigned long *result); |
| int opt_intmax(const char *value, intmax_t *result); |
| int opt_uintmax(const char *value, uintmax_t *result); |
| |
| int opt_format(const char *s, unsigned long flags, int *result); |
| int opt_isdir(const char *name); |
| int opt_string(const char *name, const char **options); |
| int opt_pair(const char *name, const OPT_PAIR* pairs, int *result); |
| |
| int opt_num_rest(void); |
| char **opt_rest(void); |
| |
| int opt_legacy_okay(void); |
| |
| =head1 DESCRIPTION |
| |
| The functions on this page provide a common set of option-parsing for |
| the OpenSSL command and the internal test programs. |
| It is intended to be used like the standard getopt(3) routine, except |
| that multi-character flag names are supported, and a variety of parsing |
| and other utility functions are also provided. |
| |
| Programs that use this should make sure to set the appropriate C<-I> |
| flag. |
| |
| These routines expect a global B<BIO> named B<bio_err> to point to |
| the equivalent of B<stderr>. This is already done in the OpenSSL |
| application. |
| |
| =head2 Data Types |
| |
| Each program should define, near the main() routine, an enumeration |
| that is the set of options the program accepts. For example: |
| |
| typedef enum OPTION_choice { |
| OPT_COMMON, |
| OPT_YES, OPT_NAME, OPT_COUNT, OPT_OFILE, |
| ... |
| } OPTION_CHOICE; |
| |
| The first two lines must appear exactly as shown. |
| OPT_COMMON is a macro that expands to C<OPT_ERR = -1, OPT_EOF = 0, OPT_HELP>. |
| In addition to defining symbolic names for the constants that opt_next() |
| returns, it also helps guarantee that every command has a C<-help> option. |
| The third line is a sample |
| set of flags, and the closing C<typedef> name is used for error-checking |
| as discussed below. |
| By declaring the variable as an C<OPTION_CHOICE>, with the right warning |
| flags, the compiler could check that all specified options are handled. |
| |
| The B<OPTIONS> C<typedef> specifies an option: what type of argument |
| it takes (if any), and an optional "help" string. It is a C<struct> |
| containing these fields: |
| |
| const char *name; |
| int retval; |
| int valtype; |
| const char *helpstr; |
| |
| The B<name> is the name of the option that the user would type. Options |
| are words prefaced with a minus sign. If the user uses two minus signs, |
| this is also accepted for compatibility with other GNU software. Some |
| names are special, and are described below. |
| |
| The B<retval> is the value to return if the option is found. It should be |
| one of the choices in the enumeration above. |
| |
| The B<valtype> defines what the option's parameter must be. It should |
| be chosen from the following set: |
| |
| \0 No value |
| '-' No value |
| 's' A text string |
| '/' A directory |
| '<' Name of file to open for input |
| '>' Name of file to open for output |
| 'n' A signed number that fits in the C<int> type |
| 'p' A positive number that fits in the C<int> type |
| 'N' A nonnegative number that fits in the C<int> type |
| 'M' A signed number that fits in the C<intmax_t> type |
| 'U' An unsigned number that fits in the C<uintmax_t> type |
| 'l' A signed number that fits in the C<long> type |
| 'u' An unsigned number that fits in the C<unsigned long> type |
| 'c' File in PEM, DER, or S/MIME format |
| 'F' A file in PEM or DER format |
| 'E' Like 'F' but also allows ENGINE |
| 'f' Any file format |
| |
| The B<helpstr> is what to display when the user uses the help option, |
| which should be C<"help">. |
| |
| A program should declare its options right after the enumeration, |
| and should follow the ordering of the enumeration as this helps |
| readability and maintainability: |
| |
| static OPTIONS my_options[] = { |
| {"help", OPT_HELP, '-', "Display this summary"}, |
| {"yes", OPT_YES, '-', "Print an affirmative reply"}, |
| {"count", OPT_COUNT, 'p', "Repeat count"}, |
| {"output" OPT_OFILE, '>', "Output file; default is stdout"}, |
| {NULL} |
| }; |
| |
| Note that the B<OPT_HELP> option is explicitly listed, and the list ends with |
| an entry of all-null's. The other two special options, B<OPT_ERR> and B<OPT_EOF> |
| should not appear in the array. |
| |
| If the help string is too long to fit into one line, it may be continued |
| on multiple lines; each entry should use B<OPT_MORE_STR>, like this: |
| |
| {"output" OPT_OFILE, '>', "Output file; default is stdout"}, |
| {OPT_MORE_STR, 0, 0, |
| "This flag is not really needed on Unix systems"}, |
| {OPT_MORE_STR, 0, 0, |
| "(Unix and descendents for the win!)"} |
| |
| Each subsequent line will be indented the correct amount. |
| |
| By default, the help display will include a standard prolog: |
| |
| Usage: PROGRAM [options] |
| Valid options are: |
| ...detailed list of options... |
| |
| Sometimes there are parameters that should appear in the synopsis. |
| Use B<OPT_HELP_STR> as the first entry in your array: |
| |
| {OPT_HELP_STR, 1, '-', Usage: %s [options] [text...]\n"} |
| |
| The B<retval> and B<valtype> are ignored, and the B<helpstr> should |
| follow the general construction as shown. The C<%s> will get the program |
| name. |
| |
| If a command has a large set of options, it can be useful to break them |
| into sections. Use the macro B<OPT_SECTION> or B<OPT_SECTION_STR> |
| to indicate this. The two lines below are equivalent: |
| |
| OPT_SECTION("Validation"), |
| {OPT_SECTION_STR, 1, '-', "Validation options:\n"}, |
| |
| In addition to providing help about options, you can provide a description |
| of the parameters a command takes. These should appear at the end of |
| the options and are indicated by using B<OPT_PARAM_STR> or the |
| B<OPT_PARAMETERS> macro: |
| |
| OPT_PARAMETERS() |
| {OPT_PARAM_STR, 1, '-', "Parameters:\n"} |
| |
| Every "option" after after this should contain the parameter and |
| the help string: |
| |
| {"text", 0, 0, "Words to display (optional)"}, |
| |
| =head2 Functions |
| |
| The opt_init() function takes the I<argc> and I<argv> arguments given to main() |
| and a pointer I<o> to the list of options. It returns the simple program |
| name, as defined by opt_progname(). |
| |
| The opt_progname() function takes the full pathname C<argv[0]> in its I<arg0> |
| parameter and returns |
| the simple short name of the executable, to be used for error messages and |
| the like. |
| |
| The opt_appname() function takes in its I<argv0> parameter |
| the "application" name (such |
| as the specific command from L<openssl(1)> and appends it to the program |
| name. This function should only be called once. |
| |
| The opt_getprog() function returns the value set by opt_appname(). |
| |
| The opt_help() function takes a list of option definitions and prints a |
| nicely-formatted output. |
| |
| The opt_begin() function, which is called automatically by opt_init(), |
| can be used to reset the option parsing loop. |
| |
| The opt_next() function is called, once opt_init() has been called, |
| in a loop to fetch each option in turn. It returns -1, or B<OPT_EOF> when the |
| end of arguments has been reached. This is typically done like this: |
| |
| prog = opt_init(argc, argv, my_options); |
| while ((o = opt_next()) != OPT_EOF) { |
| switch (o) { |
| case OPT_EOF: |
| case OPT_ERR: |
| opthelp: |
| fprintf(stderr, "%s: Use -help for summary\n", prog); |
| exit(1); |
| case OPT_HELP: |
| opt_help(my_options); |
| exit(0); |
| ...other options... |
| } |
| } |
| |
| Within the option parsing loop, the following functions may be called. |
| |
| The opt_flag() function returns the most recent option name |
| including the preceding C<->. |
| |
| The opt_arg() function returns the option's argument value, if there is one. |
| |
| The opt_unknown() function returns the unknown option. |
| In an option list, there can be at most one option with the empty string. |
| This is a "wildcard" or "unknown" option. For example, it allows an |
| option to be be taken as digest algorithm, like C<-sha1>. The function |
| opt_md() takes the specified I<name> and fills in the digest into I<mdp>. |
| The functions opt_cipher(), opt_cipher_any() and opt_cipher_silent() |
| each takes the specified I<name> and fills in the cipher into I<cipherp>. |
| The function opt_cipher() only accepts ciphers which are not |
| AEAD and are not using XTS mode. The functions opt_cipher_any() and |
| opt_cipher_silent() accept any cipher, the latter not emitting an error |
| if the cipher is not located. |
| |
| There are a several useful functions for parsing numbers. These are |
| opt_int(), opt_long(), opt_ulong(), opt_intmax(), and opt_uintmax(). They all |
| take C<0x> to mean hexadecimal and C<0> to mean octal, and will do the |
| necessary range-checking. They return 1 if successful and fill in the |
| C<result> pointer with the value, or 0 on error. Note that opt_next() |
| will also do range-check on the argument if the appropriate B<valtype> |
| field is specified for the option. This means that error-checking inside |
| the C<switch> C<case> can often be elided. |
| |
| The opt_int_arg() function is a convenience abbreviation to opt_int(). |
| It parses and returns an integer, assuming its range has been checked before. |
| |
| The opt_format() function takes a string value, |
| such as used with the B<-informat> or similar option, and fills |
| the value from the constants in F<fmt.h> file. |
| |
| The opt_isdir() function returns 1 if the specified I<name> is |
| a directory, or 0 if not. |
| |
| The opt_string() function checks that I<name> appears in the |
| NULL-terminated array of strings. It returns 1 if found, |
| or prints a diagnostic and returns 0 if not. |
| |
| The opt_pair() function takes a list of I<pairs>, each of which |
| has a text name and an integer. The specified I<name> is |
| found on the list, it puts the index in I<*result>, and returns |
| 1. If not found, it returns 0. |
| |
| The following functions can be used after processing all the options. |
| |
| The opt_num_rest() function returns what is left. |
| |
| The opt_rest() function returns a pointer to the first non-option. |
| If there were no parameters, it will point to the NULL that is |
| at the end of the standard I<argv> array. |
| |
| The opt_legacy_okay() function returns true if no options have been |
| specified that would preclude using legacy code paths. Currently, |
| the various provider options preclude legacy operation. This means, |
| for example, that specifying both B<-provider> and B<-engine> in the |
| same command line will not work as expected. |
| |
| =head2 Common Options |
| |
| There are a few groups of options that are common to many OpenSSL programs. |
| These are handled with sets of macros that define common option names |
| and common code to handle them. The categories are identified by a |
| letter: |
| |
| V Validation |
| X Extended certificate |
| S TLS/SSL |
| R Random state |
| |
| The B<OPT_x_ENUM> macro is used to define the numeration values, where B<x> |
| is one of the letters above. The B<OPT_x_OPTIONS> macro is used to |
| list the set of common options, and the B<OPT_x_CASES> is used in |
| the C<switch> statement. |
| |
| The common options are used throughout the sources for the OpenSSL commands. |
| They are also used with common descriptions when generating the |
| manpages, in the file F<doc/perlvars.pm>, which follow a similar naming |
| convention. |
| |
| =head1 RETURN VALUES |
| |
| Detailed above. |
| |
| =head1 EXAMPLES |
| |
| The best examples can be found in sources for the commands in the F<apps> |
| directory of the source tree. |
| A notable exception is F<apps/cmp.c> which uses this API, but does |
| things very differently. |
| |
| =head1 COPYRIGHT |
| |
| Copyright 2021 The OpenSSL Project Authors. All Rights Reserved. |
| |
| Licensed under the Apache License 2.0 (the "License"). You may not use this |
| file except in compliance with the License. You can obtain a copy in the file |
| LICENSE in the source distribution or at |
| L<https://www.openssl.org/source/license.html>. |
| |
| =cut |