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 */ 225