src/tool_help.c - master - niceSOFT/curl

src/tool_help.c
412 строк13 KB
Daniel Stenberg
curl: help category cleanups
30 июл 2026, 17:17
30 июл 2026, 17:175eb2f07
/***************************************************************************
 *                                  _   _ ____  _
 *  Project                     ___| | | |  _ \| |
 *                             / __| | | | |_) | |
 *                            | (__| |_| |  _ <| |___
 *                             \___|\___/|_| \_\_____|
 *
 * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution. The terms
 * are also available at https://curl.se/docs/copyright.html.
 *
 * You may opt to use, copy, modify, merge, publish, distribute and/or sell
 * copies of the Software, and permit persons to whom the Software is
 * furnished to do so, under the terms of the COPYING file.
 *
 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
 * KIND, either express or implied.
 *
 * SPDX-License-Identifier: curl
 *
 ***************************************************************************/
#include "tool_setup.h"

#include "tool_help.h"
#include "tool_libinfo.h"
#include "tool_util.h"
#include "tool_version.h"
#include "tool_hugehelp.h"
#include "tool_getparam.h"
#include "tool_cfgable.h"
#include "terminal.h"

struct category_descriptors {
  const char *opt;
  const char *desc;
  unsigned int category;
};

static const struct category_descriptors categories[] = {
  /* important is left out because it is the default help page */
  { "auth", "Authentication methods", CURLHELP_AUTH },
  { "connection", "Manage connections", CURLHELP_CONNECTION },
  { "curl", "The command line tool itself", CURLHELP_CURL },
  { "deprecated", "Legacy", CURLHELP_DEPRECATED },
  { "dns", "Names and resolving", CURLHELP_DNS },
  { "file", "FILE protocol", CURLHELP_FILE },
  { "ftp", "FTP protocol", CURLHELP_FTP },
  { "global", "Global options", CURLHELP_GLOBAL },
  { "http", "HTTP and HTTPS protocol", CURLHELP_HTTP },
  { "imap", "IMAP protocol", CURLHELP_IMAP },
  { "ldap", "LDAP protocol", CURLHELP_LDAP },
  { "mqtt", "MQTT protocol", CURLHELP_MQTT },
  { "output", "File system output", CURLHELP_OUTPUT },
  { "pop3", "POP3 protocol", CURLHELP_POP3 },
  { "post", "HTTP POST specific", CURLHELP_POST },
  { "proxy", "Options for proxies", CURLHELP_PROXY },
  { "scp", "SCP protocol", CURLHELP_SCP },
  { "sftp", "SFTP protocol", CURLHELP_SFTP },
  { "smtp", "SMTP protocol", CURLHELP_SMTP },
  { "ssh", "SSH protocol", CURLHELP_SSH },
  { "telnet", "TELNET protocol", CURLHELP_TELNET },
  { "tftp", "TFTP protocol", CURLHELP_TFTP },
  { "timeout", "Timeouts and delays", CURLHELP_TIMEOUT },
  { "tls", "TLS/SSL related", CURLHELP_TLS },
  { "upload", "Upload, sending data", CURLHELP_UPLOAD },
  { "verbose", "Tracing, logging etc", CURLHELP_VERBOSE }
};

static void print_category(unsigned int category, unsigned int cols)
{
  unsigned int i;
  size_t longopt = 5;
  size_t longdesc = 5;

  for(i = 0; helptext[i].opt; ++i) {
    size_t len;
    if(!(helptext[i].categories & category))
      continue;
    len = strlen(helptext[i].opt);
    if(len > longopt)
      longopt = len;
    len = strlen(helptext[i].desc);
    if(len > longdesc)
      longdesc = len;
  }

  if(longdesc > cols)
    longopt = 0; /* avoid wrap-around */
  else if(longopt + longdesc > cols)
    longopt = cols - longdesc;

  for(i = 0; helptext[i].opt; ++i)
    if(helptext[i].categories & category) {
      size_t opt = longopt;
      size_t desclen = strlen(helptext[i].desc);
      /* avoid wrap-around */
      if(cols >= 2 && opt + desclen >= (cols - 2)) {
        if(desclen < (cols - 2))
          opt = (cols - 3) - desclen;
        else
          opt = 0;
      }
      curl_mprintf(" %-*s  %s\n", (int)opt, helptext[i].opt, helptext[i].desc);
    }
}

/* Prints category if found. If not, it returns 1 */
static int get_category_content(const char *category, unsigned int cols)
{
  unsigned int i;
  for(i = 0; i < CURL_ARRAYSIZE(categories); ++i)
    if(curl_strequal(categories[i].opt, category)) {
      curl_mprintf("%s: %s\n", categories[i].opt, categories[i].desc);
      print_category(categories[i].category, cols);
      return 0;
    }
  return 1;
}

/* Prints all categories and their description */
static void get_categories(void)
{
  unsigned int i;
  for(i = 0; i < CURL_ARRAYSIZE(categories); ++i)
    curl_mprintf(" %-11s %s\n", categories[i].opt, categories[i].desc);
}

/* Prints all categories as a comma-separated list of given width */
static void get_categories_list(unsigned int width)
{
  unsigned int i;
  size_t col = 0;
  for(i = 0; i < CURL_ARRAYSIZE(categories); ++i) {
    size_t len = strlen(categories[i].opt);
    if(i == CURL_ARRAYSIZE(categories) - 1) {
      /* final category */
      if(col + len + 1 < width)
        curl_mprintf("%s.\n", categories[i].opt);
      else
        /* start a new line first */
        curl_mprintf("\n%s.\n", categories[i].opt);
    }
    else if(col + len + 2 < width) {
      curl_mprintf("%s, ", categories[i].opt);
      col += len + 2;
    }
    else {
      /* start a new line first */
      curl_mprintf("\n%s, ", categories[i].opt);
      col = len + 2;
    }
  }
}

#ifdef USE_MANUAL

void inithelpscan(struct scan_ctx *ctx,
                  const char *trigger,
                  const char *arg,
                  const char *endarg)
{
  ctx->trigger = trigger;
  ctx->tlen = strlen(trigger);
  ctx->arg = arg;
  ctx->flen = strlen(arg);
  ctx->endarg = endarg;
  ctx->elen = strlen(endarg);
  DEBUGASSERT((ctx->elen < sizeof(ctx->rbuf)) &&
              (ctx->flen < sizeof(ctx->rbuf)) &&
              (ctx->tlen < sizeof(ctx->rbuf)));
  ctx->show = 0;
  ctx->olen = 0;
  memset(ctx->rbuf, 0, sizeof(ctx->rbuf));
}

bool helpscan(const unsigned char *buf, size_t len, struct scan_ctx *ctx)
{
  size_t i;
  for(i = 0; i < len; i++) {
    if(!ctx->show) {
      /* wait for the trigger */
      memmove(&ctx->rbuf[0], &ctx->rbuf[1], ctx->tlen - 1);
      ctx->rbuf[ctx->tlen - 1] = buf[i];
      if(!memcmp(ctx->rbuf, ctx->trigger, ctx->tlen))
        ctx->show++;
      continue;
    }
    /* past the trigger */
    if(ctx->show == 1) {
      memmove(&ctx->rbuf[0], &ctx->rbuf[1], ctx->flen - 1);
      ctx->rbuf[ctx->flen - 1] = buf[i];
      if(!memcmp(ctx->rbuf, ctx->arg, ctx->flen)) {
        /* match, now output until endarg */
        fputs(&ctx->arg[1], stdout);
        ctx->show++;
      }
      continue;
    }
    /* show until the end */
    memmove(&ctx->rbuf[0], &ctx->rbuf[1], ctx->elen - 1);
    ctx->rbuf[ctx->elen - 1] = buf[i];
    if(!memcmp(ctx->rbuf, ctx->endarg, ctx->elen))
      return FALSE;

    if(buf[i] == '\n') {
      DEBUGASSERT(ctx->olen < sizeof(ctx->obuf));
      if(ctx->olen == sizeof(ctx->obuf))
        return FALSE; /* bail out */
      ctx->obuf[ctx->olen++] = 0;
      ctx->olen = 0;
      puts(ctx->obuf);
    }
    else {
      DEBUGASSERT(ctx->olen < sizeof(ctx->obuf));
      if(ctx->olen == sizeof(ctx->obuf))
        return FALSE; /* bail out */
      ctx->obuf[ctx->olen++] = buf[i];
    }
  }
  return TRUE;
}

#endif

void tool_help(const char *category)
{
  unsigned int cols = get_terminal_columns();
  /* If no category was provided */
  if(!category) {
    const char *category_note =
      "\nThis is not the full help; this "
      "menu is split into categories.\nUse \"--help category\" to get "
      "an overview of all categories, which are:";
    const char *category_note2 =
      "Use \"--help all\" to list all options"
#ifdef USE_MANUAL
      "\nUse \"--help [option]\" to view documentation for a given option"
#endif
      ;
    puts("Usage: curl [options...] <url>");
    print_category(CURLHELP_IMPORTANT, cols);
    puts(category_note);
    get_categories_list(cols);
    puts(category_note2);
  }
  /* Lets print everything if "all" was provided */
  else if(curl_strequal(category, "all"))
    /* Print everything */
    print_category(CURLHELP_ALL, cols);
  /* Lets handle the string "category" differently to not print an errormsg */
  else if(curl_strequal(category, "category"))
    get_categories();
  else if(category[0] == '-') {
#ifdef USE_MANUAL
    /* command line option help */
    const struct LongShort *a = NULL;
    if(category[1] == '-') {
      const char *lookup = &category[2];
      bool noflagged = FALSE;
      if(!strncmp(lookup, "no-", 3)) {
        lookup += 3;
        noflagged = TRUE;
      }
      a = findlongopt(lookup);
      if(a && noflagged && (ARGTYPE(a->desc) != ARG_BOOL))
        /* a --no- prefix for a non-boolean is not specifying a proper
           option */
        a = NULL;
    }
    else if(!category[2])
      a = findshortopt(category[1]);
    if(!a) {
      curl_mfprintf(tool_stderr, "Incorrect option name to show help for,"
                    " see curl -h\n");
    }
    else {
      char cmdbuf[80];
      if(a->letter != ' ')
        curl_msnprintf(cmdbuf, sizeof(cmdbuf), "\n    -%c, --", a->letter);
      else if(a->desc & ARG_NO)
        curl_msnprintf(cmdbuf, sizeof(cmdbuf), "\n    --no-%s", a->lname);
      else
        curl_msnprintf(cmdbuf, sizeof(cmdbuf), "\n    %s", category);
      if(a->cmd == C_XATTR)
        /* this is the last option, which then ends when FILES starts */
        showhelp("\nALL OPTIONS\n", cmdbuf, "\nFILES");
      else
        showhelp("\nALL OPTIONS\n", cmdbuf, "\n    -");
    }
#else
    curl_mfprintf(tool_stderr, "Cannot comply. "
                  "This curl was built without built-in manual\n");
#endif
  }
  /* Otherwise print category and handle the case if the cat was not found */
  else if(get_category_content(category, cols)) {
    puts("Unknown category provided, here is a list of all categories:\n");
    get_categories();
  }
}

static bool is_debug(void)
{
  const char * const *builtin;
  for(builtin = feature_names; *builtin; ++builtin)
    if(curl_strequal("debug", *builtin))
      return TRUE;
  return FALSE;
}

void tool_version_info(void)
{
  const char * const *builtin;
  if(is_debug())
    curl_mfprintf(tool_stderr, "WARNING: this libcurl is Debug-enabled, "
                  "do not use in production\n\n");

  curl_mprintf(CURL_ID "%s\n", curl_version());
#ifdef CURL_PATCHSTAMP
  curl_mprintf("Release-Date: %s, security patched: %s\n",
               LIBCURL_TIMESTAMP, CURL_PATCHSTAMP);
#else
  curl_mprintf("Release-Date: %s\n", LIBCURL_TIMESTAMP);
#endif
  if(built_in_protos[0]) {
#ifndef CURL_DISABLE_IPFS
    const char *insert = NULL;
    /* we have ipfs and ipns support if libcurl has http support */
    for(builtin = built_in_protos; *builtin; ++builtin) {
      if(insert) {
        /* update insertion so ipfs is printed in alphabetical order */
        if(strcmp(*builtin, "ipfs") < 0)
          insert = *builtin;
        else
          break;
      }
      else if(!strcmp(*builtin, "http")) {
        insert = *builtin;
      }
    }
#endif /* !CURL_DISABLE_IPFS */
    curl_mprintf("Protocols:");
    for(builtin = built_in_protos; *builtin; ++builtin) {
      curl_mprintf(" %s", *builtin);
#ifndef CURL_DISABLE_IPFS
      if(insert && insert == *builtin) {
        curl_mprintf(" ipfs ipns");
        insert = NULL;
      }
#endif /* !CURL_DISABLE_IPFS */
    }
    puts(""); /* newline */
  }
  if(feature_names[0]) {
    const char **feat_ext;
    size_t feat_ext_count = feature_count;
#ifdef CURL_CA_EMBED
    ++feat_ext_count;
#endif
#ifdef CURL_DEBUG_GLOBAL_MEM
    ++feat_ext_count;
#endif
    feat_ext = curlx_malloc(sizeof(*feature_names) * (feat_ext_count + 1));
    if(feat_ext) {
      memcpy((void *)feat_ext, feature_names,
             sizeof(*feature_names) * feature_count);
      feat_ext_count = feature_count;
#ifdef CURL_CA_EMBED
      feat_ext[feat_ext_count++] = "CAcert";
#endif
#ifdef CURL_DEBUG_GLOBAL_MEM
      feat_ext[feat_ext_count++] = "global-mem-debug";
#endif
      feat_ext[feat_ext_count] = NULL;
      qsort((void *)feat_ext, feat_ext_count, sizeof(*feat_ext),
            struplocompare4sort);
      curl_mprintf("Features:");
      for(builtin = feat_ext; *builtin; ++builtin)
        curl_mprintf(" %s", *builtin);
      puts(""); /* newline */
      curlx_free((void *)feat_ext);
    }
  }
  if(strcmp(CURL_VERSION, curlinfo->version)) {
    curl_mprintf("WARNING: curl and libcurl versions do not match. "
                 "Functionality may be affected.\n");
  }
}

void tool_list_engines(void)
{
  CURL *curl = curl_easy_init();
  struct curl_slist *engines = NULL;

  /* Get the list of engines */
  curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines);

  puts("Build-time engines:");
  if(engines) {
    for(; engines; engines = engines->next)
      curl_mprintf("  %s\n", engines->data);
  }
  else {
    puts("  <none>");
  }

  /* Cleanup the list of engines */
  curl_slist_free_all(engines);
  curl_easy_cleanup(curl);
}