LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

getopt.3: Reword discussion of error handling and reporting 

The existing description was hard to understand. Break
it into a bullet list that separates out the details
in a manner that is easier to parse.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2017-01-25 10:26:22 +13:00
parent 797438e749
commit a4746c3978
1 changed files with 30 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
man3/getopt.3
View File

@ -167,24 +167,43 @@ and that care about the ordering of the two.)
The special argument "\-\-" forces an end of option-scanning regardless
of the scanning mode.
.PP
If
While processing the option list,
.BR getopt ()
finds an option character in \fIargv\fP that was not
included in \fIoptstring\fP, or if it detects a missing option argument,
it returns \(aq?\(aq and sets the external variable \fIoptopt\fP to the
actual option character.
can detect two kinds of errors:
(1) an option character that was not specified in
.IR optstring
and (2) a missing option argument
(i.e., an option at the end of the command line without an expected argument).
Such errors are handled and reported as follows:
.IP * 3
By default,
.BR getopt ()
prints an error message on standard error,
places the erroneous option character in
.IR optopt ,
and returns \(aq?\(aq as the function result.
.IP *
If the caller has set the global variable
.IR opterr
to zero, then
.BR getopt ()
does not print an error message.
The caller can determine that there was an error by testing whether
the function return value is \(aq?\(aq.
(By default,
.IR opterr
has a nonzero value.)
.IP *
If the first character
(following any optional \(aq+\(aq or \(aq\-\(aq described above)
of \fIoptstring\fP
is a colon (\(aq:\(aq), then
.BR getopt ()
returns \(aq:\(aq instead of \(aq?\(aq to
likewise does not print an error message.
In addition, it returns \(aq:\(aq instead of \(aq?\(aq to
indicate a missing option argument.
If an error was detected, and
the first character of \fIoptstring\fP is not a colon, and
the external variable \fIopterr\fP is nonzero (which is the default),
.BR getopt ()
prints an error message.
This allows the caller to distinguish the two different types of errors.
.\"
.SS getopt_long() and getopt_long_only()
The
.BR getopt_long ()