usr/src/common/cmdparse/cmdparse.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or http://www.opensolaris.org/os/licensing.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25
  26 #ifndef _CMDPARSE_H
  27 #define _CMDPARSE_H
  28
  29 #ifdef  __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 #include <getopt.h>
  34
  35 #define SUBCOMMAND_BASE  1
  36
  37 /* bit defines for operand macros */
  38 #define OPERAND_SINGLE          0x2
  39 #define OPERAND_MULTIPLE        0x4
  40 #define OPERAND_MANDATORY       0x8
  41 #define OPERAND_OPTIONAL        0x10
  42
  43 /* maximum length of an option argument */
  44 #define MAXOPTARGLEN   256
  45
  46
  47 /* Following are used to express operand requirements */
  48 #define OPERAND_NONE                0x1
  49 #define OPERAND_MANDATORY_SINGLE    (OPERAND_MANDATORY | OPERAND_SINGLE)
  50 #define OPERAND_OPTIONAL_SINGLE     (OPERAND_OPTIONAL | OPERAND_SINGLE)
  51 #define OPERAND_MANDATORY_MULTIPLE  (OPERAND_MANDATORY | OPERAND_MULTIPLE)
  52 #define OPERAND_OPTIONAL_MULTIPLE   (OPERAND_OPTIONAL | OPERAND_MULTIPLE)
  53
  54 /* subcommands must have a single bit on and must have exclusive values */
  55 #define SUBCOMMAND(x)  (SUBCOMMAND_BASE << x)
  56
  57 /*
  58  * This structure is passed into the caller's callback function and
  59  * will contain a list of all options entered and their associated
  60  * option arguments if applicable
  61  */
  62 typedef struct _cmdOptions {
  63         int optval;
  64         char optarg[MAXOPTARGLEN + 1];
  65 } cmdOptions_t;
  66
  67 /*
  68  * subcommand callback function
  69  *
  70  * argc - number of arguments in argv
  71  * argv - operand arguments
  72  * options - options entered on command line
  73  * callData - pointer to caller data to be passed to subcommand function
  74  */
  75 typedef int (*handler_t)(int argc, char *argv[], cmdOptions_t *options,
  76     void *callData);
  77
  78 /*
  79  * list of subcommands and associated properties
  80  *
  81  * name -> subcommand name
  82  * handler -> function to call on successful syntax check
  83  * optionString -> short options that are valid
  84  * required -> Does it require at least one option?
  85  * exclusive -> short options that are required to be exclusively entered
  86  * operand -> Type of operand input. Can be:
  87  *
  88  *              NO_OPERAND
  89  *              OPERAND_MANDATORY_SINGLE
  90  *              OPERAND_OPTIONAL_SINGLE
  91  *              OPERAND_MANDATORY_MULTIPLE
  92  *              OPERAND_OPTIONAL_MULTIPLE
  93  *
  94  * operandDefinition -> char * definition of the operand
  95  *
  96  * The long options table specifies whether an option argument is required.
  97  *
  98  *
  99  * EXAMPLE:
 100  *
 101  * Based on "list-target" entry below:
 102  *
 103  *  "list-target" is expected as the subcommand input
 104  *  listTarget is the function to be called on success
 105  *  "list-target" accepts -i, -s, -t and -l
 106  *  "list-target" requires the option 'i'.
 107  *  "list-target" has no exclusive options
 108  *  "list-target" may have one or more operands
 109  *  "list-target" operand description is "target-name"
 110  *
 111  *
 112  *      optionRules_t optionRules[] = {
 113  *          {"list-target", listTarget, "istl", "i", NULL,
 114  *              OPERAND_OPTIONAL_MULTIPLE, "target-name"},
 115  *          {"modify-target", modifyTarget, "t", "t", NULL,
 116  *              OPERAND_MANDATORY_MULTIPLE, "target-name"},
 117  *          {"enable", enable, NULL, NULL, NULL, NO_OPERAND, NULL},
 118  *          {NULL, 0, 0, NULL, 0, NULL}
 119  *      };
 120  */
 121 typedef struct _subCommandProps {
 122         char *name;
 123         handler_t handler;
 124         char *optionString;
 125         char *required;
 126         char *exclusive;
 127         int operand;
 128         char *operandDefinition;
 129         char *helpText;
 130         uint8_t reserved[60];
 131 } subCommandProps_t;
 132
 133
 134
 135 #define required_arg    required_argument
 136 #define no_arg          no_argument
 137
 138 /*
 139  * Add short options and long options here
 140  *
 141  *  name -> long option name
 142  *  has_arg -> required_arg, no_arg
 143  *  val -> short option character
 144  *  argDesc -> description of option argument
 145  *
 146  * Note: This structure may not be used if your CLI has no
 147  * options. However, -?, --help and -V, --version will still be supported
 148  * as they are standard for every CLI.
 149  *
 150  * EXAMPLE:
 151  *
 152  *      optionTbl_t options[] = {
 153  *          {"filename", arg_required, 'f', "out-filename"},
 154  *          {NULL, 0, 0}
 155  *      };
 156  *
 157  */
 158 typedef struct _optionTbl {
 159         char *name;
 160         int has_arg;
 161         int val;
 162         char *argDesc;
 163 } optionTbl_t;
 164
 165 /*
 166  * After tables are set, assign them to this structure
 167  * for passing into cmdparse()
 168  */
 169 typedef struct _synTables {
 170         char *versionString;
 171         optionTbl_t *longOptionTbl;
 172         subCommandProps_t *subCommandPropsTbl;
 173 } synTables_t;
 174
 175 /*
 176  * cmdParse is a parser that checks syntax of the input command against
 177  * rules and property tables.
 178  *
 179  * When syntax is successfully validated, the function associated with the
 180  * subcommand is called using the subcommands table functions.
 181  *
 182  * Syntax for the command is as follows:
 183  *
 184  *      command [options] subcommand [<options>] [<operand ...>]
 185  *
 186  *
 187  * There are two standard short and long options assumed:
 188  *      -?, --help      Provides usage on a command or subcommand
 189  *                      and stops further processing of the arguments
 190  *
 191  *      -V, --version   Provides version information on the command
 192  *                      and stops further processing of the arguments
 193  *
 194  *      These options are loaded by this function.
 195  *
 196  * input:
 197  *  argc, argv from main
 198  *  syntax rules tables (synTables_t structure)
 199  *  callArgs - void * passed by caller to be passed to subcommand function
 200  *
 201  * output:
 202  *  funcRet - pointer to int that holds subcommand function return value
 203  *
 204  * Returns:
 205  *
 206  *     zero on successful syntax parse and function call
 207  *
 208  *     1 on unsuccessful syntax parse (no function has been called)
 209  *              This could be due to a version or help call or simply a
 210  *              general usage call.
 211  *
 212  *     -1 check errno, call failed
 213  *
 214  */
 215 int cmdParse(int numOperands, char *operands[], synTables_t synTables,
 216     void *callerArgs, int *funcRet);
 217
 218 #ifdef  __cplusplus
 219 }
 220 #endif
 221
 222 #endif  /* _CMDPARSE_H */