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

getopts.1p (12882B)


  1. '\" et
  2. .TH GETOPTS "1P" 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. getopts
  12. \(em parse utility options
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. getopts \fIoptstring name \fB[\fIarg\fR...\fB]\fR
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR getopts
  21. utility shall retrieve options and option-arguments from a list of
  22. parameters. It shall support the Utility Syntax Guidelines 3 to 10,
  23. inclusive, described in the Base Definitions volume of POSIX.1\(hy2017,
  24. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  25. .P
  26. Each time it is invoked, the
  27. .IR getopts
  28. utility shall place the value of the next option in the shell variable
  29. specified by the
  30. .IR name
  31. operand and the index of the next argument to be processed in the shell
  32. variable
  33. .IR OPTIND .
  34. Whenever the shell is invoked,
  35. .IR OPTIND
  36. shall be initialized to 1.
  37. .P
  38. When the option requires an option-argument, the
  39. .IR getopts
  40. utility shall place it in the shell variable
  41. .IR OPTARG .
  42. If no option was found, or if the option that was found does not have
  43. an option-argument,
  44. .IR OPTARG
  45. shall be unset.
  46. .P
  47. If an option character not contained in the
  48. .IR optstring
  49. operand is found where an option character is expected, the shell
  50. variable specified by
  51. .IR name
  52. shall be set to the
  53. <question-mark>
  54. (\c
  55. .BR '?' )
  56. character. In this case, if the first character in
  57. .IR optstring
  58. is a
  59. <colon>
  60. (\c
  61. .BR ':' ),
  62. the shell variable
  63. .IR OPTARG
  64. shall be set to the option character found, but no output shall be
  65. written to standard error; otherwise, the shell variable
  66. .IR OPTARG
  67. shall be unset and a diagnostic message shall be written to standard
  68. error. This condition shall be considered to be an error detected in
  69. the way arguments were presented to the invoking application, but shall
  70. not be an error in
  71. .IR getopts
  72. processing.
  73. .P
  74. If an option-argument is missing:
  75. .IP " *" 4
  76. If the first character of
  77. .IR optstring
  78. is a
  79. <colon>,
  80. the shell variable specified by
  81. .IR name
  82. shall be set to the
  83. <colon>
  84. character and the shell variable
  85. .IR OPTARG
  86. shall be set to the option character found.
  87. .IP " *" 4
  88. Otherwise, the shell variable specified by
  89. .IR name
  90. shall be set to the
  91. <question-mark>
  92. character, the shell variable
  93. .IR OPTARG
  94. shall be unset, and a diagnostic message shall be written to standard
  95. error. This condition shall be considered to be an error detected in
  96. the way arguments were presented to the invoking application, but shall
  97. not be an error in
  98. .IR getopts
  99. processing; a diagnostic message shall be written as stated, but the
  100. exit status shall be zero.
  101. .P
  102. When the end of options is encountered, the
  103. .IR getopts
  104. utility shall exit with a return value greater than zero; the shell
  105. variable
  106. .IR OPTIND
  107. shall be set to the index of the first operand, or the value
  108. .BR \(dq$#\(dq +1
  109. if there are no operands; the
  110. .IR name
  111. variable shall be set to the
  112. <question-mark>
  113. character. Any of the following shall identify the end of options:
  114. the first
  115. .BR \(dq--\(dq
  116. argument that is not an option-argument, finding an argument that is
  117. not an option-argument and does not begin with a
  118. .BR '\-' ,
  119. or encountering an error.
  120. .P
  121. The shell variables
  122. .IR OPTIND
  123. and
  124. .IR OPTARG
  125. shall be local to the caller of
  126. .IR getopts
  127. and shall not be exported by default.
  128. .P
  129. The shell variable specified by the
  130. .IR name
  131. operand,
  132. .IR OPTIND ,
  133. and
  134. .IR OPTARG
  135. shall affect the current shell execution environment; see
  136. .IR "Section 2.12" ", " "Shell Execution Environment".
  137. .P
  138. If the application sets
  139. .IR OPTIND
  140. to the value 1, a new set of parameters can be used: either the
  141. current positional parameters or new
  142. .IR arg
  143. values. Any other attempt to invoke
  144. .IR getopts
  145. multiple times in a single shell execution environment with parameters
  146. (positional parameters or
  147. .IR arg
  148. operands) that are not the same in all invocations, or with an
  149. .IR OPTIND
  150. value modified to be a value other than 1, produces unspecified
  151. results.
  152. .SH OPTIONS
  153. None.
  154. .SH OPERANDS
  155. The following operands shall be supported:
  156. .IP "\fIoptstring\fR" 10
  157. A string containing the option characters recognized by the utility
  158. invoking
  159. .IR getopts .
  160. If a character is followed by a
  161. <colon>,
  162. the option shall be expected to have an argument, which should be supplied
  163. as a separate argument. Applications should specify an option character
  164. and its option-argument as separate arguments, but
  165. .IR getopts
  166. shall interpret the characters following an option character requiring
  167. arguments as an argument whether or not this is done. An explicit null
  168. option-argument need not be recognized if it is not supplied as a
  169. separate argument when
  170. .IR getopts
  171. is invoked. (See also the
  172. \fIgetopt\fR()
  173. function defined in the System Interfaces volume of POSIX.1\(hy2017.) The characters
  174. <question-mark>
  175. and
  176. <colon>
  177. shall not be used as option characters by an application. The use of
  178. other option characters that are not alphanumeric produces unspecified
  179. results. If the option-argument is not supplied as a separate argument
  180. from the option character, the value in
  181. .IR OPTARG
  182. shall be stripped of the option character and the
  183. .BR '\-' .
  184. The first character in
  185. .IR optstring
  186. determines how
  187. .IR getopts
  188. behaves if an option character is not known or an option-argument is
  189. missing.
  190. .IP "\fIname\fR" 10
  191. The name of a shell variable that shall be set by the
  192. .IR getopts
  193. utility to the option character that was found.
  194. .P
  195. The
  196. .IR getopts
  197. utility by default shall parse positional parameters passed to the
  198. invoking shell procedure. If
  199. .IR arg s
  200. are given, they shall be parsed instead of the positional parameters.
  201. .SH STDIN
  202. Not used.
  203. .SH "INPUT FILES"
  204. None.
  205. .SH "ENVIRONMENT VARIABLES"
  206. The following environment variables shall affect the execution of
  207. .IR getopts :
  208. .IP "\fILANG\fP" 10
  209. Provide a default value for the internationalization variables that are
  210. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  211. .IR "Section 8.2" ", " "Internationalization Variables"
  212. for the precedence of internationalization variables used to determine
  213. the values of locale categories.)
  214. .IP "\fILC_ALL\fP" 10
  215. If set to a non-empty string value, override the values of all the
  216. other internationalization variables.
  217. .IP "\fILC_CTYPE\fP" 10
  218. Determine the locale for the interpretation of sequences of bytes of
  219. text data as characters (for example, single-byte as opposed to
  220. multi-byte characters in arguments and input files).
  221. .IP "\fILC_MESSAGES\fP" 10
  222. .br
  223. Determine the locale that should be used to affect the format and
  224. contents of diagnostic messages written to standard error.
  225. .IP "\fINLSPATH\fP" 10
  226. Determine the location of message catalogs for the processing of
  227. .IR LC_MESSAGES .
  228. .IP "\fIOPTIND\fP" 10
  229. This variable shall be used by the
  230. .IR getopts
  231. utility as the index of the next argument to be processed.
  232. .SH "ASYNCHRONOUS EVENTS"
  233. Default.
  234. .SH STDOUT
  235. Not used.
  236. .SH STDERR
  237. Whenever an error is detected and the first character in the
  238. .IR optstring
  239. operand is not a
  240. <colon>
  241. (\c
  242. .BR ':' ),
  243. a diagnostic message shall be written to standard error with the
  244. following information in an unspecified format:
  245. .IP " *" 4
  246. The invoking program name shall be identified in the message. The
  247. invoking program name shall be the value of the shell special parameter
  248. 0 (see
  249. .IR "Section 2.5.2" ", " "Special Parameters")
  250. at the time the
  251. .IR getopts
  252. utility is invoked. A name equivalent to:
  253. .RS 4
  254. .sp
  255. .RS 4
  256. .nf
  257. basename "$0"
  258. .fi
  259. .P
  260. .RE
  261. .P
  262. may be used.
  263. .RE
  264. .IP " *" 4
  265. If an option is found that was not specified in
  266. .IR optstring ,
  267. this error is identified and the invalid option character shall be
  268. identified in the message.
  269. .IP " *" 4
  270. If an option requiring an option-argument is found, but an
  271. option-argument is not found, this error shall be identified and the
  272. invalid option character shall be identified in the message.
  273. .SH "OUTPUT FILES"
  274. None.
  275. .SH "EXTENDED DESCRIPTION"
  276. None.
  277. .SH "EXIT STATUS"
  278. The following exit values shall be returned:
  279. .IP "\00" 6
  280. An option, specified or unspecified by
  281. .IR optstring ,
  282. was found.
  283. .IP >0 6
  284. The end of options was encountered or an error occurred.
  285. .SH "CONSEQUENCES OF ERRORS"
  286. Default.
  287. .LP
  288. .IR "The following sections are informative."
  289. .SH "APPLICATION USAGE"
  290. Since
  291. .IR getopts
  292. affects the current shell execution environment, it is generally
  293. provided as a shell regular built-in. If it is called in a subshell or
  294. separate utility execution environment, such as one of the following:
  295. .sp
  296. .RS 4
  297. .nf
  298. (getopts abc value "$@")
  299. nohup getopts ...
  300. find . -exec getopts ... \e;
  301. .fi
  302. .P
  303. .RE
  304. .P
  305. it does not affect the shell variables in the caller's environment.
  306. .P
  307. Note that shell functions share
  308. .IR OPTIND
  309. with the calling shell even though the positional parameters are
  310. changed. If the calling shell and any of its functions uses
  311. .IR getopts
  312. to parse arguments, the results are unspecified.
  313. .SH EXAMPLES
  314. The following example script parses and displays its arguments:
  315. .sp
  316. .RS 4
  317. .nf
  318. aflag=
  319. bflag=
  320. while getopts ab: name
  321. do
  322. case $name in
  323. a) aflag=1;;
  324. b) bflag=1
  325. bval="$OPTARG";;
  326. ?) printf "Usage: %s: [-a] [-b value] args\en" $0
  327. exit 2;;
  328. esac
  329. done
  330. if [ ! -z "$aflag" ]; then
  331. printf "Option -a specified\en"
  332. fi
  333. if [ ! -z "$bflag" ]; then
  334. printf \(aqOption -b "%s" specified\en\(aq "$bval"
  335. fi
  336. shift $(($OPTIND - 1))
  337. printf "Remaining arguments are: %s\en$*"
  338. .fi
  339. .P
  340. .RE
  341. .SH RATIONALE
  342. The
  343. .IR getopts
  344. utility was chosen in preference to the System V
  345. .IR getopt
  346. utility because
  347. .IR getopts
  348. handles option-arguments containing
  349. <blank>
  350. characters.
  351. .P
  352. The
  353. .IR OPTARG
  354. variable is not mentioned in the ENVIRONMENT VARIABLES section because
  355. it does not affect the execution of
  356. .IR getopts ;
  357. it is one of the few ``output-only'' variables used by the standard
  358. utilities.
  359. .P
  360. The
  361. <colon>
  362. is not allowed as an option character because that is not historical
  363. behavior, and it violates the Utility Syntax Guidelines. The
  364. <colon>
  365. is now specified to behave as in the KornShell version of the
  366. .IR getopts
  367. utility; when used as the first character in the
  368. .IR optstring
  369. operand, it disables diagnostics concerning missing option-arguments
  370. and unexpected option characters. This replaces the use of the
  371. .IR OPTERR
  372. variable that was specified in an early proposal.
  373. .P
  374. The formats of the diagnostic messages produced by the
  375. .IR getopts
  376. utility and the
  377. \fIgetopt\fR()
  378. function are not fully specified because implementations with superior
  379. (``friendlier'') formats objected to the formats used by some
  380. historical implementations. The standard developers considered it
  381. important that the information in the messages used be uniform between
  382. .IR getopts
  383. and
  384. \fIgetopt\fR().
  385. Exact duplication of the messages might not be possible, particularly
  386. if a utility is built on another system that has a different
  387. \fIgetopt\fR()
  388. function, but the messages must have specific information included so
  389. that the program name, invalid option character, and type of error can
  390. be distinguished by a user.
  391. .P
  392. Only a rare application program intercepts a
  393. .IR getopts
  394. standard error message and wants to parse it. Therefore,
  395. implementations are free to choose the most usable messages they can
  396. devise. The following formats are used by many historical
  397. implementations:
  398. .sp
  399. .RS 4
  400. .nf
  401. "%s: illegal option -- %c\en", <\fIprogram name\fP>, <\fIoption character\fP>
  402. .P
  403. "%s: option requires an argument -- %c\en", <\fIprogram name\fP>, \e
  404. <\fIoption character\fP>
  405. .fi
  406. .P
  407. .RE
  408. .P
  409. Historical shells with built-in versions of
  410. \fIgetopt\fR()
  411. or
  412. .IR getopts
  413. have used different formats, frequently not even indicating the option
  414. character found in error.
  415. .SH "FUTURE DIRECTIONS"
  416. None.
  417. .SH "SEE ALSO"
  418. .IR "Section 2.5.2" ", " "Special Parameters"
  419. .P
  420. The Base Definitions volume of POSIX.1\(hy2017,
  421. .IR "Chapter 8" ", " "Environment Variables",
  422. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  423. .P
  424. The System Interfaces volume of POSIX.1\(hy2017,
  425. .IR "\fIgetopt\fR\^(\|)"
  426. .\"
  427. .SH COPYRIGHT
  428. Portions of this text are reprinted and reproduced in electronic form
  429. from IEEE Std 1003.1-2017, Standard for Information Technology
  430. -- Portable Operating System Interface (POSIX), The Open Group Base
  431. Specifications Issue 7, 2018 Edition,
  432. Copyright (C) 2018 by the Institute of
  433. Electrical and Electronics Engineers, Inc and The Open Group.
  434. In the event of any discrepancy between this version and the original IEEE and
  435. The Open Group Standard, the original IEEE and The Open Group Standard
  436. is the referee document. The original Standard can be obtained online at
  437. http://www.opengroup.org/unix/online.html .
  438. .PP
  439. Any typographical or formatting errors that appear
  440. in this page are most likely
  441. to have been introduced during the conversion of the source files to
  442. man page format. To report such errors, see
  443. https://www.kernel.org/doc/man-pages/reporting_bugs.html .