diff options
Diffstat (limited to 'usr/src/common/cmdparse/cmdparse.h')
| -rw-r--r-- | usr/src/common/cmdparse/cmdparse.h | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/usr/src/common/cmdparse/cmdparse.h b/usr/src/common/cmdparse/cmdparse.h new file mode 100644 index 0000000..47dab55 --- /dev/null +++ b/usr/src/common/cmdparse/cmdparse.h @@ -0,0 +1,222 @@ +/* + * CDDL HEADER START + * + * The contents of this file are subject to the terms of the + * Common Development and Distribution License (the "License"). + * You may not use this file except in compliance with the License. + * + * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE + * or http://www.opensolaris.org/os/licensing. + * See the License for the specific language governing permissions + * and limitations under the License. + * + * When distributing Covered Code, include this CDDL HEADER in each + * file and include the License file at usr/src/OPENSOLARIS.LICENSE. + * If applicable, add the following below this CDDL HEADER, with the + * fields enclosed by brackets "[]" replaced with your own identifying + * information: Portions Copyright [yyyy] [name of copyright owner] + * + * CDDL HEADER END + */ +/* + * Copyright 2010 Sun Microsystems, Inc. All rights reserved. + * Use is subject to license terms. + */ + +#ifndef _CMDPARSE_H +#define _CMDPARSE_H + +#ifdef __cplusplus +extern "C" { +#endif + +#include <getopt.h> + +#define SUBCOMMAND_BASE 1 + +/* bit defines for operand macros */ +#define OPERAND_SINGLE 0x2 +#define OPERAND_MULTIPLE 0x4 +#define OPERAND_MANDATORY 0x8 +#define OPERAND_OPTIONAL 0x10 + +/* maximum length of an option argument */ +#define MAXOPTARGLEN 512 + + +/* Following are used to express operand requirements */ +#define OPERAND_NONE 0x1 +#define OPERAND_MANDATORY_SINGLE (OPERAND_MANDATORY | OPERAND_SINGLE) +#define OPERAND_OPTIONAL_SINGLE (OPERAND_OPTIONAL | OPERAND_SINGLE) +#define OPERAND_MANDATORY_MULTIPLE (OPERAND_MANDATORY | OPERAND_MULTIPLE) +#define OPERAND_OPTIONAL_MULTIPLE (OPERAND_OPTIONAL | OPERAND_MULTIPLE) + +/* subcommands must have a single bit on and must have exclusive values */ +#define SUBCOMMAND(x) (SUBCOMMAND_BASE << x) + +/* + * This structure is passed into the caller's callback function and + * will contain a list of all options entered and their associated + * option arguments if applicable + */ +typedef struct _cmdOptions { + int optval; + char optarg[MAXOPTARGLEN + 1]; +} cmdOptions_t; + +/* + * subcommand callback function + * + * argc - number of arguments in argv + * argv - operand arguments + * options - options entered on command line + * callData - pointer to caller data to be passed to subcommand function + */ +typedef int (*handler_t)(int argc, char *argv[], cmdOptions_t *options, + void *callData); + +/* + * list of subcommands and associated properties + * + * name -> subcommand name + * handler -> function to call on successful syntax check + * optionString -> short options that are valid + * required -> Does it require at least one option? + * exclusive -> short options that are required to be exclusively entered + * operand -> Type of operand input. Can be: + * + * NO_OPERAND + * OPERAND_MANDATORY_SINGLE + * OPERAND_OPTIONAL_SINGLE + * OPERAND_MANDATORY_MULTIPLE + * OPERAND_OPTIONAL_MULTIPLE + * + * operandDefinition -> char * definition of the operand + * + * The long options table specifies whether an option argument is required. + * + * + * EXAMPLE: + * + * Based on "list-target" entry below: + * + * "list-target" is expected as the subcommand input + * listTarget is the function to be called on success + * "list-target" accepts -i, -s, -t and -l + * "list-target" requires the option 'i'. + * "list-target" has no exclusive options + * "list-target" may have one or more operands + * "list-target" operand description is "target-name" + * + * + * optionRules_t optionRules[] = { + * {"list-target", listTarget, "istl", "i", NULL, + * OPERAND_OPTIONAL_MULTIPLE, "target-name"}, + * {"modify-target", modifyTarget, "t", "t", NULL, + * OPERAND_MANDATORY_MULTIPLE, "target-name"}, + * {"enable", enable, NULL, NULL, NULL, NO_OPERAND, NULL}, + * {NULL, 0, 0, NULL, 0, NULL} + * }; + */ +typedef struct _subCommandProps { + char *name; + handler_t handler; + char *optionString; + char *required; + char *exclusive; + int operand; + char *operandDefinition; + char *helpText; + uint8_t reserved[60]; +} subCommandProps_t; + + + +#define required_arg required_argument +#define no_arg no_argument + +/* + * Add short options and long options here + * + * name -> long option name + * has_arg -> required_arg, no_arg + * val -> short option character + * argDesc -> description of option argument + * + * Note: This structure may not be used if your CLI has no + * options. However, -?, --help and -V, --version will still be supported + * as they are standard for every CLI. + * + * EXAMPLE: + * + * optionTbl_t options[] = { + * {"filename", arg_required, 'f', "out-filename"}, + * {NULL, 0, 0} + * }; + * + */ +typedef struct _optionTbl { + char *name; + int has_arg; + int val; + char *argDesc; +} optionTbl_t; + +/* + * After tables are set, assign them to this structure + * for passing into cmdparse() + */ +typedef struct _synTables { + char *versionString; + optionTbl_t *longOptionTbl; + subCommandProps_t *subCommandPropsTbl; +} synTables_t; + +/* + * cmdParse is a parser that checks syntax of the input command against + * rules and property tables. + * + * When syntax is successfully validated, the function associated with the + * subcommand is called using the subcommands table functions. + * + * Syntax for the command is as follows: + * + * command [options] subcommand [<options>] [<operand ...>] + * + * + * There are two standard short and long options assumed: + * -?, --help Provides usage on a command or subcommand + * and stops further processing of the arguments + * + * -V, --version Provides version information on the command + * and stops further processing of the arguments + * + * These options are loaded by this function. + * + * input: + * argc, argv from main + * syntax rules tables (synTables_t structure) + * callArgs - void * passed by caller to be passed to subcommand function + * + * output: + * funcRet - pointer to int that holds subcommand function return value + * + * Returns: + * + * zero on successful syntax parse and function call + * + * 1 on unsuccessful syntax parse (no function has been called) + * This could be due to a version or help call or simply a + * general usage call. + * + * -1 check errno, call failed + * + */ +int cmdParse(int numOperands, char *operands[], synTables_t synTables, + void *callerArgs, int *funcRet); + +#ifdef __cplusplus +} +#endif + +#endif /* _CMDPARSE_H */ |