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] commands Commands array
  89  * @param[out] result New cmdline context
  90  * @return 0 on success, errno on failure
  91  *
  92  * Freeing cmdline context will free up all the resources.
  93  */
  94 int cmdline_init(TALLOC_CTX *mem_ctx,
  95                  const char *prog,
  96                  struct poptOption *options,
  97                  struct cmdline_command *commands,
  98                  struct cmdline_context **result);
  99
 100 /**
 101  * @brief Parse command line options and commands/arguments
 102  *
 103  * This function parses the arguments to process options and commands.
 104  *
 105  * This function should be passed the arguments to main() and parse_options
 106  * should be set to true.  If cmdline is used for handling second-level
 107  * commands, then parse_options should be set to false.
 108  *
 109  * If argv does not match any command, then ENOENT is returned.
 110  *
 111  * @param[in] cmdline Cmdline context
 112  * @param[in] argc Number of arguments
 113  * @param[in] argv Arguments array
 114  * @param[in] parse_options Whether to parse for options
 115  * @return 0 on success, errno on failure
 116  */
 117 int cmdline_parse(struct cmdline_context *cmdline,
 118                   int argc,
 119                   const char **argv,
 120                   bool parse_options);
 121
 122 /**
 123  * @brief Excecute the function for the command matched by @cmdline_parse
 124  *
 125  * @param[in] cmdline Cmdline context
 126  * @param[in] private_data Private data for implementation function
 127  * @param[out] result Return value from the implementation function
 128  * @return 0 on success, errno on failure
 129  *
 130  * If help options are specified, then detailed help will be printed and
 131  * the return value will be EAGAIN.
 132  */
 133 int cmdline_run(struct cmdline_context *cmdline,
 134                 void *private_data,
 135                 int *result);
 136
 137 /**
 138  * @brief Print usage help message to stdout
 139  *
 140  * @param[in] cmdline Cmdline context
 141  * @param[in] command Command string
 142  *
 143  * If command is NULL, then full help is printed.
 144  * If command is specified, then compact help is printed.
 145  */
 146 void cmdline_usage(struct cmdline_context *cmdline, const char *command);
 147
 148 #endif /* __CTDB_CMDLINE_H__ */