logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

getopt.3p (10296B)


  1. '\" et
  2. .TH GETOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. getopt,
  12. optarg,
  13. opterr,
  14. optind,
  15. optopt
  16. \(em command option parsing
  17. .SH SYNOPSIS
  18. .LP
  19. .nf
  20. #include <unistd.h>
  21. .P
  22. int getopt(int \fIargc\fP, char * const \fIargv\fP[], const char *\fIoptstring\fP);
  23. extern char *optarg;
  24. extern int opterr, optind, optopt;
  25. .fi
  26. .SH DESCRIPTION
  27. The
  28. \fIgetopt\fR()
  29. function is a command-line parser that shall follow Utility Syntax
  30. Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base Definitions volume of POSIX.1\(hy2017,
  31. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  32. .P
  33. The parameters
  34. .IR argc
  35. and
  36. .IR argv
  37. are the argument count and argument array as passed to
  38. \fImain\fR()
  39. (see
  40. \fIexec\fR()).
  41. The argument
  42. .IR optstring
  43. is a string of recognized option characters; if a character is followed
  44. by a
  45. <colon>,
  46. the option takes an argument. All option characters allowed by Utility
  47. Syntax Guideline 3 are allowed in
  48. .IR optstring .
  49. The implementation may accept other characters as an extension.
  50. .P
  51. The variable
  52. .IR optind
  53. is the index of the next element of the
  54. .IR argv [\^]
  55. vector to be processed. It shall be initialized to 1 by the system, and
  56. \fIgetopt\fR()
  57. shall update it when it finishes with each element of
  58. .IR argv [\|].
  59. If the application sets
  60. .IR optind
  61. to zero before calling
  62. \fIgetopt\fR(),
  63. the behavior is unspecified. When an element of
  64. .IR argv [\|]
  65. contains multiple option characters, it is unspecified how
  66. \fIgetopt\fR()
  67. determines which options have already been processed.
  68. .P
  69. The
  70. \fIgetopt\fR()
  71. function shall return the next option character (if one is found) from
  72. .IR argv
  73. that matches a character in
  74. .IR optstring ,
  75. if there is one that matches. If the option takes an argument,
  76. \fIgetopt\fR()
  77. shall set the variable
  78. .IR optarg
  79. to point to the option-argument as follows:
  80. .IP " 1." 4
  81. If the option was the last character in the string pointed to by an
  82. element of
  83. .IR argv ,
  84. then
  85. .IR optarg
  86. shall contain the next element of
  87. .IR argv ,
  88. and
  89. .IR optind
  90. shall be incremented by 2. If the resulting value of
  91. .IR optind
  92. is greater than
  93. .IR argc ,
  94. this indicates a missing option-argument, and
  95. \fIgetopt\fR()
  96. shall return an error indication.
  97. .IP " 2." 4
  98. Otherwise,
  99. .IR optarg
  100. shall point to the string following the option character in that
  101. element of
  102. .IR argv ,
  103. and
  104. .IR optind
  105. shall be incremented by 1.
  106. .P
  107. If, when
  108. \fIgetopt\fR()
  109. is called:
  110. .sp
  111. .RS 4
  112. .nf
  113. \fIargv\fP[optind] \fRis a null pointer\fP
  114. *\fIargv\fP[optind] \fRis not the character\fP \-
  115. \fIargv\fP[optind] \fRpoints to the string\fP "\-"
  116. .fi
  117. .P
  118. .RE
  119. .P
  120. \fIgetopt\fR()
  121. shall return \-1 without changing
  122. .IR optind .
  123. If:
  124. .sp
  125. .RS 4
  126. .nf
  127. \fIargv\fP[optind] \fRpoints to the string\fP "\-\|\-"
  128. .fi
  129. .P
  130. .RE
  131. .P
  132. \fIgetopt\fR()
  133. shall return \-1 after incrementing
  134. .IR optind .
  135. .P
  136. If
  137. \fIgetopt\fR()
  138. encounters an option character that is not contained in
  139. .IR optstring ,
  140. it shall return the
  141. <question-mark>
  142. (\c
  143. .BR '?' )
  144. character. If it detects a missing option-argument, it shall return the
  145. <colon>
  146. character (\c
  147. .BR ':' )
  148. if the first character of
  149. .IR optstring
  150. was a
  151. <colon>,
  152. or a
  153. <question-mark>
  154. character (\c
  155. .BR '?' )
  156. otherwise. In either case,
  157. \fIgetopt\fR()
  158. shall set the variable
  159. .IR optopt
  160. to the option character that caused the error. If the application has
  161. not set the variable
  162. .IR opterr
  163. to 0 and the first character of
  164. .IR optstring
  165. is not a
  166. <colon>,
  167. \fIgetopt\fR()
  168. shall also print a diagnostic message to
  169. .IR stderr
  170. in the format specified for the
  171. .IR getopts
  172. utility, unless the
  173. .IR stderr
  174. stream has wide orientation, in which case the behavior is undefined.
  175. .P
  176. The
  177. \fIgetopt\fR()
  178. function need not be thread-safe.
  179. .SH "RETURN VALUE"
  180. The
  181. \fIgetopt\fR()
  182. function shall return the next option character specified on the command
  183. line.
  184. .P
  185. A
  186. <colon>
  187. (\c
  188. .BR ':' )
  189. shall be returned if
  190. \fIgetopt\fR()
  191. detects a missing argument and the first character of
  192. .IR optstring
  193. was a
  194. <colon>
  195. (\c
  196. .BR ':' ).
  197. .P
  198. A
  199. <question-mark>
  200. (\c
  201. .BR '?' )
  202. shall be returned if
  203. \fIgetopt\fR()
  204. encounters an option character not in
  205. .IR optstring
  206. or detects a missing argument and the first character of
  207. .IR optstring
  208. was not a
  209. <colon>
  210. (\c
  211. .BR ':' ).
  212. .P
  213. Otherwise,
  214. \fIgetopt\fR()
  215. shall return \-1 when all command line options are parsed.
  216. .SH ERRORS
  217. If the application has not set the variable
  218. .IR opterr
  219. to 0, the first character of
  220. .IR optstring
  221. is not a
  222. <colon>,
  223. and a write error occurs while
  224. \fIgetopt\fR()
  225. is printing a diagnostic message to
  226. .IR stderr ,
  227. then the error indicator for
  228. .IR stderr
  229. shall be set; but
  230. \fIgetopt\fR()
  231. shall still succeed and the value of
  232. .IR errno
  233. after
  234. \fIgetopt\fR()
  235. is unspecified.
  236. .LP
  237. .IR "The following sections are informative."
  238. .SH EXAMPLES
  239. .SS "Parsing Command Line Options"
  240. .P
  241. The following code fragment shows how you might process the arguments
  242. for a utility that can take the mutually-exclusive options
  243. .IR a
  244. and
  245. .IR b
  246. and the options
  247. .IR f
  248. and
  249. .IR o ,
  250. both of which require arguments:
  251. .sp
  252. .RS 4
  253. .nf
  254. #include <stdio.h>
  255. #include <stdlib.h>
  256. #include <unistd.h>
  257. .P
  258. int
  259. main(int argc, char *argv[ ])
  260. {
  261. int c;
  262. int bflg = 0, aflg = 0, errflg = 0;
  263. char *ifile;
  264. char *ofile;
  265. . . .
  266. while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
  267. switch(c) {
  268. case \(aqa\(aq:
  269. if (bflg)
  270. errflg++;
  271. else
  272. aflg++;
  273. break;
  274. case \(aqb\(aq:
  275. if (aflg)
  276. errflg++;
  277. else
  278. bflg++;
  279. break;
  280. case \(aqf\(aq:
  281. ifile = optarg;
  282. break;
  283. case \(aqo\(aq:
  284. ofile = optarg;
  285. break;
  286. case \(aq:\(aq: /* -f or -o without operand */
  287. fprintf(stderr,
  288. "Option -%c requires an operand\en", optopt);
  289. errflg++;
  290. break;
  291. case \(aq?\(aq:
  292. fprintf(stderr,
  293. "Unrecognized option: \(aq-%c\(aq\en", optopt);
  294. errflg++;
  295. }
  296. }
  297. if (errflg) {
  298. fprintf(stderr, "usage: . . . ");
  299. exit(2);
  300. }
  301. for ( ; optind < argc; optind++) {
  302. if (access(argv[optind], R_OK)) {
  303. . . .
  304. }
  305. .fi
  306. .P
  307. .RE
  308. .P
  309. This code accepts any of the following as equivalent:
  310. .sp
  311. .RS 4
  312. .nf
  313. cmd -ao arg path path
  314. cmd -a -o arg path path
  315. cmd -o arg -a path path
  316. cmd -a -o arg -- path path
  317. cmd -a -oarg path path
  318. cmd -aoarg path path
  319. .fi
  320. .P
  321. .RE
  322. .SS "Selecting Options from the Command Line"
  323. .P
  324. The following example selects the type of database routines the user
  325. wants to use based on the
  326. .IR Options
  327. argument.
  328. .sp
  329. .RS 4
  330. .nf
  331. #include <unistd.h>
  332. #include <string.h>
  333. \&...
  334. const char *Options = "hdbtl";
  335. \&...
  336. int dbtype, c;
  337. char *st;
  338. \&...
  339. dbtype = 0;
  340. while ((c = getopt(argc, argv, Options)) != -1) {
  341. if ((st = strchr(Options, c)) != NULL) {
  342. dbtype = st - Options;
  343. break;
  344. }
  345. }
  346. .fi
  347. .P
  348. .RE
  349. .SH "APPLICATION USAGE"
  350. The
  351. \fIgetopt\fR()
  352. function is only required to support option characters included in
  353. Utility Syntax Guideline 3. Many historical implementations of
  354. \fIgetopt\fR()
  355. support other characters as options. This is an allowed extension, but
  356. applications that use extensions are not maximally portable. Note that
  357. support for multi-byte option characters is only possible when such
  358. characters can be represented as type
  359. .BR int .
  360. .P
  361. Applications which use wide-character output functions with
  362. .IR stderr
  363. should ensure that any calls to
  364. \fIgetopt\fR()
  365. do not write to
  366. .IR stderr ,
  367. either by setting
  368. .IR opterr
  369. to 0 or by ensuring the first character of
  370. .IR optstring
  371. is always a
  372. <colon>.
  373. .P
  374. While
  375. .IR ferror ( stderr )
  376. may be used to detect failures to write a diagnostic to
  377. .IR stderr
  378. when
  379. \fIgetopt\fR()
  380. returns
  381. .BR '?' ,
  382. the value of
  383. .IR errno
  384. is unspecified in such a condition. Applications desiring more control
  385. over handling write failures should set
  386. .IR opterr
  387. to 0 and independently perform output to
  388. .IR stderr ,
  389. rather than relying on
  390. \fIgetopt\fR()
  391. to do the output.
  392. .SH RATIONALE
  393. The
  394. .IR optopt
  395. variable represents historical practice and allows the application to
  396. obtain the identity of the invalid option.
  397. .P
  398. The description has been written to make it clear that
  399. \fIgetopt\fR(),
  400. like the
  401. .IR getopts
  402. utility, deals with option-arguments whether separated from the option
  403. by
  404. <blank>
  405. characters or not. Note that the requirements on
  406. \fIgetopt\fR()
  407. and
  408. .IR getopts
  409. are more stringent than the Utility Syntax Guidelines.
  410. .P
  411. The
  412. \fIgetopt\fR()
  413. function shall return \-1, rather than EOF, so that
  414. .IR <stdio.h>
  415. is not required.
  416. .P
  417. The special significance of a
  418. <colon>
  419. as the first character of
  420. .IR optstring
  421. makes
  422. \fIgetopt\fR()
  423. consistent with the
  424. .IR getopts
  425. utility. It allows an application to make a distinction between a
  426. missing argument and an incorrect option letter without having to
  427. examine the option letter. It is true that a missing argument can only
  428. be detected in one case, but that is a case that has to be considered.
  429. .SH "FUTURE DIRECTIONS"
  430. None.
  431. .SH "SEE ALSO"
  432. .IR "\fIexec\fR\^"
  433. .P
  434. The Base Definitions volume of POSIX.1\(hy2017,
  435. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  436. .IR "\fB<unistd.h>\fP"
  437. .P
  438. The Shell and Utilities volume of POSIX.1\(hy2017,
  439. .IR "\fIgetopts\fR\^"
  440. .\"
  441. .SH COPYRIGHT
  442. Portions of this text are reprinted and reproduced in electronic form
  443. from IEEE Std 1003.1-2017, Standard for Information Technology
  444. -- Portable Operating System Interface (POSIX), The Open Group Base
  445. Specifications Issue 7, 2018 Edition,
  446. Copyright (C) 2018 by the Institute of
  447. Electrical and Electronics Engineers, Inc and The Open Group.
  448. In the event of any discrepancy between this version and the original IEEE and
  449. The Open Group Standard, the original IEEE and The Open Group Standard
  450. is the referee document. The original Standard can be obtained online at
  451. http://www.opengroup.org/unix/online.html .
  452. .PP
  453. Any typographical or formatting errors that appear
  454. in this page are most likely
  455. to have been introduced during the conversion of the source files to
  456. man page format. To report such errors, see
  457. https://www.kernel.org/doc/man-pages/reporting_bugs.html .