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 2010 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 512 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 */ 223