Version 3.0
Gopt is a free, open-source ANSI C library, for parsing command line arguments and options according to GNU standards.
Gopt was written by Tom Vajzovic, and is a free-standing alternative to
Argp or
getopt. It is written to minimise and simplify the code required within
a program's main() function dealing with the command line.
Gopt is copyright 2003 and 2004 Tom Vajzovic. Gopt is distributed under the GNU GPL; please read through the legal information before distributing Gopt or using it in your program.
To use Gopt you need gopt.c and gopt.h. A Gopt working example program is also available.
The latest versions of these files, together with text and html versions of this manual are available online at http://gopt.sourceforge.net/ .
In the file which has your main() function, you must include the header file gopt.h. This contains the
function declarations and type definitions that you will use. It must be included before the functions that look at the command line options.
#include "gopt.h"
When you declare your main() function, it must take the command line arguments as its function arguments:
int main(int argc, char *argv[])
Inside your main() function you should declare a void pointer variable (void *), which will be used to point to the
information about the options.
void *options;
When you want to start reading from the options and arguments, you should call the function gopts(). This will return a void pointer
to an area of dynamically allocated memory, which you should store in the variable you have created.
options=gopts("io",&argc,&argv);
The first argument to gopts() is a string of letters (const char*) that are short options which take arguments. Here,
-i and -o take arguments. You do not need to specify which long options may take arguments.
The second and third arguments are the addresses of the variables argc and argv, which contain the command line arguments
received by main().
If the system is unable to allocate enough memory, then, as malloc() does, gopts() returns NULL. Because
treating a null value as a pointer causes undefined behaviour, you should always test if this has happened. It is highly unlikely, because Gopt only
uses a small amount of memory.
if(NULL==options)
/* not enough memory */
The whole thing looks like this:
/* Include your other headers, typedefs, global variables etc, eg: */
#include <stdio.h>
#include <stdlib.h>
/* Include the Gopt header: */
#include "gopt.h"
/* Define your main function: */
int main(int argc, char *argv[]){
/* define all your variables for main, eg: */
int foo;
char bar;
/* define a void pointer to store the options: */
void *options;
/* Read the options from the command line: */
options=gopts("abc",&argc,&argv); /* -a -b and -c take arguments */
if(NULL==options){ /* what to do if there is not enough memory, eg: */
fprintf(stderr,"out of memory");
exit(EXIT_FAILURE);
}
/*
continue with main(). You can now call gopt().
*/
Calling gopts() removes all options and their arguments from the command line variables argc and
argv. This will leave only the non-option arguments. If no non-option arguments were specified, the value of
argc will now be 1, argv[0] will be a string containing the command, and argv[1] will be NULL. If you
want to read from the command line options other than by calling gopt(), you must do so before calling gopts().
Once this is done you can call gopt() to test for an option. The first argument for gopt() is the pointer returned by
gopts().
The second and third arguments to gopt() are a character (const char) and a string (const char*), for the short
and long names of the option you are testing for. If a long option has no short equivalent, or you wish to test for options separately, specify
0 as the second option. Equivalently, if you are not looking for a long option, use NULL for the third argument.
The fourth option to gopt() is a pointer to a constant character pointer (const char**). This character pointer will be
set with the address of the option's argument, if it has one. If you do not want to know the option argument, or you know that there was not one,
specify NULL as the fourth argument.
gopt() returns an enumerated type, gopt_t. This will have the one of the following three constants as its value:
In the first two cases, the value of the fourth argument to gopt() will not be used. If GOPT_PRESENT_WITHARG is returned,
the character pointer pointed to by the fourth argument will have been altered to point to the argument of the option.
The value of GOPT_NOTPRESENT is guaranteed to be zero, so you can simply test for the presence of an option with or without an argument using:
if(gopt(...))
Calling gopt() might look like this:
const char *string;
if(gopt(options,'q',"quiet",NULL)){
printf("-q or --quiet was specified.\n");
}
if(GOPT_PRESENT_WITHARG==gopt(options,'n',"name",&string)){
printf("Your name is %s.\n",string);
}
Once you have finished reading from the command line options, you should release the area of memory that contains the information about them back to the
system. You do this using free(), in the same way that you would with any other dynamically allocated memory:
free(options);
You do not have to have finished reading from the non-option arguments to free this memory.
Because Gopt is a new library, and is not widely distributed, you should distribute a copy of the library with any program that uses it, and link to it statically.
gopt.c should compile with no errors (or warnings/comments) under strict ANSI C. Using gcc with optimisation:
gcc -ansi -pedantic -O -c gopt.c
Note: with other compilers or on other systems than GNU/Linux you may need to link the appropriate standard library functions. gopt.c uses functions from <stdlib.h>, <stdio.h> & <string.h>.
You should use the appropriate rule in your Makefile, or if your are compiling manually, the equivalent options for your compiler.
This creates gopt.o, which you need to link to from you main program. Again, you can add a rule to your Makefile, or use something like:
gcc -lm -O -o /usr/bin/myprogram main.c gopt.o
This example links to the <math.h> function library, uses optimisation, compiles main.c, links Gopt to it, and outputs the complete program to the file /usr/bin/myprogram.
If the preprocessor constant GOPT_PASSMALLOC is defined, gopts() will take a fourth function argument. This argument is
used when there might be more than one implementation of malloc() in use. To be able to control which version of malloc()
is used by gopts(), define this constant before including the gopt.h header file, and then pass the address of the appropriate
malloc() version as the fourth argument:
#define GOPT_PASSMALLOC #include "gopt.h"...int main(int argc, char *argv[]){...options=gopts("io",&argc,&argv,&malloc);
Gopt includes a number of fprintf(stderr,...); statements, which were originally used in combination with obscene language to identify the
source of run-time errors when Gopt was under development. They also serve the dual purpose of making the source code more straightforward to read,
in place of comments. These statements are removed from the Gopt by the preprocessor before it is compiled. To leave them in, define a
constant DEBUG, either by adding #define DEBUG, or using -DDEBUG if your compiler supports it.
The author would love to hear from anyone using Gopt for anything. If you are using Gopt what do you like? What do you want changed? Do you have any suggestions, for the code or documentation? Do you want to translate the Gopt documentation into other languages? If you changed Gopt or used part of it, let me know about your program. If you aren't using Gopt, why don't you like it? This is the first library I've written so feel free to be brutal.
What platforms are you using Gopt on? Under any compiler, do you receive any errors/warnings/comments? Let me know.
Gopt is copyright 2003 and 2004 Tom Vajzovic.
Gopt is free software, you may redistribute and modify it under the terms of version 2 of the GNU General Public License, as published by the Free Software Foundation.
Gopt is distributed in the hope that it will be useful, but without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If you did not, write to the Free Software Foundation, Inc, 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
Note that this library is not distributed under the Library or Lesser GPL, but the full GPL.
In plain English this means that Gopt may not do what it is supposed to, and may have undesirable side effects. You may use it, entirely at your own risk.
The GPL grants you the right to redistribute modified versions or derivatives of this software. The author does not grant you the right to do so using the name "Gopt". You may only redistribute modified versions or derivatives of this software under a different name.
The author requests (but does not require) to be notified about programs using Gopt, and that a comment containing the above URL be included with them.
This manual is copyright 2003 and 2004 Tom Vajzovic.
Permission is granted to copy, distribute and modify this document under the terms of the GNU Free Documentation License, Version 1.2, with no invariant sections, no front-cover texts, and no back-cover texts. A copy of the license is included in the file fdl.txt.
Tom Vajzovic <tom_v (at) users.sourceforge.net> http://sourceforge.net/users/tom_v/