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)