Document the optional argument support and as well as where we differ from

POSIX and/or GNU.  deraadt@ and jmc@ OK

src/lib/libc/stdlib/getopt.3

@@ -25,7 +25,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$OpenBSD: getopt.3,v 1.27 2003/09/18 09:29:27 jmc Exp $
+.\"	$OpenBSD: getopt.3,v 1.28 2003/09/22 23:47:26 millert Exp $
 .\"
 .Dd December 17, 2002
 .Dt GETOPT 3
@@ -57,9 +57,13 @@ if it has been specified in the string of accepted option characters,
 .Pp
 The option string
 .Fa optstring
-may contain the following elements: individual characters and
-characters followed by a colon to indicate an option argument
-is to follow.
+may contain the following elements: individual characters,
+characters followed by a colon, and characters followed by two colons.
+A character followed by a single colon indicates that an argument
+is to follow the option on the command line.
+Two colons indicates that the argument is optional--this is an
+extension not covered by
+.Px .
 For example, an option string
 .Qq x
 recognizes an option
@@ -147,6 +151,15 @@ is set to the character that caused the error.
 The
 .Fn getopt
 function returns \-1 when the argument list is exhausted.
+.Sh ENVIRONMENT
+.Bl -tag -width POSIXLY_CORRECTXX
+.It Ev POSIXLY_CORRECT
+If set, a leading
+.Sq -
+in
+.Ar optstring
+is ignored.
+.El
 .Sh EXAMPLES
 .Bd -literal -compact
 extern char *optarg;
@@ -204,31 +217,38 @@ this is reasonable but reduces the amount of error checking possible.
 .Xr getsubopt 3
 .Sh STANDARDS
 The
+.Fn getopt
+function implements a superset of the functionality specified by
+.St -p1003.1 .
+.Pp
+The following extensions are supported:
+.Bl -tag -width "xxx"
+.It Li o
+The
 .Va optreset
 variable was added to make it possible to call the
 .Fn getopt
 function multiple times.
-This is an extension to the
-.St -p1003.2
-specification.
-.Sh HISTORY
-The
-.Fn getopt
-function appeared in
-.Bx 4.3 .
-.Sh BUGS
-The
-.Fn getopt
-function was once specified to return
-.Dv EOF
-instead of \-1.
-This was changed by
-.St -p1003.2-92
-to decouple
-.Fn getopt
-from
-.Aq Pa stdio.h .
-.Pp
+.It Li o
+If the first character of
+.Fa optstring
+is a plus sign
+.Pq Ql + ,
+it will be ignored.
+This is for compatibility with
+.Tn GNU
+.Fn getopt .
+.It Li o
+If the first character of
+.Fa optstring
+is a dash
+.Pq Ql - ,
+non-options will be returned as arguments to the option character
+.Ql \e1 .
+This is for compatibility with
+.Tn GNU
+.Fn getopt .
+.It Li o
 A single dash
 .Pq Ql -
 may be specified as a character in
@@ -250,20 +270,51 @@ as the first character in
 .Fa optstring
 to avoid a semantic conflict with
 .Tn GNU
-.Fn getopt ,
-which assigns different meaning to an
-.Fa optstring
-that begins with a
-.Ql - .
+.Fn getopt
+semantics (see above).
 By default, a single dash causes
 .Fn getopt
 to return \-1.
+.El
+.Pp
+Unlike
+.Tn GNU
+.Fn getopt ,
+.Ox
+does not permute the argument vector to allow non-options to be
+interspersed with options on the command line.
+Programs requiring this behavior should use
+.Xr getopt_long 3
+instead.
+Because of this (and unlike
+.Tn GNU ) ,
+the
+.Ox
+.Fn getopt
+supports optional arguments separated by whitespace.
+.Sh HISTORY
+The
+.Fn getopt
+function appeared in
+.Bx 4.3 .
+.Sh BUGS
+The
+.Fn getopt
+function was once specified to return
+.Dv EOF
+instead of \-1.
+This was changed by
+.St -p1003.2-92
+to decouple
+.Fn getopt
+from
+.Aq Pa stdio.h .
 .Pp
-It is also possible to handle digits as option letters.
+It is possible to handle digits as option letters.
 This allows
 .Fn getopt
 to be used with programs that expect a number
-.Pq Dq Li \&-\&3
+.Pq Dq Li \-3
 as an option.
 This practice is wrong, and should not be used in any current development.
 It is provided for backward compatibility