This is gengetopt.info, produced by makeinfo version 4.8 from gengetopt.texinfo. START-INFO-DIR-ENTRY * GenGetopt: (gengetopt). A tool for generating a C function which parses command line arguments. END-INFO-DIR-ENTRY This manual is for GNU Gengetopt (version 2.19.1, 4 January 2008), a tool to write command line option parsers for C programs. Copyright (C) 2001 - 2007 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." INFO-DIR-SECTION GNU programming tools START-INFO-DIR-ENTRY * Gengetopt: (gengetopt). Create command line options parsers END-INFO-DIR-ENTRY  File: gengetopt.info, Node: Top, Next: Audience, Prev: (dir), Up: (dir) Gengetopt ********* Gengetopt is a tool to write command line option parsing code for C programs. This is Edition 2.19.1 of the Gengetopt manual. This file documents GNU Gengetopt version 2.19.1. This manual is for GNU Gengetopt (version 2.19.1, 4 January 2008), a tool to write command line option parsers for C programs. Copyright (C) 2001 - 2007 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development." * Menu: * Audience:: What is gengetopt and who it is for. * Copying:: Your rights. * Installation:: Download and Installation * Basic Usage:: How to run Gengetopt; syntax of .ggo files * Invoking gengetopt:: gengetopt command line options * Terminology:: Definitions of options, values, and so forth. * Group options:: Mutual exclusive options * Configuration files:: Parsing a configuration file * Multiple Options:: Multiple options * String Parsers and Multiple Parsers:: Using multiple parsers in the same program * No getopt_long:: What if getopt_long is not available? * Bugs:: What is lame and/or buggy in Gengetopt 2.19.1 * Mailing Lists:: For discussions and announces * Index:: Index.  File: gengetopt.info, Node: Audience, Next: Copying, Prev: Top, Up: Top Audience ******** Gengetopt is a tool to generate C code to parse the command line arguments `argc' and `argv' that are part of every C or C++ program. The generated code uses the C library function `getopt_long' to perform the actual command line parsing. This manual is written for C and C++ programmers, specifically the _lazy_ ones. If you've written any non-trivial C program, you've had to deal with argument parsing. It isn't particularly difficult, nor is it particularly exciting. It _is_ one of the classic programming nuisances, which is why most books on programming leave it as an exercise for the reader. Gengetopt can save you from this work, leaving you free to focus on the interesting parts of your program. Thus your program will be able to handle command line options such as: myprog --input foo.c -o foo.o --no-tabs -i 100 *.class And both long options (those that start with `--') and short options (start with `-' and consist of only one character) can be handled (see *Note Terminology:: for further details). For standards about short and long options you may want to take a look at the GNU Coding Standards (`http://www.gnu.org/prep/standards_toc.html'). Gengetopt can also generate a function to save the command line options into a file (see *Note Basic Usage::), and a function to read the command line options from a file (see *Note Configuration files::). Of course, these two kinds of files are compliant.  File: gengetopt.info, Node: Copying, Next: Installation, Prev: Audience, Up: Top Gengetopt Copying Conditions **************************** Gengetopt is free software; you are free to use, share and modify it under the terms of the GNU General Public License that accompanies this manual. The code that Gengetopt generates is also free software; however it is licensed with a simple all-permissive license instead of the GPL or LGPL. You are free to do anything you like with the generated code, including incorporating it into or linking it with proprietary software. Gengetopt was originally written by Roberto Arturo Tena Sanchez. It is currently maintained by Lorenzo Bettini `http://www.lorenzobettini.it'. A primordial version of *Note Terminology:: was written by Adam Greenblatt.  File: gengetopt.info, Node: Installation, Next: Basic Usage, Prev: Copying, Up: Top 1 Installation ************** See the file `INSTALL' for detailed building and installation instructions; anyway if you're used to compiling Linux software that comes with sources you may simply follow the usual procedure, i.e. untar the file you downloaded in a directory and then: cd ./configure make make install Note: unless you specify a different install directory by `--prefix' option of configure (e.g. `./configure --prefix='), you must be root to run `make install'. Files will be installed in the following directories: `executables' `/prefix/bin' `docs' `/prefix/share/doc/gengetopt' `examples' `/prefix/share/doc/gengetopt/examples' `additional files' `/prefix/share/gengetopt' Default value for prefix is `/usr/local' but you may change it with `--prefix' option to configure. 1.1 Download ============ You can download it from GNU's ftp site: `ftp://ftp.gnu.org/gnu/gengetopt' or from one of its mirrors (see `http://www.gnu.org/prep/ftp.html'). I do not distribute Windows binaries anymore; since, they can be easily built by using Cygnus C/C++ compiler, available at `http://www.cygwin.com'. However, if you don't feel like downloading such compiler, you can request such binaries directly to me, by e-mail (find my e-mail at my home page) and I can send them to you. Archives are digitally signed by me (Lorenzo Bettini) with GNU gpg (`http://www.gnupg.org'). My GPG public key can be found at my home page (`http://www.lorenzobettini.it'). You can also get the patches, if they are available for a particular release (see below for patching from a previous version). 1.2 Anonymous CVS Access ======================== This project's CVS repository can be checked out through anonymous (pserver) CVS with the following instruction: cvs -z3 -d:pserver:anonymous@cvs.savannah.gnu.org:/sources/gengetopt co gengetopt Further instructions can be found at the address: `http://savannah.gnu.org/projects/gengetopt'. Please notice that this way you will get the latest development sources of Gengetopt, which may also be unstable. This solution is the best if you intend to correct/extend this program: you should send me patches against the latest cvs repository sources. If, on the contrary, you want to get the sources of a given release, through cvs, say, e.g., version X.Y.Z, you must specify the tag `rel_X_Y_Z' when you run the cvs command or the `cvs update' command. When you compile the sources that you get through the cvs repository, before running the `configure' and `make' commands, you should, at least the first time, run the command: sh reconf This will run the autotools commands in the correct order, and also copy possibly missing files. You should have installed recent versions of `automake' and `autoconf' in order for this to succeed. You will also need `flex' and `bison'. NOTICE: This convention holds since release 2.14. 1.3 What you need to build gengetopt ==================================== Gengetopt has been developed under GNU/Linux, using gcc (C++), and bison (yacc) and flex (lex), and ported under Win32 with Cygnus C/C++compiler, available at `http://www.cygwin.com'. For developing gengetopt, I use the excellent GNU Autoconf(1) and GNU Automake(2). Since version 2.19 I also started to use Gnulib - The GNU Portability Library(3), "a central location for common GNU code, intended to be shared among GNU packages" (for instance, I rely on Gnulib for checking for the presence and correctness of `getopt_long' function, *Note Use Gnulib::). Moreover _GNU Gengen_ (`http://www.gnu.org/software/gengen') is used for automatically generating the code that generates the command line parser. Actually, you don't need all these tools above to build gengetopt because I provide generated sources, unless you want to develop gengetopt. The code generated by gengetopt relies on the `getopt_long' function that is usually in the standard C library; however, there may be some implementations of the C library that don't include it; we refer to *Note No getopt_long::, for instructions on how to check whether getopt_long is part of the library and how to deal with their lacking (using autoconf and automake). 1.4 Patching from a previous version ==================================== If you downloaded a patch, say `gengetopt-1.3-1.3.1-patch.gz' (i.e., the patch to go from version 1.3 to version 1.3.1), cd to the directory with sources from the previous version (gengetopt-1.3) and type: gunzip -cd ../gengetopt-1.3-1.3.1.patch.gz | patch -p1 and restart the compilation process (if you had already run configure a simple make should do). ---------- Footnotes ---------- (1) `http://www.gnu.org/software/autoconf' (2) `http://www.gnu.org/software/automake' (3) `http://www.gnu.org/software/gnulib'  File: gengetopt.info, Node: Basic Usage, Next: Invoking gengetopt, Prev: Installation, Up: Top 2 Basic Usage ************* The command line options, which have to be handled by gengetopt generated function, are specified in a file (typically with `.ggo' extension). This file consist in lines of sentences with the formats shown below. Commands in {} are optional (the `option' sentences need not to be given in separate lines): package "" version "" purpose "" usage "" description "" args "" option "" {argtype} {typestr=""} {values="","",...} {default=""} {dependon=""} {required} {argoptional} {multiple} {hidden} option flag section "section name" {sectiondesc="optional section description"} text "a textual sentence" Where: `package' This has the precedence over `PACKAGE' generated by autoconf. Optional. `version' This has the precedence over `VERSION' generated by autoconf. Optional. `purpose' What the program does (even on more than one line), it will be printed with the help, before the usage string. Optional. `usage' The "Usage" string that will be printed with the help(1). If not specified, it will be generated automatically. Optional. `description' The "Description" string that will be printed with the help(2), after the usage string. Optional. `args' With `args'(3) you can specify options that will be added to the command line options of gengetopt itself. For instance, if you always run gengetopt on your input file with the options `--no-handle-error --string-parser -u', you can add these options in the input file like this: args "--no-handle-error --string-parser -u" and remove those recurrent options from the command line. Optional. `long' The long option, a double quoted string with upper and lower case characters, digits, a dash (`-') and a dot (`.'). No spaces allowed. The name of the variables generated to store arguments (see later in this section) are long options converted to be legal C variable names. This means that `.' and `-' are both replaced by `_'. `short' The short option, a single upper or lower case char, or a digit. If a `-' is specified, then no short option is considered for the long option (thus long options with no associated short options are allowed). `desc' This description will be printed during the output of `--help'. Wrapping will be automatically performed. `argtype' `string', `int', `short', `long', `float', `double', `longdouble' or `longlong'. If no type is specified the option does not accept an argument. `typestr' a description for the type of the values for the option. This will be used during the output of `--help' (e.g., `"filename"' instead of simply `STRING', or `"portnumber"' instead of simply `INT'). `values' a list of strings containing all the possible values that can be passed to the option. The type is considered string and must not be specified. `default' an optional default value for the option. The value must always be specified as a double quoted string. `dependon' this option depends on another option (whose long name description is specified). If this option is given at command line but not the option it depends on, an error will be generated. `required' `required' or `optional'. This specifies whether such option must be given at each program invocation. These keywords were introduced in release 2.17. Before, you had to use the keywords `yes' or `no'. You can still use these keywords but their use is not advised since they are not much explicative. `argoptional' If this flag is specified then this option has an argument that is optional. In this case, when you specify the argument at command line, please use `=' in case you use a long option, and avoid spaces if you use short option. For instance, if the option with optional argument is `-B|--bar', use the following command line syntax: `-B15' or `--bar=15', and NOT the following one `-B 15' nor `--bar 15'. By using this specification together with `default' you can obtain an option that even if not explicitly specified will have the default value, and if it is specified without an argument it will have, again, the default value. `multiple' If this flag is specified then this option can be specified more than once at command line; all the values for this option are stored in an array. You can also specify the number of occurrences that a multiple option must be specified. Notice that this is independent from the `required' flag. See *Note Multiple Options::. `hidden' If an option is "hidden" it will not appear in the output of `--help' but it can still be specified at command line(4). In case hidden options are used, the command line option `--full-help' will also be generated. This will print also the hidden options(5). `on/off' `on' or `off'. This is the state of the flag when the program starts. If user specifies the option, the flag toggles. For strings (delimited by `"') the following convention is adopted(6): a string spanning more than one line will be interpreted with the corresponding line breaks; if the line break is not desired one can use the backslash `\' to break the line without inserting a line break. A line break in a string can also be inserted with the string `\n'. Here are some examples: "This string will be interpreted into two lines exactly as it is" "This string is specified with two lines \ but interpreted as specified in only one line \ i.e., without explicit line break" "This string\nwill have a line break" Moreover, if the character `"' must be specified in the string, it will have to be escaped with the backslash(7): "This string contains \"a quoted string\" inside" The part that must be provided in the correct order is option "" while the other specifications can be given in any order(8). Thus, for instance option "" {argtype} {typestr=""} is the same as option "" {typestr=""} {argtype} Comments begin with `#' in any place (but in strings) of the line and ends in the end of line. Notice that the options `-h,--help' and `-V,--version' are added automatically; however, if you specify an option yourself that has `h' as short form or `help' as long form, then `-h,--help' is not added (and you have to handle the help option manually). The same holds for `-V,--version'. In case hidden options are used, *Note Hidden options: hidden, the command line option `--full-help' will also be generated. This will print also the hidden options(9). Options can be part of sections, that provide a more meaningful descriptions of the options. A _section_ can be defined with the following syntax (the `sectiondesc' is optional) and all the options following a section declaration are considered part of that sections: section "section name" {sectiondesc="optional section description"} Notice that the separation in sections is stronger than separation in groups of mutual exclusive options (see *Note Group options::). Furthermore, sections should not be inserted among group options (but only externally). A section makes sense only if it is followed by some options. If you don't specify any option after a section, that section will not be printed at all. If you need to simply insert some text in the output of `--help', then you must use `text', explained in the next paragraph. You can insert, among options, a textual string that will be printed in the output of `--help'(10): text "\nA text description with possible line\nbreaks" Of course, you can use this mechanism even to manually insert blank lines among options with an empty text string: text "" You can also specify the list of `values' that can be passed to an option (in that case the option has type `string'). If a value that is not in the list is passed, an error is raised. You can think of such options as _enumerated_ options. It is not necessary to pass the complete value at the command line option: a non ambiguous prefix will do. For instance, if the accepted values are `"foo","bar","foobar"', then you can pass at the command line the value `"b"' and the value `"bar"' will be selected, or the value `"foob"' and the value `"foobar"' will be selected; instead, passing the value `"fo"' will raise an ambiguity error. Here's an example of such a file (the file is called `sample1.ggo') # Name of your program package "sample1" # don't use package if you're using automake # Version of your program version "2.0" # don't use version if you're using automake # Options option "str-opt" s "A string option, for a filename" string typestr="filename" optional text "\nA brief text description" text " before the other options.\n" option "my-opt" m "Another integer option, \ this time the description of the option should be \"quite\" long to \ require wrapping... possibly more than one wrapping :-) \ especially if I\nrequire a line break" int optional option "int-opt" i "A int option" int yes section "more involved options" sectiondesc="the following options\nare more complex" text "" option "flag-opt" - "A flag option" flag off option "funct-opt" F "A function option" optional section "last option section" option "long-opt" - "A long option" long optional option "def-opt" - "A string option with default" string default="Hello" optional option "enum-opt" - "A string option with list of values" values="foo","bar","hello","bye" default="hello" optional option "secret" S "hidden option will not appear in --help" int optional hidden option "dependant" D "option that depends on str-opt" int optional dependon="str-opt" text "\nAn ending text." The simplest way to use gengetopt is to pass this file as the standard input, i.e.: gengetopt < sample1.ggo By default gengetopt generates `cmdline.h' and `cmdline.c'. Otherwise we can specify these names with a command line option: gengetopt < sample1.ggo --file-name=cmdline1 --unamed-opts The option `--unamed-opts' allows the generated command line parser to accept also names, without an option (for instance you can pass a file name without an option in front of it, and also use wildcards, such as `*.c', `foo*.?' and so on). These are also called _parameters_ (see *Note Terminology::). You can specify an optional description for these additional names (default is `FILES'). In `cmdline1.h' you'll find the generated C struct: /* cmdline1.h */ /* File autogenerated by gengetopt version 2.19.1 */ #ifndef CMDLINE1_H #define CMDLINE1_H /* If we use autoconf. */ #ifdef HAVE_CONFIG_H #include "config.h" #endif #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ #ifndef CMDLINE_PARSER_PACKAGE #define CMDLINE_PARSER_PACKAGE "sample1" #endif #ifndef CMDLINE_PARSER_VERSION #define CMDLINE_PARSER_VERSION "2.0" #endif struct gengetopt_args_info { const char *help_help; /* Print help and exit help description. */ const char *full_help_help; /* Print help, including hidden options, and exit help description. */ const char *version_help; /* Print version and exit help description. */ char * str_opt_arg; /* A string option, for a filename. */ char * str_opt_orig; /* A string option, for a filename original value given at command line. */ const char *str_opt_help; /* A string option, for a filename help description. */ int my_opt_arg; /* Another integer option, this time the description of the option should be \"quite\" long to require wrapping... possibly more than one wrapping :-) especially if I\nrequire a line break. */ char * my_opt_orig; /* Another integer option, this time the description of the option should be \"quite\" long to require wrapping... possibly more than one wrapping :-) especially if I\nrequire a line break original value given at command line. */ const char *my_opt_help; /* Another integer option, this time the description of the option should be \"quite\" long to require wrapping... possibly more than one wrapping :-) especially if I\nrequire a line break help description. */ int int_opt_arg; /* A int option. */ char * int_opt_orig; /* A int option original value given at command line. */ const char *int_opt_help; /* A int option help description. */ int flag_opt_flag; /* A flag option (default=off). */ const char *flag_opt_help; /* A flag option help description. */ const char *funct_opt_help; /* A function option help description. */ long long_opt_arg; /* A long option. */ char * long_opt_orig; /* A long option original value given at command line. */ const char *long_opt_help; /* A long option help description. */ char * def_opt_arg; /* A string option with default (default='Hello'). */ char * def_opt_orig; /* A string option with default original value given at command line. */ const char *def_opt_help; /* A string option with default help description. */ char * enum_opt_arg; /* A string option with list of values (default='hello'). */ char * enum_opt_orig; /* A string option with list of values original value given at command line. */ const char *enum_opt_help; /* A string option with list of values help description. */ int secret_arg; /* hidden option will not appear in -help. */ char * secret_orig; /* hidden option will not appear in -help original value given at command line. */ const char *secret_help; /* hidden option will not appear in -help help description. */ int dependant_arg; /* option that depends on str-opt. */ char * dependant_orig; /* option that depends on str-opt original value given at command line. */ const char *dependant_help; /* option that depends on str-opt help description. */ int help_given ; /* Whether help was given. */ int full_help_given ; /* Whether full-help was given. */ int version_given ; /* Whether version was given. */ int str_opt_given ; /* Whether str-opt was given. */ int my_opt_given ; /* Whether my-opt was given. */ int int_opt_given ; /* Whether int-opt was given. */ int flag_opt_given ; /* Whether flag-opt was given. */ int funct_opt_given ; /* Whether funct-opt was given. */ int long_opt_given ; /* Whether long-opt was given. */ int def_opt_given ; /* Whether def-opt was given. */ int enum_opt_given ; /* Whether enum-opt was given. */ int secret_given ; /* Whether secret was given. */ int dependant_given ; /* Whether dependant was given. */ char **inputs ; /* unamed options */ unsigned inputs_num ; /* unamed options number */ } ; extern const char *gengetopt_args_info_purpose; extern const char *gengetopt_args_info_usage; extern const char *gengetopt_args_info_help[]; extern const char *gengetopt_args_info_full_help[]; int cmdline_parser (int argc, char * const *argv, struct gengetopt_args_info *args_info); int cmdline_parser2 (int argc, char * const *argv, struct gengetopt_args_info *args_info, int override, int initialize, int check_required); int cmdline_parser_file_save(const char *filename, struct gengetopt_args_info *args_info); void cmdline_parser_print_help(void); void cmdline_parser_print_full_help(void); void cmdline_parser_print_version(void); void cmdline_parser_init (struct gengetopt_args_info *args_info); void cmdline_parser_free (struct gengetopt_args_info *args_info); int cmdline_parser_required (struct gengetopt_args_info *args_info, const char *prog_name); extern char *cmdline_parser_enum_opt_values[] ; /* Possible values for enum-opt. */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* CMDLINE1_H */ The `