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 * 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 uint8_t reserved[64]; 130 } subCommandProps_t; 131 132 133 134 #define required_arg required_argument 135 #define no_arg no_argument 136 137 /* 138 * Add short options and long options here 139 * 140 * name -> long option name 141 * has_arg -> required_arg, no_arg 142 * val -> short option character 143 * argDesc -> description of option argument 144 * 145 * Note: This structure may not be used if your CLI has no 146 * options. However, -?, --help and -V, --version will still be supported 147 * as they are standard for every CLI. 148 * 149 * EXAMPLE: 150 * 151 * optionTbl_t options[] = { 152 * {"filename", arg_required, 'f', "out-filename"}, 153 * {NULL, 0, 0} 154 * }; 155 * 156 */ 157 typedef struct _optionTbl { 158 char *name; 159 int has_arg; 160 int val; 161 char *argDesc; 162 } optionTbl_t; 163 164 /* 165 * After tables are set, assign them to this structure 166 * for passing into cmdparse() 167 */ 168 typedef struct _synTables { 169 char *versionString; 170 optionTbl_t *longOptionTbl; 171 subCommandProps_t *subCommandPropsTbl; 172 } synTables_t; 173 174 /* 175 * cmdParse is a parser that checks syntax of the input command against 176 * rules and property tables. 177 * 178 * When syntax is successfully validated, the function associated with the 179 * subcommand is called using the subcommands table functions. 180 * 181 * Syntax for the command is as follows: 182 * 183 * command [options] subcommand [<options>] [<operand ...>] 184 * 185 * 186 * There are two standard short and long options assumed: 187 * -?, --help Provides usage on a command or subcommand 188 * and stops further processing of the arguments 189 * 190 * -V, --version Provides version information on the command 191 * and stops further processing of the arguments 192 * 193 * These options are loaded by this function. 194 * 195 * input: 196 * argc, argv from main 197 * syntax rules tables (synTables_t structure) 198 * callArgs - void * passed by caller to be passed to subcommand function 199 * 200 * output: 201 * funcRet - pointer to int that holds subcommand function return value 202 * 203 * Returns: 204 * 205 * zero on successful syntax parse and function call 206 * 207 * 1 on unsuccessful syntax parse (no function has been called) 208 * This could be due to a version or help call or simply a 209 * general usage call. 210 * 211 * -1 check errno, call failed 212 * 213 */ 214 int cmdParse(int numOperands, char *operands[], synTables_t synTables, 215 void *callerArgs, int *funcRet); 216 217 #ifdef __cplusplus 218 } 219 #endif 220 221 #endif /* _CMDPARSE_H */ 222