1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
my_getopt - a command-line argument parser
Copyright 1997-2006, Benjamin Sittler
The author can be reached by sending email to <bsittler@gmail.com>.
The version of my_getopt in this package (1.5) has a BSD-like license;
see the file LICENSE for details. Version 1.0 of my_getopt was similar
to the GPL'ed version of my_getopt included with SMOKE-16 Version 1,
Release 19990717. SMOKE-16 packages are available from:
http://geocities.com/bsittler/#smoke16
OVERVIEW OF THE ARGUMENT PARSER
===============================
The getopt(), getopt_long() and getopt_long_only() functions parse
command line arguments. The argc and argv parameters passed to these
functions correspond to the argument count and argument list passed to
your program's main() function at program start-up. Element 0 of the
argument list conventionally contains the name of your program. Any
remaining arguments starting with "-" (except for "-" or "--" by
themselves) are option arguments, some of include option values. This
family of getopt() functions allows intermixed option and non-option
arguments anywhere in the argument list, except that "--" by itself
causes the remaining elements of the argument list to be treated as
non-option arguments.
[ See the parts of this document labeled "DOCUMENTATION" and
"WHY RE-INVENT THE WHEEL?" for a more information. ]
FILES
=====
The following four files constitute the my_getopt package:
LICENSE - license and warranty information for my_getopt
my_getopt.c - implementation of my getopt replacement
my_getopt.h - interface for my getopt replacement
getopt.h - a header file to make my getopt look like GNU getopt
USAGE
=====
To use my_getopt in your application, include the following line to
your main program source:
#include "getopt.h"
This line should appear after your standard system header files to
avoid conflicting with your system's built-in getopt.
Then compile my_getopt.c into my_getopt.o, and link my_getopt.o into
your application:
$ cc -c my_getopt.c
$ ld -o app app.o ... my_getopt.o
To avoid conflicting with standard library functions, the function
names and global variables used by my_getopt all begin with `my_'. To
ensure compatibility with existing C programs, the `getopt.h' header
file uses the C preprocessor to redefine names like getopt, optarg,
optind, and so forth to my_getopt, my_optarg, my_optind, etc.
SAMPLE PROGRAM
==============
There is also a public-domain sample program:
main.c - main() for a sample program using my_getopt
Makefile - build script for the sample program (called `copy')
To build and test the sample program:
$ make
$ ./copy -help
$ ./copy -version
The sample program bears a slight resemblance to the UNIX `cat'
utility, but can be used rot13-encode streams, and can redirect output
to a file.
DOCUMENTATION
=============
There is not yet any real documentation for my_getopt. For the moment,
use the Linux manual page for getopt. It has its own copyright and
license; view the file `getopt.3' in a text editor for more details.
getopt.3 - the manual page for GNU getopt
getopt.txt - preformatted copy of the manual page for GNU getopt,
for your convenience
WHY RE-INVENT THE WHEEL?
========================
I re-implemented getopt, getopt_long, and getopt_long_only because
there were noticable bugs in several versions of the GNU
implementations, and because the GNU versions aren't always available
on some systems (*BSD, for example.) Other systems don't include any
sort of standard argument parser (Win32 with Microsoft tools, for
example, has no getopt.)
These should do all the expected Unix- and GNU-style argument
parsing, including permution, bunching, long options with single or
double dashes (double dashes are required if you use
my_getopt_long,) and optional arguments for both long and short
options. A word with double dashes all by themselves halts argument
parsing. A required long option argument can be in the same word as
the option name, separated by '=', or in the next word. An optional
long option argument must be in the same word as the option name,
separated by '='.
As with the GNU versions, a '+' prefix to the short option
specification (or the POSIXLY_CORRECT environment variable) disables
permution, a '-' prefix to the short option specification returns 1
for non-options, ':' after a short option indicates a required
argument, and '::' after a short option specification indicates an
optional argument (which must appear in the same word.) If you'd like
to recieve ':' instead of '?' for missing option arguments, prefix the
short option specification with ':'.
The original intent was to re-implement the documented behavior of
the GNU versions, but I have found it necessary to emulate some of
the undocumented behavior as well. Some programs depend on it.
KNOWN BUGS
==========
The GNU versions support POSIX-style -W "name=value" long
options. Currently, my_getopt does not support these, because I
don't have any documentation on them (other than the fact that they
are enabled by "W;" in the short option specification.) As a
temporary workaround, my_getopt treats "W;" in the short option
string identically to "W:".
The GNU versions support internationalized/localized
messages. Currently, my_getopt does not.
There should be re-entrant versions of all these functions so that
multiple threads can parse arguments simultaneously.
|
