Cgetopt man page

CGETOPT_LONG(3) Common Library CGETOPT_LONG(3)

[1mNAME[0m
Cgetopt_long - get long options from command line argument list

[1mSYNOPSIS[0m
[1m#include <Cgetopt.h>[0m

[1mint Cgetopt (int [4m[22margc[24m[1m, char **[4m[22margv[24m[1m, char *[4m[22moptstring[24m[1m)[0m
[1mint Cgetopt_long (int [4m[22margc[24m[1m, char **[4m[22margv[24m[1m, char *[4m[22moptstring[24m[1m, Coptions_t[0m
[1m*[4m[22mlong_options[24m[1m, int *[4m[22mindex[24m[1m)[0m

[1mDESCRIPTION[0m
The [1mCgetopt [22mfunction incrementally parses a command line argument list
[4margv[24m and returns the next known option character. An option character
is known if it has been specified in the string of accepted option
characters [4moptstring[24m.

The [1mCgetopt_long [22mfunction is similar to [1mCgetopt [22mbut it accepts options
in two forms: words and characters. The [1mCgetopt_long [22mfunction provides
a superset of the functionality of [1mCgetopt[22m. The additional functional-
ity is described in the section CGETOPT_LONG.

The option string [4moptstring[24m may contain the following elements: indi-
vidual characters, and characters followed by a colon to indicate an
option argument is to follow. For example, an option string [1mx [22mrecog-
nizes an option [1mx , [22mand an option string [1mx: [22mrecognizes an option [1mx [22mtak-
ing an argument. It does not matter to [1mCgetopt [22mif a following argument
has leading white space.

On return from [1mCgetopt[22m, [1mCoptarg [22mpoints to an option argument, if it is
anticipated, and the variable [1mCoptind [22mcontains the index to the next
[4margv[24m argument for a subsequent call to [1mCgetopt[22m. The variable [1mCoptopt[0m
saves the last known option character returned by [1mCgetopt[22m.

The variables [1mCopterr [22mand [1mCoptind [22mare both initialized to 1. The
[1mCoptind [22mvariable may be set to another value before a set of calls to
[1mCgetopt [22min order to skip over more or less argv entries.

In order to use [1mCgetopt [22mto evaluate multiple sets of arguments, or to
evaluate a single set of arguments multiple times, the variable [1mCoptre-[0m
[1mset [22mmust be set to 1 before the second and each additional set of calls
to [1mCgetopt [22mand the variable [1mCoptind [22mmust be reinitialized.

The [1mCgetopt [22mfunction returns -1 when the argument list is exhausted, or
a non-recognized option is encountered. The interpretation of options
in the argument list may be cancelled by the option [1m-- [22m(double dash)
which causes [1mCgetopt [22mto signal the end of argument processing and
returns -1. When all options have been processed (i.e., up to the first
non-option argument), [1mCgetopt [22mreturns -1. .P [1mCgetopt_long [22mcan be used
in two ways. In the first way, every long option understood by the pro-
gram has a coresponding short option, and the option structure is only
used to translate from long option to short options. When used in this
fashion, [1mCgetopt_long [22mbehaves identically to [1mCgetopt[22m. This is good way
to add long option processing to an existing program with the minimum
of rewriting.

In the second mechanism, a long option set a flag in the [1mCoptions_t[0m
structure passed, or will store a pointer to the command line argument
in the [1mCoptions_t [22mstructure passed to it for options that take argu-
ments. Additionally, the long option's argument may be specified as a
single argument with an equal sign, e.g [1mmyprogram --myoption=somevalue[0m

When a long option is processed the call to [1mCgetopt_long [22mwill return 0.
For this reason, long option processing without shortcuts are not back-
wards compatible with [1mCgetopt.[0m

It is possible to combine these methods, providing for long options
processing with short option equivalents for some options. Less fre-
quently used options would be processed as long options only.

[1mUSAGE OF CGETOPT_LONG[0m
The [1mCgetopt_long [22mcall requires a structure to be initialized describing
the long options. The structure is:

[1mCoptions_t {[0m
char *name;
int has_arg;
int *flag;
int val;
};

The [4mname[24m field should contain the option name without the leading dou-
ble dash.

The [4mhas_arg[24m field should be one of: [1mNO_ARGUMENT [22mif no argument to the
option is expected, [1mREQUIRED_ARGUMENT [22mif an argument to the option is
required or [1mOPTIONAL_ARGUMENT [22mif an argument to the option may be pre-
sented.

If [4mflag[24m is non-NULL, then the integer pointed to by it will set to the
value in the [4mval[24m field. If the [4mflag[24m field is NULL, then the [4mval[24m field
will be returned. Setting [4mflag[24m to NULL and setting [4mval[24m to the corre-
sponding short option will make this function act just like [1mCgetopt[22m.

[1mDIAGNOSTICS[0m
If the [1mCgetopt [22mfunction encounters a character not found in the string
[4moptstring[24m or detects a missing option argument it writes an error mes-
sage to [1mstderr [22mand returns [1m?[22m. Setting [1mCopterr [22mto a zero will disable
these error messages. If [4moptstring[24m has a leading [1m: [22mthen a missing
option argument causes a [1m: [22mto be returned in addition to suppressing
any error messages.

Option arguments are allowed to begin with [1m- [22m; this is reasonable but
reduces the amount of error checking possible.

[1mCGETOPT_LONG EXTENSIONS[0m
The [1mCoptreset [22mvariable was added to make it possible to call the [1mCge-[0m
[1mtopt [22mfunction multiple times. This is an extension to the [1m-p1003.2[0m
specification.

[1mEXAMPLE[0m
#include <Cgetopt.h>
int bflag, ch, fd;

Coptind = 1; /* Required */
Copterr = 1; /* Some stderr output if you want */

bflag = 0;
while ((ch = Cgetopt(argc, argv, "bf:")) != -1)
switch(ch) {
case 'b':
bflag = 1;
break;
case 'f':
if ((fd = open(Coptarg, O_RDONLY, 0)) < 0) {
(void)fprintf(stderr,
"myname: %s: %s0, Coptarg, strerror(errno));
exit(1);
}
break;
case '?':
default:
usage();
}
argc -= Coptind;
argv += Coptind;

[1mLONG EXAMPLE[0m
#include <Cgetopt.h>
int bflag, ch, fd;
int daggerset;

/* options descriptor */
Coptions_t longopts[] =
{
{"buffy", NO_ARGUMENT, NULL, 'b'},
{"floride", REQUIRED_ARGUMENT, NULL, 'f'},
{"daggerset", NO_ARGUMENT, &daggerset, 1},
{NULL, 0, NULL, 0}
};

Coptind = 1; /* Required */
Copterr = 1; /* Some stderr output if you want */

bflag = 0;
while ((ch = Cgetopt_long(argc, argv, "bf:", longopts, NULL)) != -1)
switch(ch) {
case 'b':
bflag = 1;
break;
case 'f':
if ((fd = open(Coptarg, O_RDONLY, 0)) < 0) {
(void)fprintf(stderr,
"myname: %s: %s0, Coptarg, strerror(errno));
exit(1);
}
break;
case 0:
if(daggerset) {
fprintf(stderr,"Buffy will put use her dagger"
"to apply floride to dracula's teeth");
}
break;
case '?':
default:
usage();
}
argc -= Coptind;
argv += Coptind;

[1mHISTORY[0m
The [1mCgetopt [22mfunction appeared in BSD 4.3. The [1mCgetopt_long [22mfunction
first appeared in GNU library. This implementation was imported to Net-
BSD from a Kerberos distribution.

[1mBUGS[0m
The [1mCgetopt [22mfunction was once specified to return [1mEOF [22minstead of -1.
This was changed by [1m-p1003.2-92 [22mto decouple [1mCgetopt [22mfrom <stdio.h>.

A single dash [1m- [22mmay be specified as an character in [4moptstring[24m, however
it should [1mnever [22mhave an argument associated with it. This allows [1mCge-[0m
[1mtopt [22mto be used with programs that expect [1m- [22mas an option flag. This
practice is wrong, and should not be used in any current development.
It is provided for backward compatibility [1monly[22m. By default, a single
dash causes [1mCgetopt [22mto return -1. This is, we believe, compatible with
System V.

It is also possible to handle digits as option letters. This allows
[1mCgetopt [22mto be used with programs that expect a number [1m-3 [22mas an option.
This practice is wrong, and should not be used in any current develop-
ment. It is provided for backward compatibility [1monly[22m. The following
code fragment works in most cases.

int length;
char *p;

Coptind = 1; /* Required */
Copterr = 1; /* Some stderr output if you want */

while ((c = Cgetopt(argc, argv, "0123456789")) != -1)
switch (c) {
case '0': case '1': case '2': case '3': case '4':
case '5': case '6': case '7': case '8': case '9':
p = argv[Coptind - 1];
if (p[0] == '-' && p[1] == ch && !p[2])
length = atoi(++p);
else
length = atoi(argv[Coptind] + 1);
break;
}
}

The [1mOPTIONAL_ARGUMENT [22malways eats the following argument unless the
argument is included via the [1m--option=argument [22mnotation.

[1mAUTHOR[0m
Copyright (c) 1988, 1991, 1993 The Regents of the University of Cali-
fornia. All rights reserved.
Redistribution and use in source and binary forms, with or without mod-
ification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
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 soft-
ware 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
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS “AS IS” AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR-
POSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSI-
NESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LCG $Date: 2010-04-05 09:51:26 +0200 (Mon, 05 Apr 2010)CG$ETOPT_LONG(3)

Info