1 GETOPT_LONG(3C) Standard C Library Functions GETOPT_LONG(3C)
2
3 NAME
4 getopt_long, getopt_long_only - get long options from command line
5 argument list
6
7 SYNOPSIS
8 #include <getopt.h>
9
10 extern char *optarg;
11 extern int optind;
12 extern int optopt;
13 extern int opterr;
14
15 int
16 getopt_long(int argc, char * const *argv, const char *optstring,
17 const struct option *longopts, int *longindex);
18
19 int
20 getopt_long_only(int argc, char * const *argv, const char *optstring,
21 const struct option *longopts, int *longindex);
22
23 int
24 getopt_long_clip(int argc, char * const *argv, const char *optstring,
25 const struct option *longopts, int *longindex);
26
27 DESCRIPTION
28 The getopt_long() function is similar to getopt(3C) but it accepts
29 options in two forms: words and characters. The getopt_long() function
30 provides a superset of the functionality of getopt(3C). The
31 getopt_long() function can be used in two ways.
32
33 In the first way, every long option understood by the program has a
34 corresponding short option, and the option structure is only used to
35 translate from long options to short options. When used in this fashion,
36 getopt_long() behaves identically to getopt(3C). This is a good way to
37 add long option processing to an existing program with the minimum of
38 rewriting.
39
40 In the second mechanism, a long option sets a flag in the option
41 structure passed, or will store a pointer to the command line argument in
42 the option structure passed to it for options that take arguments.
43 Additionally, the long option's argument may be specified as a single
44 argument with an equal sign, e.g.,
45
46 myprogram --myoption=somevalue
47
48 When a long option is processed, the call to getopt_long() will return 0.
49 For this reason, long option processing without shortcuts is not
50 backwards compatible with getopt(3C).
51
52 It is possible to combine these methods, providing for long options
53 processing with short option equivalents for some options. Less
54 frequently used options would be processed as long options only.
55
56 In getopt_long() and getopt_long_only(), optstring acts similar to
57 optstring in getopt(3C). In addition, optstring can begin with `+' or
58 `-'. If optstring begins with `+', the first non-option terminates
59 option processing. This is equivalent to setting the environment
60 variable POSIXLY_CORRECT. If optstring begins with `-', non-options are
61 treated as options to the argument `\1'.
62
63 If optstring does not begin with `+' and POSIXLY_CORRECT is not set, if
64 `W;' appears in optstring, `-W myoption' is treated the same as
65 `--myoption' and optarg is set to `myoption'.
66
67 In getopt_long_clip(), `+' and `-' are ignored at the beginning of a
68 string.
69
70 The getopt_long(), getopt_long_only(), and getopt_long_clip() functions
71 require a structure to be initialized describing the long options. The
72 structure is:
73
74 struct option {
75 char *name;
76 int has_arg;
77 int *flag;
78 int val;
79 };
80
81 The name field should contain the option name without the leading double
82 dash.
83
84 The has_arg field should be one of:
85
86 no_argument no argument to the option is expected
87 required_argument an argument to the option is required
88 optional_argument an argument to the option may be presented
89
90 If flag is not NULL, then the integer pointed to by it will be set to the
91 value in the val field and optopt will be set to 0. If the flag field is
92 NULL, then the val field will be returned and optopt is set to the value
93 in the val field. Setting flag to NULL and setting val to the
94 corresponding short option will make this function act just like
95 getopt(3C).
96
97 If the longindex field is not NULL, then the integer pointed to by it
98 will be set to the index of the long option relative to longopts.
99
100 The last element of the longopts array has to be filled with zeroes.
101
102 The getopt_long_only() function behaves identically to getopt_long() with
103 the exception that long options may start with `-' in addition to `--'.
104 If an option starting with `-' does not match a long option but does
105 match a single-character option, the single-character option is returned.
106
107 The getopt_long_clip() function is a variation of getopt_long() except
108 that options must also adhere to the Sun CLIP specification.
109 Specifically, the major differences from getopt_long() are:
110
111 o All option arguments are required (optional_argument is treated
112 the same as required_argument).
113
114 o Long options cannot be abbreviated on the command line.
115
116 o Long options must use a double dash (`--').
117
118 o Option processing stops at the first non-option.
119
120 o All long options must have an eqivalent short option (single
121 character) and vice-versa.
122
123 o A leading `+' or `-' in optstring is ignored. optstring is
124 treated as if it began after the leading `+' or `-'.
125
126 On each call to getopt_long(), getopt_long_only(), or getopt_long(),
127 optind is set to the argv index of the next argument to be processed.
128 optind is initialized to 1 prior to the first invocation of
129 getopt_long(), getopt_long_only(), or getopt_long_clip().
130
131 If opterr is set to a non-zero value and optstring does not start with
132 `:', getopt_long(), getopt_long_only(), and getopt_long_clip() will print
133 an error message to stderr when an error or invalid option is
134 encountered.
135
136 RETURN VALUES
137 If the flag field in struct option is NULL, getopt_long() and
138 getopt_long_only() return the value specified in the val field, which is
139 usually just the corresponding short option. If flag is not NULL, these
140 functions return 0 and store val in the location pointed to by flag.
141 These functions return `:' if there was a missing option argument, `?' if
142 the user specified an unknown or ambiguous option, and -1 when the
143 argument list has been exhausted.
144
145 If a long option to getopt_long_clip() is missing its equivalent short
146 option (or vice-versa),-1 is returned on the first call to
147 getopt_long_clip(), and errno is set to EINVAL. If opterr is set to a
148 non-zero value and optstring does not start with `:', an error message
149 will be written to stderr.
150
151 If optstring does not start with `:' and getopt_long(),
152 getopt_long_only(), or getopt_long_clip() return `:' or `?', if opterr is
153 set to a non-zero value, an error message is written to stderr.
154
155 ENVIRONMENT
156 The following environment variables can effect the execution of
157 getopt_long, getopt_long_only, and getopt_long_clip: LANG, LC_ALL,
158 LC_MESSAGES. See environ(5).
159
160 POSIXLY_CORRECT If set, option processing stops when the first non-
161 option is found and a leading `-' or `+' in the
162 optstring is ignored.
163
164 USAGE
165 Similar to getopt(3C), since there is no unambiguous way to detect a
166 missing option-argument except when the option is the last option on the
167 command line, the getopt_long(), getopt_long_only(), and
168 getopt_long_clip() functions cannot fully check for mandatory arguments.
169 For example, the option string `ho:' with an input of `-o -h' will assume
170 that `-h' is the required argument to -o instead of assuming that -o is
171 missing its option-argument.
172
173 Like getopt(3C), grouping options taking or requiring arguments with
174 other options is a violation of the Basic Utility Command syntax standard
175 (see Intro(1)). For example, given the option string `cde:', running:
176
177 cmd -cde ieio
178
179 is incorrect. Current versions of getopt_long, getopt_long_only, and
180 getopt_long_clip accept this, however future versions may not support
181 this. The correct invocation would be:
182
183 cmd -cd -e ieio
184
185 EXAMPLES
186 int bflag, ch, fd;
187 int daggerset;
188
189 /* options descriptor */
190 static struct option longopts[] = {
191 { "buffy", no_argument, NULL, 'b' },
192 { "fluoride", required_argument, NULL, 'f' },
193 { "daggerset", no_argument, &daggerset, 1 },
194 { NULL, 0, NULL, 0 }
195 };
196
197 bflag = 0;
198 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
199 switch (ch) {
200 case 'b':
201 bflag = 1;
202 break;
203 case 'f':
204 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
205 err(1, "unable to open %s", optarg);
206 break;
207 case 0:
208 if (daggerset) {
209 fprintf(stderr,"Buffy will use her dagger to "
210 "apply fluoride to dracula's teeth\n");
211 }
212 break;
213 default:
214 usage();
215 }
216 }
217 argc -= optind;
218 argv += optind;
219
220 ERRORS
221 The getopt_long_clip() function will fail if:
222
223 EINVAL A short option is missing a corresponding long option, or vice-
224 versa.
225
226 There are no errors defined for getopt_long() and getopt_long_only().
227
228 IMPLEMENTATION DIFFERENCES
229 While the illumos implementations of getopt_long and getopt_long_only are
230 broadly compatible with other implementations, the following edge cases
231 have historically been known to vary among implementations:
232
233 o The setting of optopt for long options with flag != NULL in struct
234 option. In illumos, optopt is set to 0 (since val would never be
235 returned).
236
237 o The setting of optarg for long options without an argument that are
238 invoked via `-W' (`W;' in optstring). illumos sets optarg to the
239 option name (the argument of `-W').
240
241 o The handling of `-W' with an argument that is not (a prefix to) a
242 known long option (`W;' in optstring). illumos treats this as an
243 error (unknown option) and returns `?' with optopt set to 0 and
244 optarg set to NULL.
245
246 o illumos may not permute the argument vector at the same points in the
247 calling sequence as other implementations. The aspects normally used
248 by the caller (ordering after -1 is returned, the value of optind
249 relative to current positions) are the same, though. (We often do
250 fewer variable swaps.)
251
252 INTERFACE STABILITY
253 Committed
254
255 MT-LEVEL
256 Unsafe
257
258 SEE ALSO
259 getopt(3C)
260
261 BUGS
262 The argv argument is not really const as its elements may be permuted
263 (unless POSIXLY_CORRECT is set).
264
265 illumos July 17, 2018 illumos