usr/src/cmd/isns/isnsadm/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 2008 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  * value -> subcommand value
  83  * handler -> function to call on successful syntax check
  84  * optionString -> short options that are valid
  85  * required -> Does it require at least one option?
  86  * exclusive -> short options that are required to be exclusively entered
  87  * operand -> Type of operand input. Can be:
  88  *
  89  *              NO_OPERAND
  90  *              OPERAND_MANDATORY_SINGLE
  91  *              OPERAND_OPTIONAL_SINGLE
  92  *              OPERAND_MANDATORY_MULTIPLE
  93  *              OPERAND_OPTIONAL_MULTIPLE
  94  *
  95  * operandDefinition -> char * definition of the operand
  96  *
  97  * The long options table specifies whether an option argument is required.
  98  *
  99  *
 100  * EXAMPLE:
 101  *
 102  * Based on "list-target" entry below:
 103  *
 104  *  "list-target" is expected as the subcommand input
 105  *  LIST-TARGET is the subcommand value
 106  *  listTarget is the function to be called on success
 107  *  LIST_TARGET accepts -i, -s, -t and -l
 108  *  LIST_TARGET requires at least one option
 109  *  LIST_TARGET has no exclusive options
 110  *  LIST_TARGET may have one or more operands
 111  *  LIST_TARGET operand description is "target-name"
 112  *
 113  *
 114  *      optionRules_t optionRules[] = {
 115  *          {"list-target", LIST-TARGET, listTarget, "istl", B_TRUE, NULL,
 116  *              OPERAND_OPTIONAL_MULTIPLE, "target-name"},
 117  *          {"modify-target", MODIFY-TARGET, modifyTarget, "t", B_TRUE, NULL,
 118  *              OPERAND_MANDATORY_MULTIPLE, "target-name"},
 119  *          {"enable", ENABLE, enable, NULL, B_TRUE, NULL, NO_OPERAND, NULL},
 120  *          {NULL, 0, 0, NULL, 0, NULL}
 121  *      };
 122  */
 123 typedef struct _subCommandProps {
 124         char *name;
 125         uint_t value;
 126         handler_t handler;
 127         char *optionString;
 128         boolean_t required;
 129         char *exclusive;
 130         int operand;
 131         char *operandDefinition;
 132         uint8_t reserved[64];
 133 } subCommandProps_t;
 134
 135
 136
 137 #define required_arg    required_argument
 138 #define no_arg          no_argument
 139
 140 /*
 141  * Add short options and long options here
 142  *
 143  *  name -> long option name
 144  *  has_arg -> required_arg, no_arg
 145  *  val -> short option character
 146  *  argDesc -> description of option argument
 147  *
 148  * Note: This structure may not be used if your CLI has no
 149  * options. However, -?, --help and -V, --version will still be supported
 150  * as they are standard for every CLI.
 151  *
 152  * EXAMPLE:
 153  *
 154  *      optionTbl_t options[] = {
 155  *          {"filename", arg_required, 'f', "out-filename"},
 156  *          {NULL, 0, 0}
 157  *      };
 158  *
 159  */
 160 typedef struct _optionTbl {
 161         char *name;
 162         int has_arg;
 163         int val;
 164         char *argDesc;
 165 } optionTbl_t;
 166
 167 /*
 168  * After tables are set, assign them to this structure
 169  * for passing into cmdparse()
 170  */
 171 typedef struct _synTables {
 172         char *versionString;
 173         optionTbl_t *longOptionTbl;
 174         subCommandProps_t *subCommandPropsTbl;
 175 } synTables_t;
 176
 177 /*
 178  * cmdParse is a parser that checks syntax of the input command against
 179  * rules and property tables.
 180  *
 181  * When syntax is successfully validated, the function associated with the
 182  * subcommand is called using the subcommands table functions.
 183  *
 184  * Syntax for the command is as follows:
 185  *
 186  *      command [options] subcommand [<options>] [<operand ...>]
 187  *
 188  *
 189  * There are two standard short and long options assumed:
 190  *      -?, --help      Provides usage on a command or subcommand
 191  *                      and stops further processing of the arguments
 192  *
 193  *      -V, --version   Provides version information on the command
 194  *                      and stops further processing of the arguments
 195  *
 196  *      These options are loaded by this function.
 197  *
 198  * input:
 199  *  argc, argv from main
 200  *  syntax rules tables (synTables_t structure)
 201  *  callArgs - void * passed by caller to be passed to subcommand function
 202  *
 203  * output:
 204  *  funcRet - pointer to int that holds subcommand function return value
 205  *
 206  * Returns:
 207  *
 208  *     zero on successful syntax parse and function call
 209  *
 210  *     1 on unsuccessful syntax parse (no function has been called)
 211  *              This could be due to a version or help call or simply a
 212  *              general usage call.
 213  *
 214  *     -1 check errno, call failed
 215  *
 216  */
 217 int cmdParse(int numOperands, char *operands[], synTables_t synTables,
 218     void *callerArgs, int *funcRet);
 219
 220 #ifdef  __cplusplus
 221 }
 222 #endif
 223
 224 #endif  /* _CMDPARSE_H */