[newlib-cygwin.git] / newlib / libc / include / getopt.h

/****************************************************************************

getopt.h - Read command line options

AUTHOR: Gregory Pietsch
CREATED Thu Jan 09 22:37:00 1997

DESCRIPTION:

The getopt() function parses the command line arguments.  Its arguments argc
and argv are the argument count and array as passed to the main() function
on program invocation.  The argument optstring is a list of available option
characters.  If such a character is followed by a colon (`:'), the option
takes an argument, which is placed in optarg.  If such a character is
followed by two colons, the option takes an optional argument, which is
placed in optarg.  If the option does not take an argument, optarg is NULL.

The external variable optind is the index of the next array element of argv
to be processed; it communicates from one call to the next which element to
process.

The getopt_long() function works like getopt() except that it also accepts
long options started by two dashes `--'.  If these take values, it is either
in the form

--arg=value

 or

--arg value

It takes the additional arguments longopts which is a pointer to the first
element of an array of type GETOPT_LONG_OPTION_T, defined below.  The last
element of the array has to be filled with NULL for the name field.

The longind pointer points to the index of the current long option relative
to longopts if it is non-NULL.

The getopt() function returns the option character if the option was found
successfully, `:' if there was a missing parameter for one of the options,
`?' for an unknown option character, and EOF for the end of the option list.

The getopt_long() function's return value is described below.

The function getopt_long_only() is identical to getopt_long(), except that a
plus sign `+' can introduce long options as well as `--'.

Describe how to deal with options that follow non-option ARGV-elements.

If the caller did not specify anything, the default is REQUIRE_ORDER if the
environment variable POSIXLY_CORRECT is defined, PERMUTE otherwise.

REQUIRE_ORDER means don't recognize them as options; stop option processing
when the first non-option is seen.  This is what Unix does.  This mode of
operation is selected by either setting the environment variable
POSIXLY_CORRECT, or using `+' as the first character of the optstring
parameter.

PERMUTE is the default.  We permute the contents of ARGV as we scan, so that
eventually all the non-options are at the end.  This allows options to be
given in any order, even with programs that were not written to expect this.

RETURN_IN_ORDER is an option available to programs that were written to
expect options and other ARGV-elements in any order and that care about the
ordering of the two.  We describe each non-option ARGV-element as if it were
the argument of an option with character code 1.  Using `-' as the first
character of the optstring parameter selects this mode of operation.

The special argument `--' forces an end of option-scanning regardless of the
value of `ordering'.  In the case of RETURN_IN_ORDER, only `--' can cause
getopt() and friends to return EOF with optind != argc.

COPYRIGHT NOTICE AND DISCLAIMER:

Copyright (C) 1997 Gregory Pietsch

This file and the accompanying getopt.c implementation file are hereby 
placed in the public domain without restrictions.  Just give the author 
credit, don't claim you wrote it or prevent anyone else from using it.

Gregory Pietsch's current e-mail address:
gpietsch@comcast.net
****************************************************************************/

/* This is a glibc-extension header file. */

#ifndef GETOPT_H
#define GETOPT_H

#include <_ansi.h>

/* include files needed by this include file */

#define no_argument		0
#define required_argument	1
#define optional_argument	2

#ifdef __cplusplus
extern "C"
{

#endif				/* __cplusplus */

/* types defined by this include file */
  struct option
  {
    char *name;			/* the name of the long option */
    int has_arg;		/* one of the above macros */
    int *flag;			/* determines if getopt_long() returns a
				 * value for a long option; if it is
				 * non-NULL, 0 is returned as a function
				 * value and the value of val is stored in
				 * the area pointed to by flag.  Otherwise,
				 * val is returned. */
    int val;			/* determines the value to return if flag is
				 * NULL. */

  };

/* While getopt.h is a glibc extension, the following are newlib extensions.
 * They are optionally included via the __need_getopt_newlib flag.  */

#ifdef __need_getopt_newlib

  /* macros defined by this include file */
  #define NO_ARG          	no_argument
  #define REQUIRED_ARG    	required_argument
  #define OPTIONAL_ARG    	optional_argument

  /* The GETOPT_DATA_INITIALIZER macro is used to initialize a statically-
     allocated variable of type struct getopt_data.  */
  #define GETOPT_DATA_INITIALIZER	{0,0,0,0,0}

  /* These #defines are to make accessing the reentrant functions easier.  */
  #define getopt_r		__getopt_r
  #define getopt_long_r		__getopt_long_r
  #define getopt_long_only_r	__getopt_long_only_r

  /* The getopt_data structure is for reentrancy. Its members are similar to
     the externally-defined variables.  */
  typedef struct getopt_data
  {
    char *optarg;
    int optind, opterr, optopt, optwhere;
  } getopt_data;

#endif /* __need_getopt_newlib */

  /* externally-defined variables */
  extern char *optarg;
  extern int optind;
  extern int opterr;
  extern int optopt;

  /* function prototypes */
  int _EXFUN (getopt,
	      (int __argc, char *const __argv[], const char *__optstring));

  int _EXFUN (getopt_long,
	      (int __argc, char *const __argv[], const char *__shortopts,
	       const struct option * __longopts, int *__longind));

  int _EXFUN (getopt_long_only,
	      (int __argc, char *const __argv[], const char *__shortopts,
	       const struct option * __longopts, int *__longind));

  int _EXFUN (__getopt_r,
	      (int __argc, char *const __argv[], const char *__optstring,
	       struct getopt_data * __data));

  int _EXFUN (__getopt_long_r,
	      (int __argc, char *const __argv[], const char *__shortopts,
	       const struct option * __longopts, int *__longind,
	       struct getopt_data * __data));

  int _EXFUN (__getopt_long_only_r,
	      (int __argc, char *const __argv[], const char *__shortopts,
	       const struct option * __longopts, int *__longind,
	       struct getopt_data * __data));

#ifdef __cplusplus
};

#endif /* __cplusplus  */

#endif /* GETOPT_H */

/* END OF FILE getopt.h */
Commit	Line	Data
791c9bda JJ	1	/****************************************************************************
	2
	3	getopt.h - Read command line options
	4
	5	AUTHOR: Gregory Pietsch
	6	CREATED Thu Jan 09 22:37:00 1997
	7
	8	DESCRIPTION:
	9
	10	The getopt() function parses the command line arguments. Its arguments argc
	11	and argv are the argument count and array as passed to the main() function
	12	on program invocation. The argument optstring is a list of available option
	13	characters. If such a character is followed by a colon (`:'), the option
	14	takes an argument, which is placed in optarg. If such a character is
	15	followed by two colons, the option takes an optional argument, which is
	16	placed in optarg. If the option does not take an argument, optarg is NULL.
	17
	18	The external variable optind is the index of the next array element of argv
	19	to be processed; it communicates from one call to the next which element to
	20	process.
	21
	22	The getopt_long() function works like getopt() except that it also accepts
	23	long options started by two dashes `--'. If these take values, it is either
	24	in the form
	25
	26	--arg=value
	27
	28	or
	29
	30	--arg value
	31
	32	It takes the additional arguments longopts which is a pointer to the first
	33	element of an array of type GETOPT_LONG_OPTION_T, defined below. The last
	34	element of the array has to be filled with NULL for the name field.
	35
	36	The longind pointer points to the index of the current long option relative
	37	to longopts if it is non-NULL.
	38
	39	The getopt() function returns the option character if the option was found
	40	successfully, `:' if there was a missing parameter for one of the options,
	41	`?' for an unknown option character, and EOF for the end of the option list.
	42
	43	The getopt_long() function's return value is described below.
	44
	45	The function getopt_long_only() is identical to getopt_long(), except that a
	46	plus sign `+' can introduce long options as well as `--'.
	47
	48	Describe how to deal with options that follow non-option ARGV-elements.
	49
	50	If the caller did not specify anything, the default is REQUIRE_ORDER if the
	51	environment variable POSIXLY_CORRECT is defined, PERMUTE otherwise.
	52
	53	REQUIRE_ORDER means don't recognize them as options; stop option processing
	54	when the first non-option is seen. This is what Unix does. This mode of
	55	operation is selected by either setting the environment variable
	56	POSIXLY_CORRECT, or using `+' as the first character of the optstring
	57	parameter.
	58
	59	PERMUTE is the default. We permute the contents of ARGV as we scan, so that
	60	eventually all the non-options are at the end. This allows options to be
	61	given in any order, even with programs that were not written to expect this.
	62
	63	RETURN_IN_ORDER is an option available to programs that were written to
	64	expect options and other ARGV-elements in any order and that care about the
65	ordering of the two. We describe each non-option ARGV-element as if it were
66	the argument of an option with character code 1. Using `-' as the first
67	character of the optstring parameter selects this mode of operation.
68
69	The special argument `--' forces an end of option-scanning regardless of the
70	value of `ordering'. In the case of RETURN_IN_ORDER, only `--' can cause
71	getopt() and friends to return EOF with optind != argc.
72
73	COPYRIGHT NOTICE AND DISCLAIMER:
74
75	Copyright (C) 1997 Gregory Pietsch
76
77	This file and the accompanying getopt.c implementation file are hereby
78	placed in the public domain without restrictions. Just give the author
79	credit, don't claim you wrote it or prevent anyone else from using it.
80
81	Gregory Pietsch's current e-mail address:
82	gpietsch@comcast.net
83	****************************************************************************/
84
c6228428	85	/* This is a glibc-extension header file. */
76ff710c	86
791c9bda JJ	87	#ifndef GETOPT_H
	88	#define GETOPT_H
	89
	90	#include <_ansi.h>
	91
	92	/* include files needed by this include file */
	93
c6228428 JJ	94	#define no_argument 0
	95	#define required_argument 1
	96	#define optional_argument 2
791c9bda JJ	97
	98	#ifdef __cplusplus
	99	extern "C"
	100	{
76ff710c JJ	101
	102	#endif /* __cplusplus */
	103
	104	/* types defined by this include file */
	105	struct option
	106	{
	107	char name; / the name of the long option */
	108	int has_arg; /* one of the above macros */
	109	int flag; / determines if getopt_long() returns a
	110	* value for a long option; if it is
	111	* non-NULL, 0 is returned as a function
	112	* value and the value of val is stored in
	113	* the area pointed to by flag. Otherwise,
	114	* val is returned. */
	115	int val; /* determines the value to return if flag is
	116	* NULL. */
	117
	118	};
	119
c6228428 JJ	120	/* While getopt.h is a glibc extension, the following are newlib extensions.
	121	* They are optionally included via the __need_getopt_newlib flag. */
	122
	123	#ifdef __need_getopt_newlib
	124
	125	/* macros defined by this include file */
	126	#define NO_ARG no_argument
	127	#define REQUIRED_ARG required_argument
	128	#define OPTIONAL_ARG optional_argument
	129
	130	/* The GETOPT_DATA_INITIALIZER macro is used to initialize a statically-
	131	allocated variable of type struct getopt_data. */
	132	#define GETOPT_DATA_INITIALIZER {0,0,0,0,0}
	133
	134	/* These #defines are to make accessing the reentrant functions easier. */
	135	#define getopt_r __getopt_r
	136	#define getopt_long_r __getopt_long_r
	137	#define getopt_long_only_r __getopt_long_only_r
	138
76ff710c JJ	139	/* The getopt_data structure is for reentrancy. Its members are similar to
	140	the externally-defined variables. */
	141	typedef struct getopt_data
	142	{
	143	char *optarg;
	144	int optind, opterr, optopt, optwhere;
	145	} getopt_data;
791c9bda	146
c6228428 JJ	147	#endif /* __need_getopt_newlib */
c6228428 JJ	148
791c9bda JJ	149	/* externally-defined variables */
	150	extern char *optarg;
	151	extern int optind;
	152	extern int opterr;
	153	extern int optopt;
	154
	155	/* function prototypes */
76ff710c JJ	156	int _EXFUN (getopt,
	157	(int __argc, char const __argv[], const char __optstring));
	158
	159	int _EXFUN (getopt_long,
	160	(int __argc, char const __argv[], const char __shortopts,
	161	const struct option * __longopts, int *__longind));
	162
	163	int _EXFUN (getopt_long_only,
	164	(int __argc, char const __argv[], const char __shortopts,
	165	const struct option * __longopts, int *__longind));
	166
	167	int _EXFUN (__getopt_r,
	168	(int __argc, char const __argv[], const char __optstring,
	169	struct getopt_data * __data));
	170
	171	int _EXFUN (__getopt_long_r,
	172	(int __argc, char const __argv[], const char __shortopts,
	173	const struct option * __longopts, int *__longind,
	174	struct getopt_data * __data));
	175
	176	int _EXFUN (__getopt_long_only_r,
	177	(int __argc, char const __argv[], const char __shortopts,
	178	const struct option * __longopts, int *__longind,
	179	struct getopt_data * __data));
791c9bda JJ	180
	181	#ifdef __cplusplus
	182	};
	183
76ff710c	184	#endif /* __cplusplus */
791c9bda JJ	185
	186	#endif /* GETOPT_H */
	187
	188	/* END OF FILE getopt.h */