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 void usage(const char * const *usagestr)
 222 {
 223         usage_command_usagestr(usagestr, NULL, 1, 1);
 224         exit(1);
 225 }
 226
 227 static void usage_command_group_internal(const struct cmd_group *grp, int full,
 228                                          FILE *outf)
 229 {
 230         const struct cmd_struct *cmd = grp->commands;
 231         int do_sep = 0;
 232
 233         for (; cmd->token; cmd++) {
 234                 if (cmd->flags & CMD_HIDDEN)
 235                         continue;
 236
 237                 if (full && cmd != grp->commands)
 238                         fputc('\n', outf);
 239
 240                 if (!cmd->next) {
 241                         if (do_sep) {
 242                                 fputc('\n', outf);
 243                                 do_sep = 0;
 244                         }
 245
 246                         usage_command_internal(cmd->usagestr, cmd->token, full,
 247                                                1, cmd->flags & CMD_ALIAS, outf);
 248                         if (cmd->flags & CMD_ALIAS)
 249                                 putchar('\n');
 250                         continue;
 251                 }
 252
 253                 /* this is an entry point to a nested command group */
 254
 255                 if (!full && cmd != grp->commands)
 256                         fputc('\n', outf);
 257
 258                 usage_command_group_internal(cmd->next, full, outf);
 259
 260                 if (!full)
 261                         do_sep = 1;
 262         }
 263 }
 264
 265 void usage_command_group_short(const struct cmd_group *grp)
 266 {
 267         const char * const *usagestr = grp->usagestr;
 268         FILE *outf = stdout;
 269         const struct cmd_struct *cmd;
 270
 271         if (usagestr && *usagestr) {
 272                 fprintf(outf, "usage: %s\n", *usagestr++);
 273                 while (*usagestr)
 274                         fprintf(outf, "   or: %s\n", *usagestr++);
 275         }
 276
 277         fputc('\n', outf);
 278
 279         fprintf(outf, "Command groups:\n");
 280         for (cmd = grp->commands; cmd->token; cmd++) {
 281                 if (cmd->flags & CMD_HIDDEN)
 282                         continue;
 283
 284                 if (!cmd->next)
 285                         continue;
 286
 287                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->next->infostr);
 288         }
 289
 290         fprintf(outf, "\nCommands:\n");
 291         for (cmd = grp->commands; cmd->token; cmd++) {
 292                 if (cmd->flags & CMD_HIDDEN)
 293                         continue;
 294
 295                 if (cmd->next)
 296                         continue;
 297
 298                 fprintf(outf, "  %-16s  %s\n", cmd->token, cmd->usagestr[1]);
 299         }
 300
 301         fputc('\n', outf);
 302         fprintf(stderr, "For an overview of a given command use 'btrfs command --help'\n");
 303         fprintf(stderr, "or 'btrfs [command...] --help --full' to print all available options.\n");
 304         fprintf(stderr, "Any command name can be shortened as far as it stays unambiguous,\n");
 305         fprintf(stderr, "however it is recommended to use full command names in scripts.\n");
 306         fprintf(stderr, "All command groups have their manual page named 'btrfs-<group>'.\n");
 307 }
 308
 309 void usage_command_group(const struct cmd_group *grp, int full, int err)
 310 {
 311         const char * const *usagestr = grp->usagestr;
 312         FILE *outf = err ? stderr : stdout;
 313
 314         if (usagestr && *usagestr) {
 315                 fprintf(outf, "usage: %s\n", *usagestr++);
 316                 while (*usagestr)
 317                         fprintf(outf, "   or: %s\n", *usagestr++);
 318         }
 319
 320         fputc('\n', outf);
 321         usage_command_group_internal(grp, full, outf);
 322         fputc('\n', outf);
 323
 324         if (grp->infostr)
 325                 fprintf(outf, "%s\n", grp->infostr);
 326 }
 327
 328 void help_unknown_token(const char *arg, const struct cmd_group *grp)
 329 {
 330         fprintf(stderr, "%s: unknown token '%s'\n", get_argv0_buf(), arg);
 331         usage_command_group(grp, 0, 1);
 332         exit(1);
 333 }
 334
 335 void help_ambiguous_token(const char *arg, const struct cmd_group *grp)
 336 {
 337         const struct cmd_struct *cmd = grp->commands;
 338
 339         fprintf(stderr, "%s: ambiguous token '%s'\n", get_argv0_buf(), arg);
 340         fprintf(stderr, "\nDid you mean one of these ?\n");
 341
 342         for (; cmd->token; cmd++) {
 343                 if (!prefixcmp(cmd->token, arg))
 344                         fprintf(stderr, "\t%s\n", cmd->token);
 345         }
 346
 347         exit(1);
 348 }
 349
 350 void help_command_group(const struct cmd_group *grp, int argc, char **argv)
 351 {
 352         int full = 0;
 353
 354         if (argc > 1) {
 355                 if (!strcmp(argv[1], "--full"))
 356                         full = 1;
 357         }
 358
 359         usage_command_group(grp, full, 0);
 360 }
 361