123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328 |
- =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_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
- - 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_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);
- =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 ths 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_cipher() takes the specified I<name> and fills in
- the cipher into I<cipherp>. The function opt_md() does the same
- thing for message digest.
- 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.
- =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
|