help.c

   1 /*
   2  * This program is free software; you can redistribute it and/or
   3  * modify it under the terms of the GNU General Public
   4  * License v2 as published by the Free Software Foundation.
   5  *
   6  * This program is distributed in the hope that it will be useful,
   7  * but WITHOUT ANY WARRANTY; without even the implied warranty of
   8  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   9  * General Public License for more details.
  10  *
  11  * You should have received a copy of the GNU General Public
  12  * License along with this program; if not, write to the
  13  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  14  * Boston, MA 021110-1307, USA.
  15  */
  16
  17 #include <stdio.h>
  18 #include <stdlib.h>
  19 #include <string.h>
  20 #include <limits.h>
  21 #include <getopt.h>
  22
  23 #include "commands.h"
  24 #include "utils.h"
  25 #include "help.h"
  26
  27 #define USAGE_SHORT             1U
  28 #define USAGE_LONG              2U
  29 #define USAGE_OPTIONS           4U
  30 #define USAGE_LISTING           8U
  31
  32 static char argv0_buf[ARGV0_BUF_SIZE] = "btrfs";
  33
  34 const char *get_argv0_buf(void)
  35 {
  36         return argv0_buf;
  37 }
  38
  39 void fixup_argv0(char **argv, const char *token)
  40 {
  41         int len = strlen(argv0_buf);
  42
  43         snprintf(argv0_buf + len, sizeof(argv0_buf) - len, " %s", token);
  44         argv[0] = argv0_buf;
  45 }
  46
  47 void set_argv0(char **argv)
  48 {
  49         strncpy(argv0_buf, argv[0], sizeof(argv0_buf));
  50         argv0_buf[sizeof(argv0_buf) - 1] = 0;
  51 }
  52
  53 int check_argc_exact(int nargs, int expected)
  54 {
  55         if (nargs < expected)
  56                 fprintf(stderr, "%s: too few arguments\n", argv0_buf);
  57         if (nargs > expected)
  58                 fprintf(stderr, "%s: too many arguments\n", argv0_buf);
  59
  60         return nargs != expected;
  61 }
  62
  63 int check_argc_min(int nargs, int expected)
  64 {
  65         if (nargs < expected) {
  66                 fprintf(stderr, "%s: too few arguments\n", argv0_buf);
  67                 return 1;
  68         }
  69
  70         return 0;
  71 }
  72
  73 int check_argc_max(int nargs, int expected)
  74 {
  75         if (nargs > expected) {
  76                 fprintf(stderr, "%s: too many arguments\n", argv0_buf);
  77                 return 1;
  78         }
  79
  80         return 0;
  81 }
  82
  83 /*
  84  * Preprocess @argv with getopt_long to reorder options and consume the "--"
  85  * option separator.
  86  * Unknown short and long options are reported, optionally the @usage is printed
  87  * before exit.
  88  */
  89 void clean_args_no_options(int argc, char *argv[], const char * const *usagestr)
  90 {
  91         static const struct option long_options[] = {
  92                 {NULL, 0, NULL, 0}
  93         };
  94
  95         while (1) {
  96                 int c = getopt_long(argc, argv, "", long_options, NULL);
  97
  98                 if (c < 0)
  99                         break;
 100
 101                 switch (c) {
 102                 default:
 103                         if (usagestr)
 104                                 usage(usagestr);
 105                 }
 106         }
 107 }
 108
 109 /*
 110  * Same as clean_args_no_options but pass through arguments that could look
 111  * like short options. Eg. reisze which takes a negative resize argument like
 112  * '-123M' .
 113  *
 114  * This accepts only two forms:
 115  * - "-- option1 option2 ..."
 116  * - "option1 option2 ..."
 117  */
 118 void clean_args_no_options_relaxed(int argc, char *argv[], const char * const *usagestr)
 119 {
 120         if (argc <= 1)
 121                 return;
 122
 123         if (strcmp(argv[1], "--") == 0)
 124                 optind = 2;
 125 }
 126
 127 static int do_usage_one_command(const char * const *usagestr,
 128                                 unsigned int flags, FILE *outf)
 129 {
 130         int pad = 4;
 131
 132         if (!usagestr || !*usagestr)
 133                 return -1;
 134
 135         fprintf(outf, "%s%s", (flags & USAGE_LISTING) ? "    " : "usage: ",
 136                 *usagestr++);
 137
 138         /* a short one-line description (mandatory) */
 139         if ((flags & USAGE_SHORT) == 0)
 140                 return 0;
 141         else if (!*usagestr)
 142                 return -2;
 143         fputc('\n', outf);
 144
 145         if (flags & USAGE_LISTING)
 146                 pad = 8;
 147         else
 148                 fputc('\n', outf);
 149
 150         fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
 151
 152         /* a long (possibly multi-line) description (optional) */
 153         if (!*usagestr || ((flags & USAGE_LONG) == 0))
 154                 return 0;
 155
 156         if (**usagestr)
 157                 fputc('\n', outf);
 158         while (*usagestr && **usagestr)
 159                 fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
 160
 161         /* options (optional) */
 162         if (!*usagestr || ((flags & USAGE_OPTIONS) == 0))
 163                 return 0;
 164
 165         /*
 166          * options (if present) should always (even if there is no long
 167          * description) be prepended with an empty line, skip it
 168          */
 169         usagestr++;
 170
 171         fputc('\n', outf);
 172         while (*usagestr)
 173                 fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
 174
 175         return 0;
 176 }
 177
 178 static int usage_command_internal(const char * const *usagestr,
 179                                   const char *token, int full, int lst,
 180                                   int alias, FILE *outf)
 181 {
 182         unsigned int flags = 0;
 183         int ret;
 184
 185         if (!alias)
 186                 flags |= USAGE_SHORT;
 187         if (full)
 188                 flags |= USAGE_LONG | USAGE_OPTIONS;
 189         if (lst)
 190                 flags |= USAGE_LISTING;
 191
 192         ret = do_usage_one_command(usagestr, flags, outf);
 193         switch (ret) {
 194         case -1:
 195                 fprintf(outf, "No usage for '%s'\n", token);
 196                 break;
 197         case -2:
 198                 fprintf(outf, "No short description for '%s'\n", token);
 199                 break;
 200         }
 201
 202         return ret;
 203 }
 204
 205 static void usage_command_usagestr(const char * const *usagestr,
 206                                    const char *token, int full, int err)
 207 {
 208         FILE *outf = err ? stderr : stdout;
 209         int ret;
 210
 211         ret = usage_command_internal(usagestr, token, full, 0, 0, outf);
 212         if (!ret)
 213                 fputc('\n', outf);
 214 }
 215
 216 void usage_command(const struct cmd_struct *cmd, int full, int err)
 217 {
 218         usage_command_usagestr(cmd->usagestr, cmd->token, full, err);
 219 }
 220
 221 __attribute__((noreturn))
 222 void usage(const char * const *usagestr)
 223 {
 224         usage_command_usagestr(usagestr, NULL, 1, 1);
 225         exit(1);
 226 }
 227
 228 static void usage_command_group_internal(const struct cmd_group *grp, int full,
 229                                          FILE *outf)
 230 {
 231         const struct cmd_struct *cmd = grp->commands;
 232         int do_sep = 0;
 233
 234         for (; cmd->token; cmd++) {
 235                 if (cmd->flags & CMD_HIDDEN)
 236                         continue;
 237
 238                 if (full && cmd != grp->commands)
 239                         fputc('\n', outf);
 240
 241                 if (!cmd->next) {
 242                         if (do_sep) {
 243                                 fputc('\n', outf);
 244                                 do_sep = 0;
 245                         }
 246
 247                         usage_command_internal(cmd->usagestr, cmd->token, full,
 248                                                1, cmd->flags & CMD_ALIAS, outf);
 249                         if (cmd->flags & CMD_ALIAS)
 250                                 putchar('\n');
 251                         continue;
 252                 }
 253
 254                 /* this is an entry point to a nested command group */
 255
 256                 if (!full && cmd != grp->commands)
 257                         fputc('\n', outf);
 258
 259                 usage_command_group_internal(cmd->next, full, outf);
 260
 261                 if (!full)
 262                         do_sep = 1;
 263         }
 264 }
 265
 266 void usage_command_group_short(const struct cmd_group *grp)
 267 {
 268         const char * const *usagestr = grp->usagestr;
 269         FILE *outf = stdout;
 270         const struct cmd_struct *cmd;
 271
 272         if (usagestr && *usagestr) {
 273                 fprintf(outf, "usage: %s\n", *usagestr++);
 274                 while (*usagestr)
 275                         fprintf(outf, "   or: %s\n", *usagestr++);
 276         }
 277
 278         fputc('\n', outf);
 279
 280         fprintf(outf, "Command groups:\n");
 281         for (cmd = grp->commands; cmd->token; cmd++) {
 282                 if (cmd->flags & CMD_HIDDEN)
 283                         continue;
 284
 285                 if (!cmd->next)
 286                         continue;
 287
 288                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->next->infostr);
 289         }
 290
 291         fprintf(outf, "\nCommands:\n");
 292         for (cmd = grp->commands; cmd->token; cmd++) {
 293                 if (cmd->flags & CMD_HIDDEN)
 294                         continue;
 295
 296                 if (cmd->next)
 297                         continue;
 298
 299                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->usagestr[1]);
 300         }
 301
 302         fputc('\n', outf);
 303         fprintf(stderr, "For an overview of a given command use 'btrfs command --help'\n");
 304         fprintf(stderr, "or 'btrfs [command...] --help --full' to print all available options.\n");
 305         fprintf(stderr, "Any command name can be shortened as far as it stays unambiguous,\n");
 306         fprintf(stderr, "however it is recommended to use full command names in scripts.\n");
 307         fprintf(stderr, "All command groups have their manual page named 'btrfs-<group>'.\n");
 308 }
 309
 310 void usage_command_group(const struct cmd_group *grp, int full, int err)
 311 {
 312         const char * const *usagestr = grp->usagestr;
 313         FILE *outf = err ? stderr : stdout;
 314
 315         if (usagestr && *usagestr) {
 316                 fprintf(outf, "usage: %s\n", *usagestr++);
 317                 while (*usagestr)
 318                         fprintf(outf, "   or: %s\n", *usagestr++);
 319         }
 320
 321         fputc('\n', outf);
 322         usage_command_group_internal(grp, full, outf);
 323         fputc('\n', outf);
 324
 325         if (grp->infostr)
 326                 fprintf(outf, "%s\n", grp->infostr);
 327 }
 328
 329 __attribute__((noreturn))
 330 void help_unknown_token(const char *arg, const struct cmd_group *grp)
 331 {
 332         fprintf(stderr, "%s: unknown token '%s'\n", get_argv0_buf(), arg);
 333         usage_command_group(grp, 0, 1);
 334         exit(1);
 335 }
 336
 337 __attribute__((noreturn))
 338 void help_ambiguous_token(const char *arg, const struct cmd_group *grp)
 339 {
 340         const struct cmd_struct *cmd = grp->commands;
 341
 342         fprintf(stderr, "%s: ambiguous token '%s'\n", get_argv0_buf(), arg);
 343         fprintf(stderr, "\nDid you mean one of these ?\n");
 344
 345         for (; cmd->token; cmd++) {
 346                 if (!prefixcmp(cmd->token, arg))
 347                         fprintf(stderr, "\t%s\n", cmd->token);
 348         }
 349
 350         exit(1);
 351 }
 352
 353 void help_command_group(const struct cmd_group *grp, int argc, char **argv)
 354 {
 355         int full = 0;
 356
 357         if (argc > 1) {
 358                 if (!strcmp(argv[1], "--full"))
 359                         full = 1;
 360         }
 361
 362         usage_command_group(grp, full, 0);
 363 }
 364