Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ParseArgv(3)		   Library Functions Manual		  ParseArgv(3)

______________________________________________________________________________

NAME
       ParseArgv - process command-line	options

SYNOPSIS
       #include	<ParseArgv.h>

       int
       ParseArgv(argcPtr, argv,	argTable, flags)

ARGUMENTS
       int	  argcPtr     (in/out)	Pointer	 to  number  of	 arguments  in
					argv;  gets modified to	hold number of
					unprocessed  arguments that remain af-
					ter the	call.

       char	  **argv      (in/out)	Command	line arguments passed to  main
					program.  Modified to hold unprocessed
					arguments that remain after the	call.

       ArgvInfo	  *argTable   (in)	Array of argument descriptors,	termi-
					nated by element with type ARGV_END.

       int	  flags	      (in)	If  non-zero, then it specifies	one or
					more flags that	control	the parsing of
					arguments.   Different	flags  may  be
					OR'ed together.	 The flags currently
					defined	are ARGV_DONT_SKIP_FIRST_ARG,
					ARGV_NO_ABBREV,	ARGV_NO_LEFTOVERS,
					ARGV_NO_DEFAULTS and ARGV_NO_PRINT.
______________________________________________________________________________

DESCRIPTION
       ParseArgv  processes  an	array of command-line arguments	according to a
       table describing	the kinds of arguments that are	expected.  Each	of the
       arguments  in  argv is processed	in turn:  if it	matches	one of the en-
       tries in	argTable, the argument is processed according  to  that	 entry
       and  discarded.	 The  arguments	that do	not match anything in argTable
       are copied down to the beginning	of argv	(retaining their original  or-
       der) and	returned to the	caller.	 At the	end of the call	ParseArgv sets
       *argcPtr	to hold	the number of arguments	that are  left	in  argv,  and
       argv[*argcPtr]  will  hold the value NULL.  Normally, ParseArgv assumes
       that argv[0] is a command name, so it is	treated	like an	argument  that
       doesn't	match  argTable	 and  returned to the caller;  however,	if the
       ARGV_DONT_SKIP_FIRST_ARG	bit is set in flags then argv[0] will be  pro-
       cessed just like	the other elements of argv.

       ParseArgv  normally  returns  the  value	FALSE (0).  If an error	occurs
       while parsing the arguments, then TRUE (1) is  returned	and  ParseArgv
       will print an error message on stderr. In the event of an error return,
       *argvPtr	will not have been modified, but argv  could  have  been  par-
       tially modified.	 The possible causes of	errors are explained below.

       The  argTable array specifies the kinds of arguments that are expected;
       each of its entries has the following structure:	typedef	struct {
	   char*key;
	   int type;
	   char*src;
	   char*dst;
	   char*help; }	ArgvInfo;

       The key field is	a string such as ``-display'' or ``-bg'' that is  com-
       pared  with the values in argv.	Type indicates how to process an argu-
       ment that matches key (more on this below).  Src	and dst	are additional
       values  used  in	processing the argument.  Their	exact usage depends on
       type, but typically src indicates a value and dst  indicates  where  to
       store  the  value.   The	char * declarations for	src and	dst are	place-
       holders:	 the actual types may be different.  Lastly, help is a	string
       giving a	brief description of this option;  this	string is printed when
       users ask for help about	command-line options.

       When processing an argument in argv, ParseArgv compares the argument to
       each  of	 the key's in argTable.	 ParseArgv selects the first specifier
       whose key matches the argument exactly, if  such	 a  specifier  exists.
       Otherwise  ParseArgv  selects  a	 specifier for which the argument is a
       unique abbreviation.  If	the argument is	a unique abbreviation for more
       than one	specifier, then	an error is returned.  If there	is no matching
       entry in	argTable, then the argument is skipped	and  returned  to  the
       caller.

       Once  a	matching  argument specifier is	found, ParseArgv processes the
       argument	according to the type field of the  specifier.	 The  argument
       that  matched  key  is called ``the matching argument'' in the descrip-
       tions below.  As	part of	the processing,	ParseArgv  may	also  use  the
       next  argument  in  argv	 after	the matching argument, which is	called
       ``the following argument''.  The	legal values for type,	and  the  pro-
       cessing that they cause,	are as follows:

       ARGV_END
	      Marks  the  end  of  the table.  The last	entry in argTable must
	      have this	type;  all of its other	fields are ignored and it will
	      never match any arguments.

       ARGV_CONSTANT
	      Src  is treated as an integer and	dst is treated as a pointer to
	      an integer.  Src is stored at *dst.  The	matching  argument  is
	      discarded.

       ARGV_INT
	      The  following  argument	must  contain an integer string	in the
	      format accepted by strtol	(e.g. ``0'' and	``0x'' prefixes	may be
	      used  to	specify	 octal	or hexadecimal numbers,	respectively).
	      Dst is treated as	a pointer to an	integer;  the following	 argu-
	      ment  is	converted to an	integer	value and stored at *dst.  Src
	      is treated as an integer count: if its value is greater than  1,
	      then  that many arguments	are processed and Dst is treated as an
	      array pointer.  The matching and following  arguments  are  dis-
	      carded from argv.

       ARGV_FLOAT
	      The  following  argument must contain a floating-point number in
	      the format accepted by strtol.  Dst is treated as	the address of
	      an  double-precision  floating point value;  the following argu-
	      ment is converted	to a  double-precision	value  and  stored  at
	      *dst.   Src  is  treated	as  an	integer	count: if its value is
	      greater than 1, then that	many arguments are processed  and  Dst
	      is  treated as an	array pointer.	The matching and following ar-
	      guments are discarded from argv.

       ARGV_STRING
	      In this form, dst	is  treated  as	 a  pointer  to	 a  (char  *);
	      ParseArgv	 stores	 at  *dst a pointer to the following argument,
	      and discards the matching	and  following	arguments  from	 argv.
	      Src is treated as	an integer count: if its value is greater than
	      1, then that many	arguments are processed	and Dst	is treated  as
	      an array pointer.

       ARGV_HELP
	      When this	kind of	option is encountered, ParseArgv uses the help
	      fields of	argTable to format a message describing	all the	 valid
	      arguments.   The	message	is written on stderr and ParseArgv re-
	      turns TRUE.  When	this happens, the caller normally aborts.   If
	      the  key field of	a ARGV_HELP specifier is NULL, then the	speci-
	      fier will	never match any	arguments;  in this case the specifier
	      simply provides extra documentation, which will be included when
	      some other ARGV_HELP entry causes	help  information  to  be  re-
	      turned.

       ARGV_REST
	      This  option is used by programs or commands that	allow the last
	      several of their options to be the name and/or options for  some
	      other program.  If a ARGV_REST argument is found,	then ParseArgv
	      doesn't process any of the remaining arguments;  it returns them
	      all  at  the beginning of	argv (along with any other unprocessed
	      arguments).  In addition,	ParseArgv treats dst as	the address of
	      an  integer  value, and stores at	*dst the index of the first of
	      the ARGV_REST options in the returned  argv.   This  allows  the
	      program  to  distinguish the ARGV_REST options from other	unpro-
	      cessed options that preceeded the	ARGV_REST.

       ARGV_FUNC
	      For this kind of argument, src is	treated	as the	address	 of  a
	      procedure,  which	 is invoked to process the following argument.
	      The procedure should have	the following structure: int func(dst,
	      key, nextArg)
		  char	  *dst;
		  char	  *key;
		  char	  *nextArg; { }

	      The dst and key parameters will contain the corresponding	fields
	      from the argTable	entry, and nextArg will	point to the following
	      argument	from  argv (or NULL if there aren't any	more arguments
	      left in argv).  If func uses nextArg (so that  ParseArgv	should
	      discard  it),  then it should return 1.  Otherwise it should re-
	      turn 0 and TkParseArgv will process the  following  argument  in
	      the  normal  fashion.   In either	event the matching argument is
	      discarded.

       ARGV_GENFUNC
	      This form	provides a more	general	procedural escape.  It	treats
	      src as the address of a procedure, and passes that procedure all
	      of the remaining arguments.  The procedure should	have the  fol-
	      lowing form: int genfunc(dst, key, argc, argv)
		  char	  *dst;
		  char	  *key;
		  int argc;
		  char	  **argv; { }

	      The dst and key parameters will contain the corresponding	fields
	      from the argTable	entry.	Argc and argv refer to all of the  op-
	      tions  after the matching	one.  Genfunc should behave in a fash-
	      ion similar to ParseArgv:	 parse as many of the remaining	 argu-
	      ments  as	 it  can,  then	return any that	are left by compacting
	      them to the beginning of argv (starting  at  argv[0]).   Genfunc
	      should  return  a	 count of how many arguments are left in argv;
	      ParseArgv	will process them.  If	genfunc	 encounters  an	 error
	      then  it should print an error message on	stderr,	and return -1;
	      when this	happens	ParseArgv will abort its processing and	return
	      TRUE.

FLAGS
       ARGV_DONT_SKIP_FIRST_ARG
	      ParseArgv	 normally treats argv[0] as a program or command name,
	      and returns it to	the  caller  just  as  if  it  hadn't  matched
	      argTable.	 If this flag is given,	then argv[0] is	not given spe-
	      cial treatment.

       ARGV_NO_ABBREV
	      Normally,	ParseArgv accepts unique abbreviations for key	values
	      in argTable.  If this flag is given then only exact matches will
	      be acceptable.

       ARGV_NO_LEFTOVERS
	      Normally,	 ParseArgv  returns  unrecognized  arguments  to   the
	      caller.	If this	bit is set in flags then ParseArgv will	return
	      an error if  it  encounters  any	argument  that	doesn't	 match
	      argTable.	  The  only  exception	to this	rule is	argv[0], which
	      will be returned to  the	caller	with  no  errors  as  long  as
	      ARGV_DONT_SKIP_FIRST_ARG isn't specified.

       ARGV_NO_DEFAULTS
	      Normally,	ParseArgv searches an internal table of	standard argu-
	      ment specifiers in addition to argTable.	If this	bit is set  in
	      flags, then ParseArgv will use only argTable and not its default
	      table.

       ARGV_NO_PRINT
	      Normally,	ParseArgv prints error message on stderr. If this  bit
	      is  set  in  flags, then ParseArgv will not print	any error mes-
	      sages.

EXAMPLE
       Here is an example definition of	an argTable and	 some  sample  command
       lines  that  use	the options.  Note the effect on argc and argv;	 argu-
       ments processed by ParseArgv are	eliminated from	argv, and argc is  up-
       dated to	reflect	reduced	number of arguments.  /*
	* Define and set default values	for globals.
	*/  int	 debugFlag  =  0;  int numReps = 100; char defaultFileName[] =
       "out"; char *fileName = defaultFileName;	Boolean	exec = FALSE;

       /*
	* Define option	descriptions.
	*/ ArgvInfo argTable[] = {     {"-X", ARGV_CONSTANT, (char *) 1, (char
       *)   &debugFlag,		  "Turn	 on  debugging	printfs"},	{"-N",
       ARGV_INT, (char *) NULL,	(char *) &numReps,	   "Number of  repeti-
       tions"},	     {"-of",  ARGV_STRING,  (char *) NULL, (char *) &fileName,
	       "Name of	file for output"},     {"x", ARGV_REST,	(char *) NULL,
       (char  *) &exec,		"File to exec, followed	by any arguments (must
       be last argument)."},	 {(char	*)  NULL,  ARGV_END,  (char  *)	 NULL,
       (char *)	NULL,	      (char *) NULL} };

       main(argc, argv)	    int	argc;	  char *argv[];	{     ...

	   if (ParseArgv(&argc,	argv, argTable,	0)) {	      exit(1);	   }

	   /*	   * Remainder of the program.	     */	}

       Note  that  default  values  can	 be  assigned  to  variables  named in
       argTable:  the variables	will only be overwritten if the	particular ar-
       guments	are  present in	argv.  Here are	some example command lines and
       their effects.  prog -N 200 infile      # just sets the	numReps	 vari-
       able  to	 200  prog  -of	 out200	 infile	  # sets fileName to reference
       "out200"	prog -XN 10 infile	# sets the debug flag, also sets  num-
       Reps  In	all of the above examples, argc	will be	set by ParseArgv to 2,
       argv[0] will be ``prog'', argv[1] will be ``infile'', and argv[2]  will
       be NULL.

KEYWORDS
       arguments, command line,	options

								  ParseArgv(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | FLAGS | EXAMPLE | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ParseArgv&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help