ctdb/common/cmdline.h

   1 /*
   2    Command line processing
   3
   4    Copyright (C) Amitay Isaacs  2018
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_CMDLINE_H__
  21 #define __CTDB_CMDLINE_H__
  22
  23 #include <popt.h>
  24 #include <talloc.h>
  25
  26 /**
  27  * @file cmdline.h
  28  *
  29  * @brief Command-line handling with options and commands
  30  *
  31  * This abstraction encapsulates the boiler-plate for parsing options,
  32  * commands and arguments on command-line.
  33  *
  34  * Options handling is done using popt.
  35  */
  36
  37 /**
  38  * @brief Abstract data structure holding command-line configuration
  39  */
  40 struct cmdline_context;
  41
  42 /**
  43  * @brief A command definition structure
  44  *
  45  * @name is the name of the command
  46  * @fn is the implementation of the command
  47  * @msg_help is the help message describing command
  48  * @msg_args is the help message describing arguments
  49  *
  50  * A command name can be a single word or multiple words separated with spaces.
  51  *
  52  * An implementation function should return 0 on success and non-zero value
  53  * on failure.  This value is returned as result in @cmdline_run.
  54  */
  55 struct cmdline_command {
  56         const char *name;
  57         int (*fn)(TALLOC_CTX *mem_ctx,
  58                   int argc,
  59                   const char **argv,
  60                   void *private_data);
  61         const char *msg_help;
  62         const char *msg_args;
  63 };
  64
  65 /**
  66  * @brief convinience macro to define the end of commands list
  67  *
  68  * Here is an example of defining commands list.
  69  *
  70  * struct cmdline_command commands[] = {
  71  *      { "command1", command1_func, "Run command1", NULL },
  72  *      { "command2", command2_func, "Run command2", "<filename>" },
  73  *      CMDLINE_TABLEEND
  74  * };
  75  */
  76 #define CMDLINE_TABLEEND  { NULL, NULL, NULL, NULL }
  77
  78 /**
  79  * @brief Initialize cmdline abstraction
  80  *
  81  * If there are no options, options can be NULL.
  82  *
  83  * Help options (--help, -h) are automatically added to the options.
  84  *
  85  * @param[in] mem_ctx Talloc memory context
  86  * @param[in] prog Program name
  87  * @param[in] options Command-line options
  88  * @param[in] section Name of section grouping specified commands
  89  * @param[in] commands Commands array
  90  * @param[out] result New cmdline context
  91  * @return 0 on success, errno on failure
  92  *
  93  * Freeing cmdline context will free up all the resources.
  94  */
  95 int cmdline_init(TALLOC_CTX *mem_ctx,
  96                  const char *prog,
  97                  struct poptOption *options,
  98                  const char *section,
  99                  struct cmdline_command *commands,
 100                  struct cmdline_context **result);
 101
 102
 103 /**
 104  * @brief Add command line section/commands
 105  *
 106  * @param[in] cmdline Cmdline context
 107  * @param[in] section Name of section grouping specified commands
 108  * @param[in] commands Commands array
 109  * @return 0 on success, errno on failure
 110  */
 111 int cmdline_add(struct cmdline_context *cmdline,
 112                 const char *section,
 113                 struct cmdline_command *commands);
 114
 115 /**
 116  * @brief Parse command line options and commands/arguments
 117  *
 118  * This function parses the arguments to process options and commands.
 119  *
 120  * This function should be passed the arguments to main() and parse_options
 121  * should be set to true.  If cmdline is used for handling second-level
 122  * commands, then parse_options should be set to false.
 123  *
 124  * If argv does not match any command, then ENOENT is returned.
 125  *
 126  * @param[in] cmdline Cmdline context
 127  * @param[in] argc Number of arguments
 128  * @param[in] argv Arguments array
 129  * @param[in] parse_options Whether to parse for options
 130  * @return 0 on success, errno on failure
 131  */
 132 int cmdline_parse(struct cmdline_context *cmdline,
 133                   int argc,
 134                   const char **argv,
 135                   bool parse_options);
 136
 137 /**
 138  * @brief Excecute the function for the command matched by @cmdline_parse
 139  *
 140  * @param[in] cmdline Cmdline context
 141  * @param[in] private_data Private data for implementation function
 142  * @param[out] result Return value from the implementation function
 143  * @return 0 on success, errno on failure
 144  *
 145  * If help options are specified, then detailed help will be printed and
 146  * the return value will be EAGAIN.
 147  */
 148 int cmdline_run(struct cmdline_context *cmdline,
 149                 void *private_data,
 150                 int *result);
 151
 152 /**
 153  * @brief Print usage help message to stdout
 154  *
 155  * @param[in] cmdline Cmdline context
 156  * @param[in] command Command string
 157  *
 158  * If command is NULL, then full help is printed.
 159  * If command is specified, then compact help is printed.
 160  */
 161 void cmdline_usage(struct cmdline_context *cmdline, const char *command);
 162
 163 #endif /* __CTDB_CMDLINE_H__ */