Debian Codegraph @

upstream/debian-unstable/man3/getopt_long.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH getopt_long 3 2026-02-14 "Linux man-pages 6.18"
7 .SH NAME
8 getopt_long
9 \- parse command-line options
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #define _GNU_SOURCE
16 .B #include <getopt.h>
17 .P
18 .BI "int getopt_long(int " argc ", char *" argv [],
19 .BI " const char *" optstring ,
20 .BI " const struct option *" longopts ", int *" longindex );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR getopt_long ()
25 function works like
26 .BR getopt (3)
27 except that it also accepts long options, started with two dashes.
28 (If the program accepts only long options, then
29 .I optstring
30 should be specified as an empty string (""), not NULL.)
31 Long option names may be abbreviated if the abbreviation is
32 unique or is an exact match for some defined option.
33 A long option
34 may take a parameter, of the form
35 .B \-\-arg=param
36 or
37 .BR "\-\-arg param" .
38 .P
39 .I longopts
40 is a pointer to the first element of an array of
41 .I struct option
42 declared in
43 .I <getopt.h>
44 as
45 .P
46 .in +4n
47 .EX
48 struct option {
49 const char *name;
50 int has_arg;
51 int *flag;
52 int val;
53 };
54 .EE
55 .in
56 .P
57 The meanings of the different fields are:
58 .TP
59 .I name
60 is the name of the long option.
61 .TP
62 .I has_arg
63 is:
64 .B no_argument
65 (or 0) if the option does not take an argument;
66 .B required_argument
67 (or 1) if the option requires an argument;
68 or
69 .B optional_argument
70 (or 2) if the option takes an optional argument.
71 .TP
72 .I flag
73 specifies how results are returned for a long option.
74 If
75 .I flag
76 is NULL, then
77 .BR getopt_long ()
78 returns
79 .IR val .
80 (For example, the calling program may set
81 .I val
82 to the equivalent short
83 option character.)
84 Otherwise,
85 .BR getopt_long ()
86 returns 0, and
87 .I flag
88 points to a variable which is set to
89 .I val
90 if the option is found,
91 but left unchanged if the option is not found.
92 .TP
93 .I val
94 is the value to return, or to load into the variable pointed
95 to by
96 .IR flag .
97 .P
98 The last element of the array has to be filled with zeros.
99 .P
100 If
101 .I longindex
102 is not NULL, it
103 points to a variable which is set to the index of the long option relative to
104 .IR longopts .
105 .P
106 Its analogue to
107 .BR getopt (3)'s
108 .I optopt
109 is
110 .RI \[lq] "argv[(optind \- 1)]" \[rq].
111 .SH RETURN VALUE
112 See
113 .BR getopt (3).
114 .P
115 .BR getopt_long ()
116 also returns the option
117 character when a short option is recognized.
118 For a long option,
119 it returns
120 .I val
121 if
122 .I flag
123 is NULL, and 0 otherwise.
124 Error and \-1 returns are the same as for
125 .BR getopt (3),
126 plus \[aq]?\[aq] for an
127 ambiguous match or an extraneous parameter.
128 .SH ENVIRONMENT
129 See
130 .BR getopt (3).
131 .SH ATTRIBUTES
132 For an explanation of the terms used in this section, see
133 .BR attributes (7).
134 .TS
135 allbox;
136 lb lb lbx
137 l l l.
138 Interface Attribute Value
139 T{
140 .na
141 .nh
142 .BR getopt_long ()
143 T} Thread safety T{
144 .na
145 .nh
146 MT-Unsafe race:getopt env
147 T}
148 .TE
149 .SH STANDARDS
150 GNU.
151 .SH EXAMPLES
152 The following example program illustrates the use of
153 .BR getopt_long ()
154 with most of its features.
155 .P
156 .\" SRC BEGIN (getopt_long.c)
157 .EX
158 #include <getopt.h>
159 #include <stdio.h>
160 #include <stdlib.h>
161 #include <unistd.h>
162 \&
163 int
164 main(int argc, char *argv[])
165 {
166 int c;
167 int digit_optind = 0;
168 \&
169 for (;;) {
170 int this_option_optind = optind ? optind : 1;
171 int option_index = 0;
172 static struct option long_options[] = {
173 {"add", required_argument, 0, 0 },
174 {"append", no_argument, 0, 0 },
175 {"delete", required_argument, 0, 0 },
176 {"verbose", no_argument, 0, 0 },
177 {"create", required_argument, 0, \[aq]c\[aq]},
178 {"file", required_argument, 0, 0 },
179 {0, 0, 0, 0 }
180 };
181 \&
182 c = getopt_long(argc, argv, "abc:d:012",
183 long_options, &option_index);
184 if (c == \-1)
185 break;
186 \&
187 switch (c) {
188 case 0:
189 printf("option %s", long_options[option_index].name);
190 if (optarg)
191 printf(" with arg %s", optarg);
192 printf("\[rs]n");
193 break;
194 \&
195 case \[aq]0\[aq]:
196 case \[aq]1\[aq]:
197 case \[aq]2\[aq]:
198 if (digit_optind != 0 && digit_optind != this_option_optind)
199 printf("digits occur in two different argv\-elements.\[rs]n");
200 digit_optind = this_option_optind;
201 printf("option %c\[rs]n", c);
202 break;
203 \&
204 case \[aq]a\[aq]:
205 printf("option a\[rs]n");
206 break;
207 \&
208 case \[aq]b\[aq]:
209 printf("option b\[rs]n");
210 break;
211 \&
212 case \[aq]c\[aq]:
213 printf("option c with value \[aq]%s\[aq]\[rs]n", optarg);
214 break;
215 \&
216 case \[aq]d\[aq]:
217 printf("option d with value \[aq]%s\[aq]\[rs]n", optarg);
218 break;
219 \&
220 case \[aq]?\[aq]:
221 break;
222 \&
223 default:
224 printf("?? getopt returned character code 0%o ??\[rs]n", c);
225 }
226 }
227 \&
228 if (optind < argc) {
229 printf("non\-option ARGV\-elements: ");
230 while (optind < argc)
231 printf("%s ", argv[optind++]);
232 printf("\[rs]n");
233 }
234 \&
235 exit(EXIT_SUCCESS);
236 }
237 .EE
238 .\" SRC END
239 .SH SEE ALSO
240 .BR getopt (1),
241 .BR getopt (3),
242 .BR getopt_long_only (3),
243 .BR getsubopt (3)