newlib/libc/include/getopt.h

   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
  85 /* This is a glibc-extension header file. */
  86
  87 #ifndef GETOPT_H
  88 #define GETOPT_H
  89
  90 #include <_ansi.h>
  91
  92 /* include files needed by this include file */
  93
  94 #define no_argument             0
  95 #define required_argument       1
  96 #define optional_argument       2
  97
  98 #ifdef __cplusplus
  99 extern "C"
 100 {
 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
 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
 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;
 146
 147 #endif /* __need_getopt_newlib */
 148
 149   /* externally-defined variables */
 150   extern char *optarg;
 151   extern int optind;
 152   extern int opterr;
 153   extern int optopt;
 154
 155   /* function prototypes */
 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));
 180
 181 #ifdef __cplusplus
 182 };
 183
 184 #endif /* __cplusplus  */
 185
 186 #endif /* GETOPT_H */
 187
 188 /* END OF FILE getopt.h */