Libc-498.tar.gz

[apple/libc.git] / stdlib / FreeBSD / getopt_long.3

diff --git a/stdlib/FreeBSD/getopt_long.3 b/stdlib/FreeBSD/getopt_long.3
index 4e7c401982d6e1e36451cee49984f6fe9f38951b..dde7980d5dc678cba6bf4955325ec59ace93c8e7 100644 (file)
--- a/stdlib/FreeBSD/getopt_long.3
+++ b/stdlib/FreeBSD/getopt_long.3
@@ -1,4 +1,5 @@
-.\"    $NetBSD: getopt_long.3,v 1.8 2002/06/03 12:01:43 wiz Exp $
+.\"    $OpenBSD: getopt_long.3,v 1.10 2004/01/06 23:44:28 fgsch Exp $
+.\"    $NetBSD: getopt_long.3,v 1.14 2003/08/07 16:43:40 agc Exp $

 .\"
 .\" Copyright (c) 1988, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
 .\"
 .\" Copyright (c) 1988, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.


@@ -11,11 +12,7 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.

-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors

 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"


@@ -32,22 +29,33 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)getopt.3   8.5 (Berkeley) 4/27/95
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)getopt.3   8.5 (Berkeley) 4/27/95

-.\" $FreeBSD: src/lib/libc/stdlib/getopt_long.3,v 1.3 2002/12/18 12:45:10 ru Exp $
+.\" $FreeBSD: src/lib/libc/stdlib/getopt_long.3,v 1.11 2004/03/06 14:47:49 ache Exp $

 .\"
 .Dd April 1, 2000
 .Dt GETOPT_LONG 3
 .Os
 .Sh NAME
 .\"
 .Dd April 1, 2000
 .Dt GETOPT_LONG 3
 .Os
 .Sh NAME

-.Nm getopt_long
+.Nm getopt_long ,
+.Nm getopt_long_only

 .Nd get long options from command line argument list
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In getopt.h
 .Nd get long options from command line argument list
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In getopt.h

+.Vt extern char *optarg ;
+.Vt extern int optind ;
+.Vt extern int optopt ;
+.Vt extern int opterr ;
+.Vt extern int optreset ;

 .Ft int
 .Fo getopt_long
 .Fa "int argc" "char * const *argv" "const char *optstring"
 .Ft int
 .Fo getopt_long
 .Fa "int argc" "char * const *argv" "const char *optstring"

-.Fa "struct option *long options" "int *index"
+.Fa "const struct option *longopts" "int *longindex"
+.Fc
+.Ft int
+.Fo getopt_long_only
+.Fa "int argc" "char * const *argv" "const char *optstring"
+.Fa "const struct option *longopts" "int *longindex"

 .Fc
 .Sh DESCRIPTION
 The
 .Fc
 .Sh DESCRIPTION
 The


@@ -153,41 +161,87 @@ and setting
 to the corresponding short option will make this function act just
 like
 .Xr getopt 3 .
 to the corresponding short option will make this function act just
 like
 .Xr getopt 3 .

+.Pp
+If the
+.Fa longindex
+field is not
+.Dv NULL ,
+then the integer pointed to by it will be set to the index of the long
+option relative to
+.Fa longopts .
+.Pp
+The last element of the
+.Fa longopts
+array has to be filled with zeroes.
+.Pp
+The
+.Fn getopt_long_only
+function behaves identically to
+.Fn getopt_long
+with the exception that long options may start with
+.Ql -
+in addition to
+.Ql -- .
+If an option starting with
+.Ql -
+does not match a long option but does match a single-character option,
+the single-character option is returned.
+.Sh RETURN VALUES
+If the
+.Fa flag
+field in
+.Li struct option
+is
+.Dv NULL ,
+.Fn getopt_long
+and
+.Fn getopt_long_only
+return the value specified in the
+.Fa val
+field, which is usually just the corresponding short option.
+If
+.Fa flag
+is not
+.Dv NULL ,
+these functions return 0 and store
+.Fa val
+in the location pointed to by
+.Fa flag .
+These functions return
+.Ql \&:
+if there was a missing option argument,
+.Ql \&?
+if the user specified an unknown or ambiguous option, and
+\-1 when the argument list has been exhausted.

 .Sh EXAMPLES
 .Bd -literal -compact
 .Sh EXAMPLES
 .Bd -literal -compact

-extern char *optarg;
-extern int optind;

 int bflag, ch, fd;
 int daggerset;
 
 /* options descriptor */
 static struct option longopts[] = {
 int bflag, ch, fd;
 int daggerset;
 
 /* options descriptor */
 static struct option longopts[] = {

-       { "buffy",      no_argument,            0,              'b' },
-       { "floride",    required_argument,      0,              'f' },
+       { "buffy",      no_argument,            NULL,           'b' },
+       { "fluoride",   required_argument,      NULL,           'f' },

        { "daggerset",  no_argument,            \*[Am]daggerset,        1 },
        { "daggerset",  no_argument,            \*[Am]daggerset,        1 },

-       { 0,            0,                      0,              0 }
+       { NULL,         0,                      NULL,           0 }

 };
 
 bflag = 0;
 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
 };
 
 bflag = 0;
 while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1)

-       switch(ch) {
+       switch (ch) {

        case 'b':
                bflag = 1;
                break;
        case 'f':
        case 'b':
                bflag = 1;
                break;
        case 'f':

-               if ((fd = open(optarg, O_RDONLY, 0)) \*[Lt] 0) {
-                       (void)fprintf(stderr,
-                           "myname: %s: %s\en", optarg, strerror(errno));
-                       exit(1);
-               }
+               if ((fd = open(optarg, O_RDONLY, 0)) == -1)
+                       err(1, "unable to open %s", optarg);

                break;
        case 0:
                break;
        case 0:

-               if(daggerset) {
+               if (daggerset) {

                        fprintf(stderr,"Buffy will use her dagger to "
                        fprintf(stderr,"Buffy will use her dagger to "

-                                      "apply floride to dracula's teeth\en");
+                           "apply fluoride to dracula's teeth\en");

                }
                break;
                }
                break;

-       case '?':

        default:
                usage();
 }
        default:
                usage();
 }


@@ -200,79 +254,102 @@ This section describes differences to the
 implementation
 found in glibc-2.1.3:
 .Bl -bullet
 implementation
 found in glibc-2.1.3:
 .Bl -bullet

-.It
-Handling of
-.Ql -
-as first char of option string in presence of
-environment variable
-.Ev POSIXLY_CORRECT :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-ignores
-.Ev POSIXLY_CORRECT
-and returns non-options as
-arguments to option '\e1'.
-.It Nx
-honors
-.Ev POSIXLY_CORRECT
-and stops at the first non-option.
-.El
-.It
-Handling of
-.Ql ::
-in options string in presence of
-.Ev POSIXLY_CORRECT :
-.Bl -tag -width ".Nx"
-.It Both
-.Tn GNU
-and
-.Nx
-ignore
-.Ev POSIXLY_CORRECT
-here and take
-.Ql ::
-to
-mean the preceding option takes an optional argument.
-.El
-.It
-Return value in case of missing argument if first character
-(after
-.Ql +
-or
-.Ql - )
-in option string is not
-.Ql \&: :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-returns
-.Ql \&?
-.It Nx
-returns
-.Ql \&:
-(since
-.Nx Ns 's
-.Fn getopt
-does).
-.El
-.It
-Handling of
-.Ql --a
-in getopt:
-.Bl -tag -width ".Nx"
-.It Tn GNU
-parses this as option
-.Ql - ,
-option
-.Ql a .
-.It Nx
-parses this as
-.Ql -- ,
-and returns \-1 (ignoring the
-.Ql a ) .
-(Because the original
-.Fn getopt
-does.)
-.El
+.\" .It
+.\" Handling of
+.\" .Ql -
+.\" as first char of option string in presence of
+.\" environment variable
+.\" .Ev POSIXLY_CORRECT :
+.\" .Bl -tag -width ".Bx"
+.\" .It Tn GNU
+.\" ignores
+.\" .Ev POSIXLY_CORRECT
+.\" and returns non-options as
+.\" arguments to option '\e1'.
+.\" .It Bx
+.\" honors
+.\" .Ev POSIXLY_CORRECT
+.\" and stops at the first non-option.
+.\" .El
+.\" .It
+.\" Handling of
+.\" .Ql -
+.\" within the option string (not the first character):
+.\" .Bl -tag -width ".Bx"
+.\" .It Tn GNU
+.\" treats a
+.\" .Ql -
+.\" on the command line as a non-argument.
+.\" .It Bx
+.\" a
+.\" .Ql -
+.\" within the option string matches a
+.\" .Ql -
+.\" (single dash) on the command line.
+.\" This functionality is provided for backward compatibility with
+.\" programs, such as
+.\" .Xr su 1 ,
+.\" that use
+.\" .Ql -
+.\" as an option flag.
+.\" This practice is wrong, and should not be used in any current development.
+.\" .El
+.\" .It
+.\" Handling of
+.\" .Ql ::
+.\" in options string in presence of
+.\" .Ev POSIXLY_CORRECT :
+.\" .Bl -tag -width ".Bx"
+.\" .It Both
+.\" .Tn GNU
+.\" and
+.\" .Bx
+.\" ignore
+.\" .Ev POSIXLY_CORRECT
+.\" here and take
+.\" .Ql ::
+.\" to
+.\" mean the preceding option takes an optional argument.
+.\" .El
+.\" .It
+.\" Return value in case of missing argument if first character
+.\" (after
+.\" .Ql +
+.\" or
+.\" .Ql - )
+.\" in option string is not
+.\" .Ql \&: :
+.\" .Bl -tag -width ".Bx"
+.\" .It Tn GNU
+.\" returns
+.\" .Ql \&?
+.\" .It Bx
+.\" returns
+.\" .Ql \&:
+.\" (since
+.\" .Bx Ns 's
+.\" .Fn getopt
+.\" does).
+.\" .El
+.\" .It
+.\" Handling of
+.\" .Ql --a
+.\" in getopt:
+.\" .Bl -tag -width ".Bx"
+.\" .It Tn GNU
+.\" parses this as option
+.\" .Ql - ,
+.\" option
+.\" .Ql a .
+.\" .It Bx
+.\" parses this as
+.\" .Ql -- ,
+.\" and returns \-1 (ignoring the
+.\" .Ql a ) .
+.\" (Because the original
+.\" .Fn getopt
+.\" does.)
+.\" .El

 .It
 Setting of
 .Va optopt
 .It
 Setting of
 .Va optopt


@@ -280,61 +357,51 @@ for long options with
 .Va flag
 !=
 .Dv NULL :
 .Va flag
 !=
 .Dv NULL :

-.Bl -tag -width ".Nx"
+.Bl -tag -width ".Bx"

 .It Tn GNU
 sets
 .Va optopt
 to
 .Va val .
 .It Tn GNU
 sets
 .Va optopt
 to
 .Va val .

-.It Nx
+.It Bx

 sets
 .Va optopt
 to 0 (since
 .Va val
 would never be returned).
 .El
 sets
 .Va optopt
 to 0 (since
 .Va val
 would never be returned).
 .El

-.It
-Handling of
-.Ql -W
-with
-.Ql W ;
-in option string in
-.Fn getopt
-(not
-.Fn getopt_long ) :
-.Bl -tag -width ".Nx"
-.It Tn GNU
-causes a segfault.
-.It Nx
-returns \-1, with
-.Va optind
-pointing past the argument of
-.Ql -W
-(as if
-.Ql "-W arg"
-were
-.Ql --arg ,
-and thus
-.Ql --
-had been found).
-.\" How should we treat W; in the option string when called via
-.\" getopt?  Ignore the ';' or treat it as a ':'? Issue a warning?
-.El
+.\" .It
+.\" Handling of
+.\" .Ql -W
+.\" with
+.\" .Ql W;
+.\" in option string in
+.\" .Fn getopt
+.\" (not
+.\" .Fn getopt_long ) :
+.\" .Bl -tag -width ".Bx"
+.\" .It Tn GNU
+.\" causes a segfault.
+.\" .It Bx
+.\" no special handling is done;
+.\" .Ql W;
+.\" is interpreted as two separate options, neither of which take an argument.
+.\" .El

 .It
 Setting of
 .Va optarg
 for long options without an argument that are
 invoked via
 .Ql -W
 .It
 Setting of
 .Va optarg
 for long options without an argument that are
 invoked via
 .Ql -W

-.Ql ( W ;
+.Ql ( W;

 in option string):
 in option string):

-.Bl -tag -width ".Nx"
+.Bl -tag -width ".Bx"

 .It Tn GNU
 sets
 .Va optarg
 to the option name (the argument of
 .Ql -W ) .
 .It Tn GNU
 sets
 .Va optarg
 to the option name (the argument of
 .Ql -W ) .

-.It Nx
+.It Bx

 sets
 .Va optarg
 to
 sets
 .Va optarg
 to


@@ -346,16 +413,16 @@ Handling of
 .Ql -W
 with an argument that is not (a prefix to) a known
 long option
 .Ql -W
 with an argument that is not (a prefix to) a known
 long option

-.Ql ( W ;
+.Ql ( W;

 in option string):
 in option string):

-.Bl -tag -width ".Nx"
+.Bl -tag -width ".Bx"

 .It Tn GNU
 returns
 .Ql -W
 with
 .Va optarg
 set to the unknown option.
 .It Tn GNU
 returns
 .Ql -W
 with
 .Va optarg
 set to the unknown option.

-.It Nx
+.It Bx

 treats this as an error (unknown option) and returns
 .Ql \&?
 with
 treats this as an error (unknown option) and returns
 .Ql \&?
 with


@@ -368,10 +435,10 @@ set to
 .Tn GNU Ns 's
 man page documents).
 .El
 .Tn GNU Ns 's
 man page documents).
 .El

+.\" .It
+.\" The error messages are different.

 .It
 .It

-The error messages are different.
-.It
-.Nx
+.Bx

 does not permute the argument vector at the same points in
 the calling sequence as
 .Tn GNU
 does not permute the argument vector at the same points in
 the calling sequence as
 .Tn GNU


@@ -383,18 +450,57 @@ relative
 to current positions) are the same, though.
 (We do fewer variable swaps.)
 .El
 to current positions) are the same, though.
 (We do fewer variable swaps.)
 .El

+.Sh ENVIRONMENT
+.Bl -tag -width POSIXLY_CORRECT
+.It Ev POSIXLY_CORRECT
+If set, option processing stops when the first non-option is found and
+a leading
+.Ql -
+or
+.Ql +
+in the
+.Ar optstring
+is ignored.
+.El

 .Sh SEE ALSO
 .Xr getopt 3
 .Sh HISTORY
 The
 .Fn getopt_long
 .Sh SEE ALSO
 .Xr getopt 3
 .Sh HISTORY
 The
 .Fn getopt_long

-function first appeared in
+and
+.Fn getopt_long_only
+functions first appeared in

 .Tn GNU
 libiberty.
 The first
 .Tn GNU
 libiberty.
 The first

-.Nx
-implementation appeared in 1.5.
+.Bx
+implementation of
+.Fn getopt_long
+appeared in
+.Nx 1.5 ,
+the first
+.Bx
+implementation of
+.Fn getopt_long_only
+in
+.Ox 3.3 .
+.Fx
+first included
+.Fn getopt_long
+in
+.Fx 5.0 ,
+.Fn getopt_long_only
+in
+.Fx 5.2 .

 .Sh BUGS
 .Sh BUGS

+The
+.Ar argv
+argument is not really
+.Dv const
+as its elements may be permuted (unless
+.Ev POSIXLY_CORRECT
+is set).
+.Pp

 The implementation can completely replace
 .Xr getopt 3 ,
 but right now we are using separate code.
 The implementation can completely replace
 .Xr getopt 3 ,
 but right now we are using separate code.