doc/internal/man3/OPTIONS.pod - third_party/openssl - Git at Google

 =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-2022 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
	=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-2022 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