doc/internal/man3/OPTIONS.pod

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