d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

getopt_long(3): Document behavior of leading characters in optstring

Browse Source 
Leading '+', '-', and ':' in optstring have special meaning. We briefly
mention that the first two have special meaning in that we say
POSIXLY_CORRECT turns them off, but we don't actually document their
meaning. Add a paragraph to RETURN VALUES explaining how they control
the treatment of non-option arguments.

A leading ':' has no mention; add a note that it suppresses warnings about
missing arguments.

Reviewed by:	jilles
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D14142
This commit is contained in:
kevans 2018-08-12 00:08:14 +00:00
parent 68da6ee2cf
commit 2f561e90ad
1 changed files with 43 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
lib/libc/stdlib/getopt_long.3
View File

@ -31,7 +31,7 @@
.\" @(#)getopt.3 8.5 (Berkeley) 4/27/95
.\" $FreeBSD$
.\"
.Dd December 25, 2011
.Dd May 2, 2018
.Dt GETOPT_LONG 3
.Os
.Sh NAME
@ -207,12 +207,53 @@ these functions return 0 and store
.Fa val
in the location pointed to by
.Fa flag .
.Pp
These functions return
.Ql \&:
if there was a missing option argument,
if there was a missing option argument and error messages are suppressed,
.Ql \&?
if the user specified an unknown or ambiguous option, and
\-1 when the argument list has been exhausted.
The default behavior when a missing option argument is encountered is to write
an error and return
.Ql \&? .
Specifying
.Ql \&:
in
.Fa optstr
will cause the error message to be suppressed and
.Ql \&:
to be returned instead.
.Pp
In addition to
.Ql \&: ,
a leading
.Ql \&+
or
.Ql \&-
in
.Fa optstr
also has special meaning.
If either of these are specified, they must appear before
.Ql \&: .
.Pp
A leading
.Ql \&+
indicates that processing should be halted at the first non-option argument,
matching the default behavior of
.Xr getopt 3 .
The default behavior without
.Ql \&+
is to permute non-option argments to the end of
.Fa argv .
.Pp
A leading
.Ql \&-
indicates that all non-option arguments should be treated as if they are
arguments to a literal
.Ql \&1
flag (i.e., the function call will return the value 1, rather than the char
literal '1').
.Sh ENVIRONMENT
.Bl -tag -width ".Ev POSIXLY_CORRECT"
.It Ev POSIXLY_CORRECT