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[])
 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         const char *prefix = "usage: ";
 132         const char *pad_listing = "    ";
 133
 134         if (!usagestr || !*usagestr)
 135                 return -1;
 136
 137         if (flags & USAGE_LISTING)
 138                 prefix = pad_listing;
 139
 140         fputs(prefix, outf);
 141         if (strchr(*usagestr, '\n') == NULL) {
 142                 fputs(*usagestr, outf);
 143         } else {
 144                 const char *c = *usagestr;
 145                 const char *nprefix = "       ";
 146
 147                 if (flags & USAGE_LISTING)
 148                         nprefix = pad_listing;
 149
 150                 for (c = *usagestr; *c; c++) {
 151                         fputc(*c, outf);
 152                         if (*c == '\n')
 153                                 fputs(nprefix, outf);
 154                 }
 155         }
 156         usagestr++;
 157
 158         /* a short one-line description (mandatory) */
 159         if ((flags & USAGE_SHORT) == 0)
 160                 return 0;
 161         else if (!*usagestr)
 162                 return -2;
 163         fputc('\n', outf);
 164
 165         if (flags & USAGE_LISTING)
 166                 pad = 8;
 167         else
 168                 fputc('\n', outf);
 169
 170         fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
 171
 172         /* a long (possibly multi-line) description (optional) */
 173         if (!*usagestr || ((flags & USAGE_LONG) == 0))
 174                 return 0;
 175
 176         if (**usagestr)
 177                 fputc('\n', outf);
 178         while (*usagestr && **usagestr)
 179                 fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
 180
 181         /* options (optional) */
 182         if (!*usagestr || ((flags & USAGE_OPTIONS) == 0))
 183                 return 0;
 184
 185         /*
 186          * options (if present) should always (even if there is no long
 187          * description) be prepended with an empty line, skip it
 188          */
 189         usagestr++;
 190
 191         fputc('\n', outf);
 192         while (*usagestr)
 193                 fprintf(outf, "%*s%s\n", pad, "", *usagestr++);
 194
 195         return 0;
 196 }
 197
 198 static int usage_command_internal(const char * const *usagestr,
 199                                   const char *token, int full, int lst,
 200                                   int alias, FILE *outf)
 201 {
 202         unsigned int flags = 0;
 203         int ret;
 204
 205         if (!alias)
 206                 flags |= USAGE_SHORT;
 207         if (full)
 208                 flags |= USAGE_LONG | USAGE_OPTIONS;
 209         if (lst)
 210                 flags |= USAGE_LISTING;
 211
 212         ret = do_usage_one_command(usagestr, flags, outf);
 213         switch (ret) {
 214         case -1:
 215                 fprintf(outf, "No usage for '%s'\n", token);
 216                 break;
 217         case -2:
 218                 fprintf(outf, "No short description for '%s'\n", token);
 219                 break;
 220         }
 221
 222         return ret;
 223 }
 224
 225 static void usage_command_usagestr(const char * const *usagestr,
 226                                    const char *token, int full, int err)
 227 {
 228         FILE *outf = err ? stderr : stdout;
 229         int ret;
 230
 231         ret = usage_command_internal(usagestr, token, full, 0, 0, outf);
 232         if (!ret)
 233                 fputc('\n', outf);
 234 }
 235
 236 void usage_command(const struct cmd_struct *cmd, int full, int err)
 237 {
 238         usage_command_usagestr(cmd->usagestr, cmd->token, full, err);
 239 }
 240
 241 __attribute__((noreturn))
 242 void usage(const char * const *usagestr)
 243 {
 244         usage_command_usagestr(usagestr, NULL, 1, 1);
 245         exit(1);
 246 }
 247
 248 static void usage_command_group_internal(const struct cmd_group *grp, int full,
 249                                          FILE *outf)
 250 {
 251         const struct cmd_struct *cmd = grp->commands;
 252         int do_sep = 0;
 253
 254         for (; cmd->token; cmd++) {
 255                 if (cmd->flags & CMD_HIDDEN)
 256                         continue;
 257
 258                 if (full && cmd != grp->commands)
 259                         fputc('\n', outf);
 260
 261                 if (!cmd->next) {
 262                         if (do_sep) {
 263                                 fputc('\n', outf);
 264                                 do_sep = 0;
 265                         }
 266
 267                         usage_command_internal(cmd->usagestr, cmd->token, full,
 268                                                1, cmd->flags & CMD_ALIAS, outf);
 269                         if (cmd->flags & CMD_ALIAS)
 270                                 putchar('\n');
 271                         continue;
 272                 }
 273
 274                 /* this is an entry point to a nested command group */
 275
 276                 if (!full && cmd != grp->commands)
 277                         fputc('\n', outf);
 278
 279                 usage_command_group_internal(cmd->next, full, outf);
 280
 281                 if (!full)
 282                         do_sep = 1;
 283         }
 284 }
 285
 286 void usage_command_group_short(const struct cmd_group *grp)
 287 {
 288         const char * const *usagestr = grp->usagestr;
 289         FILE *outf = stdout;
 290         const struct cmd_struct *cmd;
 291
 292         if (usagestr && *usagestr) {
 293                 fprintf(outf, "usage: %s\n", *usagestr++);
 294                 while (*usagestr)
 295                         fprintf(outf, "   or: %s\n", *usagestr++);
 296         }
 297
 298         fputc('\n', outf);
 299
 300         fprintf(outf, "Command groups:\n");
 301         for (cmd = grp->commands; cmd->token; cmd++) {
 302                 if (cmd->flags & CMD_HIDDEN)
 303                         continue;
 304
 305                 if (!cmd->next)
 306                         continue;
 307
 308                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->next->infostr);
 309         }
 310
 311         fprintf(outf, "\nCommands:\n");
 312         for (cmd = grp->commands; cmd->token; cmd++) {
 313                 if (cmd->flags & CMD_HIDDEN)
 314                         continue;
 315
 316                 if (cmd->next)
 317                         continue;
 318
 319                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->usagestr[1]);
 320         }
 321
 322         fputc('\n', outf);
 323         fprintf(stderr, "For an overview of a given command use 'btrfs command --help'\n");
 324         fprintf(stderr, "or 'btrfs [command...] --help --full' to print all available options.\n");
 325         fprintf(stderr, "Any command name can be shortened as far as it stays unambiguous,\n");
 326         fprintf(stderr, "however it is recommended to use full command names in scripts.\n");
 327         fprintf(stderr, "All command groups have their manual page named 'btrfs-<group>'.\n");
 328 }
 329
 330 void usage_command_group(const struct cmd_group *grp, int full, int err)
 331 {
 332         const char * const *usagestr = grp->usagestr;
 333         FILE *outf = err ? stderr : stdout;
 334
 335         if (usagestr && *usagestr) {
 336                 fprintf(outf, "usage: %s\n", *usagestr++);
 337                 while (*usagestr)
 338                         fprintf(outf, "   or: %s\n", *usagestr++);
 339         }
 340
 341         fputc('\n', outf);
 342         usage_command_group_internal(grp, full, outf);
 343         fputc('\n', outf);
 344
 345         if (grp->infostr)
 346                 fprintf(outf, "%s\n", grp->infostr);
 347 }
 348
 349 __attribute__((noreturn))
 350 void help_unknown_token(const char *arg, const struct cmd_group *grp)
 351 {
 352         fprintf(stderr, "%s: unknown token '%s'\n", get_argv0_buf(), arg);
 353         usage_command_group(grp, 0, 1);
 354         exit(1);
 355 }
 356
 357 __attribute__((noreturn))
 358 void help_ambiguous_token(const char *arg, const struct cmd_group *grp)
 359 {
 360         const struct cmd_struct *cmd = grp->commands;
 361
 362         fprintf(stderr, "%s: ambiguous token '%s'\n", get_argv0_buf(), arg);
 363         fprintf(stderr, "\nDid you mean one of these ?\n");
 364
 365         for (; cmd->token; cmd++) {
 366                 if (!prefixcmp(cmd->token, arg))
 367                         fprintf(stderr, "\t%s\n", cmd->token);
 368         }
 369
 370         exit(1);
 371 }
 372
 373 void help_command_group(const struct cmd_group *grp, int argc, char **argv)
 374 {
 375         int full = 0;
 376
 377         if (argc > 1) {
 378                 if (!strcmp(argv[1], "--full"))
 379                         full = 1;
 380         }
 381
 382         usage_command_group(grp, full, 0);
 383 }
 384