summaryrefslogtreecommitdiff
path: root/lib/libc/stdlib/getopt_long.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc/stdlib/getopt_long.3')
-rw-r--r--lib/libc/stdlib/getopt_long.356
1 files changed, 31 insertions, 25 deletions
diff --git a/lib/libc/stdlib/getopt_long.3 b/lib/libc/stdlib/getopt_long.3
index a2e08a778c6..c5c3dbfc265 100644
--- a/lib/libc/stdlib/getopt_long.3
+++ b/lib/libc/stdlib/getopt_long.3
@@ -1,4 +1,4 @@
-.\" $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
+.\" $NetBSD: getopt_long.3,v 1.9 2002/10/01 17:29:22 wiz Exp $
.\"
.\" Copyright (c) 1988, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -50,15 +50,17 @@ The
.Fn getopt_long
function is similar to
.Xr getopt 3
-but it accepts options in two forms: words and characters. The
+but it accepts options in two forms: words and characters.
+The
.Fn getopt_long
function provides a superset of of the functionality of
.Xr getopt 3 .
.Fn getopt_long
-can be used in two ways. In the first way, every long option understood
-by the program has a corresponding short option, and the option
-structure is only used to translate from long options to short
-options. When used in this fashion,
+can be used in two ways.
+In the first way, every long option understood by the program has a
+corresponding short option, and the option structure is only used to
+translate from long options to short options.
+When used in this fashion,
.Fn getopt_long
behaves identically to
.Xr getopt 3 .
@@ -70,27 +72,28 @@ In the second mechanism, a long option sets a flag in the
structure passed, or will store a pointer to the command line argument
in the
.Fa option
-structure passed to it for options that take arguments. Additionally,
-the long option's argument may be specified as a single argument with
-an equal sign, e.g.
+structure passed to it for options that take arguments.
+Additionally, the long option's argument may be specified as a single
+argument with an equal sign, e.g.
.Bd -literal
myprogram --myoption=somevalue
.Ed
.Pp
When a long option is processed the call to
.Fn getopt_long
-will return 0. For this reason, long option processing without
+will return 0.
+For this reason, long option processing without
shortcuts is not backwards compatible with
.Xr getopt 3 .
.Pp
It is possible to combine these methods, providing for long options
-processing with short option equivalents for some options. Less
-frequently used options would be processed as long options only.
+processing with short option equivalents for some options.
+Less frequently used options would be processed as long options only.
.Pp
The
.Fn getopt_long
-call requires a structure to be initialized describing the long
-options. The structure is:
+call requires a structure to be initialized describing the long options.
+The structure is:
.Bd -literal
struct option {
char *name;
@@ -121,11 +124,13 @@ If
is non-NULL, then the integer pointed to by it will be set to the
value in the
.Fa val
-field. If the
+field.
+If the
.Fa flag
field is NULL, then the
.Fa val
-field will be returned. Setting
+field will be returned.
+Setting
.Fa flag
to NULL and setting
.Fa val
@@ -209,8 +214,8 @@ handling of --a in getopt:
.It Li GNU
parses this as option '-', option 'a'.
.It Li NetBSD
-parses this as '--', and returns -1 (ignoring the a). (Because
-the original getopt does.)
+parses this as '--', and returns -1 (ignoring the a).
+(Because the original getopt does.)
.El
.It Li o
setting of optopt for long options with flag != NULL:
@@ -248,24 +253,25 @@ long option (W; in option string):
returns -W with optarg set to the unknown option.
.It Li NetBSD
treats this as an error (unknown option) and returns '?' with
-optopt set to 0 and optarg set to NULL (as GNU's man page
-documents).
+optopt set to 0 and optarg set to NULL (as GNU's man page documents).
.El
.It Li o
The error messages are different.
.It Li o
NetBSD does not permute the argument vector at the same points in
-the calling sequence as GNU does. The aspects normally used by
-the caller (ordering after -1 is returned, value of optind relative
-to current positions) are the same, though. (We do fewer variable
-swaps.)
+the calling sequence as GNU does.
+The aspects normally used by the caller
+(ordering after -1 is returned, value of optind relative
+to current positions) are the same, though.
+(We do fewer variable swaps.)
.El
.Sh SEE ALSO
.Xr getopt 3
.Sh HISTORY
The
.Fn getopt_long
-function first appeared in GNU libiberty. The first
+function first appeared in GNU libiberty.
+The first
.Nx
implementation appeared in 1.5.
.Sh BUGS