all_opt man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

ALL_OPT(3)			 LAM INTERNALS			    ALL_OPT(3)

NAME
       all_opt - general purpose command-line options parsing (LAM)

SYNOPSIS
       #include <all_opt.h>

       char *ao_argv0(OPT *aod);
       OPT *ao_init(void);
       char *ao_chosen(OPT *od, const char *opt);
       void ao_free(OPT *od);
       int ao_intparam(OPT *od, const char *opt,
		       int inst, int idx, int *inum);
       int ao_ninsts(OPT *od, const char *opt);
       int ao_nparams(OPT *od, const char *opt, int inst);
       int ao_ntaken(OPT *od);
       char *ao_param(OPT *od, const char *opt, int inst, int idx);
       int ao_parse(OPT *od, int *argc, char **argv);
       int ao_setflags(OPT *aod, int flags);
       int ao_setopt(OPT *od, const char *opt,
		     const char *mutex, int nparams, int flags);
       int ao_setopt1(OPT *od, const char *opt,
		      const char *mutex, int nparams, int flags);
       int ao_tail(OPT *od, int *tailc, char ***tailv);
       int ao_taken(OPT *od, const char *opt);
       int ao_unused(OPT *aod, int *unusedc, char ***unusedv);

DESCRIPTION
       The  all_opt package provides general purpose command-line option pars‐
       ing.  It parses multi-letter option strings  with  varying  numbers  of
       parameters  and	invocations.  Options can be made mandatory as well as
       grouped into mutually exclusive sets.  all_opt can handle multiple com‐
       mand-line parsing invocations by maintaining a separate option descrip‐
       tor for each one.

       An option descriptor is created and initialized by the ao_init()	 func‐
       tion.   It  returns a pointer to a new descriptor, typedef OPT (defined
       in <all_opt.h>).	 This descriptor pointer is used as the first argument
       to all the other functions.  When no longer needed, a descriptor can be
       destroyed by calling ao_free().

       Once a descriptor is created, the user declares each valid command-line
       option  string  by  calling ao_setopt().	 The function's arguments are:
       ad, the option descriptor;  opt,	 the  option  string  being  declared;
       mutex,  an  option  string in the set of mutually exclusive options (or
       NULL if not used); nparams, the number of parameters expected to follow
       this option (or AOVARNUM if variable); and flags, a bit-mapped field of
       flags controlling other characteristics of the option.  The flags value
       is constructed by ORing flags from the following list:

       AOINT	 All arguments following the option are integers.

       AOMUST	 The  option is mandatory and must be taken.  If the option is
		 part of a mutually exclusive set, all options in the set must
		 also have this flag set.

       ao_setopt1() is a convenience function that interprets the opt argument
       as a string of single letter options and	 calls	ao_setopt()  for  each
       letter with the other arguments given.

       The  option string "#" is reserved to represent the special case of the
       "-#" option (i.e. a dash followed by an integer).  The integer  can  be
       either  decimal,	 octal,	 or hexadecimal.  This option implies that the
       AOINT flag is set and that the nparams argument is 1.

       Optional flags may be set on the descriptor with	 ao_setflags().	  Cur‐
       rently, the only flag that is supported is:

       AOPRESERVE_ARGV
		 When this flag is set, the argc and argv that are passed into
		 ao_parse() (see below) are not modified.  Instead, a copy  is
		 made  of  argv	 and  its results are stored internally in the
		 descriptor.  All operations are then performed on that inter‐
		 nal  copy.   Using  this  flag	 also  enables	the use of the
		 ao_unused() function, which will  return  the	unused	tokens
		 after	parsing (i.e., tokens that were not recognized options
		 and were not part of the tail).

       After all valid options are declared, the command  line	arguments  are
       parsed  by  calling ao_parse().	The argc and argv parameters are those
       passed to main().  Note that  argc  is  passed  by  reference.	Option
       strings	in the command-line (prefixed with the dash character '-') and
       any parameters following them, are parsed and deleted  from  the	 argc,
       argv  structure,	 leaving in it any additional strings that are neither
       options	nor  parameters.   Options  can	 be  invoked  multiple	times,
       ao_parse()  maintains  a	 count of these instances as well as potential
       parameters for each option.  A "--"  argument  notifies	ao_parse()  to
       avoid processing the arguments that follow it.  These unprocessed argu‐
       ments at the tail end of the command-line can be retrieved  by  calling
       ao_tail().   ao_parse() checks the command-line for invalid options and
       parameters, and verifies that mutual exclusion is satisfied and	manda‐
       tory  options are taken.	 Once the command-line options are parsed, the
       user can make queries to check which options were  actually  taken  and
       what parameters were supplied.

   Option Queries
       The function ao_ntaken() returns the number of options taken, i.e. that
       appeared on the command-line.  ao_taken() checks if  the	 given	option
       opt  was taken, returning 1 (true) or 0 (false).	 The ao_chosen() func‐
       tion simplifies the task of locating the single option taken in a mutu‐
       ally  exclusive	set.   The  set is identified by setting opt to any of
       member options in it.  ao_chosen() returns the option taken or NULL  if
       none was chosen.

       ao_ninsts()  returns  the  number  of  times  (instances) an option was
       invoked on the command-line.  This number can be helpful if  an	option
       accepts parameters.  It allows the user to request the different param‐
       eters of each instance.	Instances are numbered	sequentially  starting
       with  0.	  If  the  option  accepts  a  variable	 number of parameters,
       ao_nparams() returns the number of parameters provided for an  option's
       given  instance	number	inst.  Parameters are identified by sequential
       index values starting with 0.  If the option takes integer  parameters,
       ao_intparam()  can  be  used to retrieve a specific parameter given its
       instance number inst  and  its  index  value  idx.   The	 parameter  is
       returned	 by  reference in the inum variable.  If the option parameters
       are strings, ao_param() is used to return a  specific  parameter	 given
       its instance and index values.

       The  tail end of the command-line, formed by all arguments to the right
       of the "--" special option, can be retrieved by calling IR ao_tail()  .
       The  tail  is  returned	in  the standard argc, argv format through the
       tailc and tailv parameters passed by reference.

EXAMPLE
       The following example code demonstrates how  all_opt  can  be  used  to
       parse command-lines.  The hypothetical tool accepts two mutually exclu‐
       sive options: "foo", "bar".  The "foo" option requires 2 string parame‐
       ters  and  can only be invoked once.  For simplicity, error checking is
       not done.

       #include <all_opt.h>

       main(int argc, char *argv[])
       {
	      OPT     *ad;
	      char    *opt;

	      ad = ao_init();
	      ao_setopt(ad, "foo", NULL, 2, 0);
	      ao_setopt(ad, "bar", "foo", 0, 0);

	      ao_parse(ad, &argc, argv);

	      opt = ao_chosen(ad, "foo");

	      if (strcmp(opt, "foo") == 0) {

		      if (ao_ninsts(ad, "foo") > 1) { /* error */ }

		      printf("foo chosen: %s %s\n",
			     ao_param(ad, "foo", 0, 0),
			     ao_param(ad, "foo", 0, 1));
	      } else {
		      printf("bar taken %d times\n",
			     ao_ninsts(ad, "bar"));
	      }

	      ao_free(ad);
       }

RETURN VALUES
       In case of an error, ao_init() returns a NULL  descriptor,  ao_chosen()
       and  ao_param()	return	NULL  strings,	and ao_intparam(), ao_parse(),
       ao_setopt(), ao_setopt1(), and ao_tail() return -1.  In	addition,  the
       global variable errno is set to indicate the error.

ERRORS
       EUSAGE	       The command-line violates the option rules.

       EBADASCIINUMB   A string representing an integer has an invalid format.

LAM 7.1.2			  March, 2006			    ALL_OPT(3)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net