Unix/Linux Go Back    


BSD 2.11 - man page for options (bsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PARSEOPTIONS(3) 								  PARSEOPTIONS(3)

NAME
       ParseOptions, UsageOptions, HelpOptions, Num_Opts - Parse command line options

SYNOPSIS
       #include "/usr/local/include/options.h"

       int ParseOptions(options, num_options, argc, argv)
       OptionDescRec *options;
       int num_options;
       int argc;
       char **argv;

       void UsageOptions(options, num_options, badoption)
       OptionDescRec *options;
       int num_options;
       char *badoption;

       void HelpOptions(options, num_options, message)
       OptionDescRec *options;
       int num_options;
       char **message;

       int Num_Opts(options)
       OptionDescRec *options;

       extern char *OptionChars;
       extern char *ProgramName;

DESCRIPTION
       ParseOptions()  parses  a  given  set of options found in argv.	The argc parameter is the
       count of the number of string pointers in argv.	Both argc and argv are	typically  passed
       directly  from  a  main() function.  The argv parameter should contain an array of strings
       that need to be parsed.	ParseOptions() returns the number of entries in  argv  that  were
       successfully parsed or -1 upon error.

       The  options  structure	should	contain  a  valid  description list of options.  The type
       OptionDescRec is defined as the following in the options.h header file:

	      typedef struct {
		  char	    *option;	 /* Option string in argv */
		  int	    flags;	 /* Flag bits */
		  int	    (*cvtarg)(); /* Function to convert argument */
		  caddr_t   valp;	 /* Variable to set */
		  caddr_t   value;	 /* Default value to provide */
		  char	    *usage;	 /* Usage message */
		  char	    *desc;	 /* Description message */
	      } OptionDescRec, *OptionDescList;

       The order of options is important because the first partial  match  found  in  options  is
       used.   This  allows  abbreviations (except if the option is a StickArg [see below]).  For
       instance, a user may specify only "-n" for "-number"  provided  that  "-n"  is  unique  to
       options or that "-number" is placed before any other "-n*" options in options.

       The  option  member  of OptionDescRec is the string name of the option.	This is typically
       something like

	      "-c"
	      "+c"
	      "-file"

       The first character of option is special.  It must be one of the characters know to be the
       start  of  an option.  The default list of starting option characters is "-+".  This indi-
       cates that an option can start with either a "-" or a "+".  This list of characters may be
       changed by setting the variable OptionChars to point to a string of custom starting option
       characters.

       The flags member is used to set bits to describe how  an  option  is  to  be  interpreted.
       Valid flags are defined in the options.h header file:

	      NoArg  No  argument  for	this option.  Use the value in OptionDescRec.value to set
		     the value in the valp member of OptionDescRec.

	      IsArg  Value is the option string itself.

	      SepArg Value is in next argument in argv.

	      StickyArg
		     Value is the characters immediately following the option.

	      SkipArg
		     Ignore this option and the next argument in argv.

	      SkipLine
		     Ignore this option and the rest of argv.

	      SkipNArgs
		     Ignore this option and the next OptionDescRes.value arguments in argv.

	      ArgHidden
		     Don't show this option in usage or help messages.

       The next member of OptionDescRec is cvtarg.  This should be a pointer to a  function  that
       knows  how  to convert the given argument into the correct type.  The predefined functions
       are as follows:

	      OptBool
		     Converts a boolean.

	      OptInt Converts an integer.

	      OptShort
		     Converts a short.

	      OptLong
		     Converts a long.

	      OptStr Converts a string.

       The valp member should be a pointer to the variable that needs to  be  set.   valp  should
       accept whatever type cvtarg is expected to return.

       The  value  member  should  contain a default value to be used if no value is given for an
       option or this type of option does not require an argument (according to the flags  bits).
       If value is NULL then an argument for this option is optional.

       usage  is  used	to  build  usage  and  help messages.  It should be a string containing a
       description of any arguments that may be used for this option.  The option  string  itself
       should not be a part of usage.  The UsageOptions() and HelpOptions() functions combine the
       option field with usage and interpret the flags bits to build a	usage  string.	 If  this
       field is NULL, then just the option field itself is used for usage and help messages.

       The  desc member is used to build a help message for this option.  This should be a string
       containing a brief description on what this option does.

       The num_options parameter should be the number of OptionDescRec's found in  options.   The
       function Num_Opts() will return the number of OptionDescRec's.

       The  UsageOptions()  function  prints  a usage message.	If badoption is not NULL, then an
       initial message is displayed indicating that badoption is not a valid option.

       The HelpOptions() function prints a nicely formatted message describing all  options.   If
       message	is  not  NULL  it  is  taken to be a message that is displayed in the output of a
       "-help" option.

EXAMPLE
       Here is an example program:

       #include "options.h"

       char *filename = NULL;
       int number = -1;
       int foo = -1;
       int I = -1;
       long L = -1;
       short S = -1;

       OptionDescRec opts[] = {
	   {"-foo",   NoArg,	     OptBool, (caddr_t) &foo, "0",
	    (char *)NULL,  "Disable foo bar"},
	   {"+foo",   NoArg,	     OptBool, (caddr_t) &foo,		"1",
	    (char *)NULL,  "Enable foo bar"},
	   {"-I",     StickyArg,     OptInt, (caddr_t) &I,	   (caddr_t) NULL,
	    (char *)NULL,  "Set value of I"},
	   {"-L",     StickyArg,     OptLong, (caddr_t) &L,	   (caddr_t) NULL,
	    (char *)NULL,  "Set value of L"},
	   {"-S",     SepArg,	     OptShort, (caddr_t) &S,	   (caddr_t) NULL,
	    (char *)NULL,  "Set value of S"},
	   {"-C",     StickyArg,     OptStr, (caddr_t) &filename,  (caddr_t) NULL,
	    (char *)NULL,  "Alternate file to use"},
	   {"-number",	   SepArg,   OptInt, (caddr_t) &number,    "66",
	    "interval",    NULL},
	   {"-file",  SepArg,	OptStr, (caddr_t) &filename,  (caddr_t) NULL,
	    "filename",    "Specify alternate file to use"},
       };

       main(argc, argv)
	    int argc;
	    char **argv;
       {
	   int c;

	   c = ParseOptions(opts, Num_Opts(opts), argc, argv);
	   printf("Count = %d of %d0, c, argc);
       }

RETURN VALUES
       ParseOptions() returns the number of arguments parsed or -1 upon error.

NOTES
       The -help option is automatically built into ParseOptions().

       All error messages are sent to stderr.

       An option may be both StickyArg and SepArg.  If both are set for one option, preference is
       given to SepArg parsing.  Also, no appreviations are allowed.

AUTHOR
       Michael A. Cooper,
       University Computing Services,
       University of Southern California.

					 30 October 1990			  PARSEOPTIONS(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 03:52 AM.