granicus.if.org Git - postgresql/blob - src/bin/psql/help.c

   1 /*
   2  * psql - the PostgreSQL interactive terminal
   3  *
   4  * Copyright (c) 2000-2019, PostgreSQL Global Development Group
   5  *
   6  * src/bin/psql/help.c
   7  */
   8 #include "postgres_fe.h"
   9
  10 #ifndef WIN32
  11 #include <unistd.h>                             /* for geteuid() */
  12 #else
  13 #include <win32.h>
  14 #endif
  15
  16 #ifndef WIN32
  17 #include <sys/ioctl.h>                  /* for ioctl() */
  18 #endif
  19
  20 #ifdef HAVE_TERMIOS_H
  21 #include <termios.h>
  22 #endif
  23
  24 #include "common.h"
  25 #include "common/logging.h"
  26 #include "common/username.h"
  27 #include "help.h"
  28 #include "input.h"
  29 #include "settings.h"
  30 #include "sql_help.h"
  31
  32 /*
  33  * PLEASE:
  34  * If you change something in this file, also make the same changes
  35  * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
  36  * know how to do it, please find someone who can help you.
  37  */
  38
  39
  40 /*
  41  * usage
  42  *
  43  * print out command line arguments
  44  */
  45 #define ON(var) (var ? _("on") : _("off"))
  46
  47 void
  48 usage(unsigned short int pager)
  49 {
  50         const char *env;
  51         const char *user;
  52         char       *errstr;
  53         FILE       *output;
  54
  55         /* Find default user, in case we need it. */
  56         user = getenv("PGUSER");
  57         if (!user)
  58         {
  59                 user = get_user_name(&errstr);
  60                 if (!user)
  61                 {
  62                         pg_log_fatal("%s", errstr);
  63                         exit(EXIT_FAILURE);
  64                 }
  65         }
  66
  67         /*
  68          * Keep this line count in sync with the number of lines printed below!
  69          * Use "psql --help=options | wc" to count correctly.
  70          */
  71         output = PageOutput(62, pager ? &(pset.popt.topt) : NULL);
  72
  73         fprintf(output, _("psql is the PostgreSQL interactive terminal.\n\n"));
  74         fprintf(output, _("Usage:\n"));
  75         fprintf(output, _("  psql [OPTION]... [DBNAME [USERNAME]]\n\n"));
  76
  77         fprintf(output, _("General options:\n"));
  78         /* Display default database */
  79         env = getenv("PGDATABASE");
  80         if (!env)
  81                 env = user;
  82         fprintf(output, _("  -c, --command=COMMAND    run only single command (SQL or internal) and exit\n"));
  83         fprintf(output, _("  -d, --dbname=DBNAME      database name to connect to (default: \"%s\")\n"), env);
  84         fprintf(output, _("  -f, --file=FILENAME      execute commands from file, then exit\n"));
  85         fprintf(output, _("  -l, --list               list available databases, then exit\n"));
  86         fprintf(output, _("  -v, --set=, --variable=NAME=VALUE\n"
  87                                           "                           set psql variable NAME to VALUE\n"
  88                                           "                           (e.g., -v ON_ERROR_STOP=1)\n"));
  89         fprintf(output, _("  -V, --version            output version information, then exit\n"));
  90         fprintf(output, _("  -X, --no-psqlrc          do not read startup file (~/.psqlrc)\n"));
  91         fprintf(output, _("  -1 (\"one\"), --single-transaction\n"
  92                                           "                           execute as a single transaction (if non-interactive)\n"));
  93         fprintf(output, _("  -?, --help[=options]     show this help, then exit\n"));
  94         fprintf(output, _("      --help=commands      list backslash commands, then exit\n"));
  95         fprintf(output, _("      --help=variables     list special variables, then exit\n"));
  96
  97         fprintf(output, _("\nInput and output options:\n"));
  98         fprintf(output, _("  -a, --echo-all           echo all input from script\n"));
  99         fprintf(output, _("  -b, --echo-errors        echo failed commands\n"));
 100         fprintf(output, _("  -e, --echo-queries       echo commands sent to server\n"));
 101         fprintf(output, _("  -E, --echo-hidden        display queries that internal commands generate\n"));
 102         fprintf(output, _("  -L, --log-file=FILENAME  send session log to file\n"));
 103         fprintf(output, _("  -n, --no-readline        disable enhanced command line editing (readline)\n"));
 104         fprintf(output, _("  -o, --output=FILENAME    send query results to file (or |pipe)\n"));
 105         fprintf(output, _("  -q, --quiet              run quietly (no messages, only query output)\n"));
 106         fprintf(output, _("  -s, --single-step        single-step mode (confirm each query)\n"));
 107         fprintf(output, _("  -S, --single-line        single-line mode (end of line terminates SQL command)\n"));
 108
 109         fprintf(output, _("\nOutput format options:\n"));
 110         fprintf(output, _("  -A, --no-align           unaligned table output mode\n"));
 111         fprintf(output, _("      --csv                CSV (Comma-Separated Values) table output mode\n"));
 112         fprintf(output, _("  -F, --field-separator=STRING\n"
 113                                           "                           field separator for unaligned output (default: \"%s\")\n"),
 114                         DEFAULT_FIELD_SEP);
 115         fprintf(output, _("  -H, --html               HTML table output mode\n"));
 116         fprintf(output, _("  -P, --pset=VAR[=ARG]     set printing option VAR to ARG (see \\pset command)\n"));
 117         fprintf(output, _("  -R, --record-separator=STRING\n"
 118                                           "                           record separator for unaligned output (default: newline)\n"));
 119         fprintf(output, _("  -t, --tuples-only        print rows only\n"));
 120         fprintf(output, _("  -T, --table-attr=TEXT    set HTML table tag attributes (e.g., width, border)\n"));
 121         fprintf(output, _("  -x, --expanded           turn on expanded table output\n"));
 122         fprintf(output, _("  -z, --field-separator-zero\n"
 123                                           "                           set field separator for unaligned output to zero byte\n"));
 124         fprintf(output, _("  -0, --record-separator-zero\n"
 125                                           "                           set record separator for unaligned output to zero byte\n"));
 126
 127         fprintf(output, _("\nConnection options:\n"));
 128         /* Display default host */
 129         env = getenv("PGHOST");
 130         fprintf(output, _("  -h, --host=HOSTNAME      database server host or socket directory (default: \"%s\")\n"),
 131                         env ? env : _("local socket"));
 132         /* Display default port */
 133         env = getenv("PGPORT");
 134         fprintf(output, _("  -p, --port=PORT          database server port (default: \"%s\")\n"),
 135                         env ? env : DEF_PGPORT_STR);
 136         /* Display default user */
 137         env = getenv("PGUSER");
 138         if (!env)
 139                 env = user;
 140         fprintf(output, _("  -U, --username=USERNAME  database user name (default: \"%s\")\n"), env);
 141         fprintf(output, _("  -w, --no-password        never prompt for password\n"));
 142         fprintf(output, _("  -W, --password           force password prompt (should happen automatically)\n"));
 143
 144         fprintf(output, _("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n"
 145                                           "commands) from within psql, or consult the psql section in the PostgreSQL\n"
 146                                           "documentation.\n\n"));
 147         fprintf(output, _("Report bugs to <pgsql-bugs@lists.postgresql.org>.\n"));
 148
 149         ClosePager(output);
 150 }
 151
 152
 153 /*
 154  * slashUsage
 155  *
 156  * print out help for the backslash commands
 157  */
 158 void
 159 slashUsage(unsigned short int pager)
 160 {
 161         FILE       *output;
 162         char       *currdb;
 163
 164         currdb = PQdb(pset.db);
 165
 166         /*
 167          * Keep this line count in sync with the number of lines printed below!
 168          * Use "psql --help=commands | wc" to count correctly.  It's okay to count
 169          * the USE_READLINE line even in builds without that.
 170          */
 171         output = PageOutput(128, pager ? &(pset.popt.topt) : NULL);
 172
 173         fprintf(output, _("General\n"));
 174         fprintf(output, _("  \\copyright             show PostgreSQL usage and distribution terms\n"));
 175         fprintf(output, _("  \\crosstabview [COLUMNS] execute query and display results in crosstab\n"));
 176         fprintf(output, _("  \\errverbose            show most recent error message at maximum verbosity\n"));
 177         fprintf(output, _("  \\g [FILE] or ;         execute query (and send results to file or |pipe)\n"));
 178         fprintf(output, _("  \\gdesc                 describe result of query, without executing it\n"));
 179         fprintf(output, _("  \\gexec                 execute query, then execute each value in its result\n"));
 180         fprintf(output, _("  \\gset [PREFIX]         execute query and store results in psql variables\n"));
 181         fprintf(output, _("  \\gx [FILE]             as \\g, but forces expanded output mode\n"));
 182         fprintf(output, _("  \\q                     quit psql\n"));
 183         fprintf(output, _("  \\watch [SEC]           execute query every SEC seconds\n"));
 184         fprintf(output, "\n");
 185
 186         fprintf(output, _("Help\n"));
 187
 188         fprintf(output, _("  \\? [commands]          show help on backslash commands\n"));
 189         fprintf(output, _("  \\? options             show help on psql command-line options\n"));
 190         fprintf(output, _("  \\? variables           show help on special variables\n"));
 191         fprintf(output, _("  \\h [NAME]              help on syntax of SQL commands, * for all commands\n"));
 192         fprintf(output, "\n");
 193
 194         fprintf(output, _("Query Buffer\n"));
 195         fprintf(output, _("  \\e [FILE] [LINE]       edit the query buffer (or file) with external editor\n"));
 196         fprintf(output, _("  \\ef [FUNCNAME [LINE]]  edit function definition with external editor\n"));
 197         fprintf(output, _("  \\ev [VIEWNAME [LINE]]  edit view definition with external editor\n"));
 198         fprintf(output, _("  \\p                     show the contents of the query buffer\n"));
 199         fprintf(output, _("  \\r                     reset (clear) the query buffer\n"));
 200 #ifdef USE_READLINE
 201         fprintf(output, _("  \\s [FILE]              display history or save it to file\n"));
 202 #endif
 203         fprintf(output, _("  \\w FILE                write query buffer to file\n"));
 204         fprintf(output, "\n");
 205
 206         fprintf(output, _("Input/Output\n"));
 207         fprintf(output, _("  \\copy ...              perform SQL COPY with data stream to the client host\n"));
 208         fprintf(output, _("  \\echo [-n] [STRING]    write string to standard output (-n for no newline)\n"));
 209         fprintf(output, _("  \\i FILE                execute commands from file\n"));
 210         fprintf(output, _("  \\ir FILE               as \\i, but relative to location of current script\n"));
 211         fprintf(output, _("  \\o [FILE]              send all query results to file or |pipe\n"));
 212         fprintf(output, _("  \\qecho [-n] [STRING]   write string to \\o output stream (-n for no newline)\n"));
 213         fprintf(output, _("  \\warn [-n] [STRING]    write string to standard error (-n for no newline)\n"));
 214         fprintf(output, "\n");
 215
 216         fprintf(output, _("Conditional\n"));
 217         fprintf(output, _("  \\if EXPR               begin conditional block\n"));
 218         fprintf(output, _("  \\elif EXPR             alternative within current conditional block\n"));
 219         fprintf(output, _("  \\else                  final alternative within current conditional block\n"));
 220         fprintf(output, _("  \\endif                 end conditional block\n"));
 221         fprintf(output, "\n");
 222
 223         fprintf(output, _("Informational\n"));
 224         fprintf(output, _("  (options: S = show system objects, + = additional detail)\n"));
 225         fprintf(output, _("  \\d[S+]                 list tables, views, and sequences\n"));
 226         fprintf(output, _("  \\d[S+]  NAME           describe table, view, sequence, or index\n"));
 227         fprintf(output, _("  \\da[S]  [PATTERN]      list aggregates\n"));
 228         fprintf(output, _("  \\dA[+]  [PATTERN]      list access methods\n"));
 229         fprintf(output, _("  \\db[+]  [PATTERN]      list tablespaces\n"));
 230         fprintf(output, _("  \\dc[S+] [PATTERN]      list conversions\n"));
 231         fprintf(output, _("  \\dC[+]  [PATTERN]      list casts\n"));
 232         fprintf(output, _("  \\dd[S]  [PATTERN]      show object descriptions not displayed elsewhere\n"));
 233         fprintf(output, _("  \\dD[S+] [PATTERN]      list domains\n"));
 234         fprintf(output, _("  \\ddp    [PATTERN]      list default privileges\n"));
 235         fprintf(output, _("  \\dE[S+] [PATTERN]      list foreign tables\n"));
 236         fprintf(output, _("  \\det[+] [PATTERN]      list foreign tables\n"));
 237         fprintf(output, _("  \\des[+] [PATTERN]      list foreign servers\n"));
 238         fprintf(output, _("  \\deu[+] [PATTERN]      list user mappings\n"));
 239         fprintf(output, _("  \\dew[+] [PATTERN]      list foreign-data wrappers\n"));
 240         fprintf(output, _("  \\df[anptw][S+] [PATRN] list [only agg/normal/procedures/trigger/window] functions\n"));
 241         fprintf(output, _("  \\dF[+]  [PATTERN]      list text search configurations\n"));
 242         fprintf(output, _("  \\dFd[+] [PATTERN]      list text search dictionaries\n"));
 243         fprintf(output, _("  \\dFp[+] [PATTERN]      list text search parsers\n"));
 244         fprintf(output, _("  \\dFt[+] [PATTERN]      list text search templates\n"));
 245         fprintf(output, _("  \\dg[S+] [PATTERN]      list roles\n"));
 246         fprintf(output, _("  \\di[S+] [PATTERN]      list indexes\n"));
 247         fprintf(output, _("  \\dl                    list large objects, same as \\lo_list\n"));
 248         fprintf(output, _("  \\dL[S+] [PATTERN]      list procedural languages\n"));
 249         fprintf(output, _("  \\dm[S+] [PATTERN]      list materialized views\n"));
 250         fprintf(output, _("  \\dn[S+] [PATTERN]      list schemas\n"));
 251         fprintf(output, _("  \\do[S]  [PATTERN]      list operators\n"));
 252         fprintf(output, _("  \\dO[S+] [PATTERN]      list collations\n"));
 253         fprintf(output, _("  \\dp     [PATTERN]      list table, view, and sequence access privileges\n"));
 254         fprintf(output, _("  \\dP[itn+] [PATTERN]    list [only index/table] partitioned relations [n=nested]\n"));
 255         fprintf(output, _("  \\drds [PATRN1 [PATRN2]] list per-database role settings\n"));
 256         fprintf(output, _("  \\dRp[+] [PATTERN]      list replication publications\n"));
 257         fprintf(output, _("  \\dRs[+] [PATTERN]      list replication subscriptions\n"));
 258         fprintf(output, _("  \\ds[S+] [PATTERN]      list sequences\n"));
 259         fprintf(output, _("  \\dt[S+] [PATTERN]      list tables\n"));
 260         fprintf(output, _("  \\dT[S+] [PATTERN]      list data types\n"));
 261         fprintf(output, _("  \\du[S+] [PATTERN]      list roles\n"));
 262         fprintf(output, _("  \\dv[S+] [PATTERN]      list views\n"));
 263         fprintf(output, _("  \\dx[+]  [PATTERN]      list extensions\n"));
 264         fprintf(output, _("  \\dy     [PATTERN]      list event triggers\n"));
 265         fprintf(output, _("  \\l[+]   [PATTERN]      list databases\n"));
 266         fprintf(output, _("  \\sf[+]  FUNCNAME       show a function's definition\n"));
 267         fprintf(output, _("  \\sv[+]  VIEWNAME       show a view's definition\n"));
 268         fprintf(output, _("  \\z      [PATTERN]      same as \\dp\n"));
 269         fprintf(output, "\n");
 270
 271         fprintf(output, _("Formatting\n"));
 272         fprintf(output, _("  \\a                     toggle between unaligned and aligned output mode\n"));
 273         fprintf(output, _("  \\C [STRING]            set table title, or unset if none\n"));
 274         fprintf(output, _("  \\f [STRING]            show or set field separator for unaligned query output\n"));
 275         fprintf(output, _("  \\H                     toggle HTML output mode (currently %s)\n"),
 276                         ON(pset.popt.topt.format == PRINT_HTML));
 277         fprintf(output, _("  \\pset [NAME [VALUE]]   set table output option\n"
 278                                           "                         (border|columns|csv_fieldsep|expanded|fieldsep|\n"
 279                                           "                         fieldsep_zero|footer|format|linestyle|null|\n"
 280                                           "                         numericlocale|pager|pager_min_lines|recordsep|\n"
 281                                           "                         recordsep_zero|tableattr|title|tuples_only|\n"
 282                                           "                         unicode_border_linestyle|unicode_column_linestyle|\n"
 283                                           "                         unicode_header_linestyle)\n"));
 284         fprintf(output, _("  \\t [on|off]            show only rows (currently %s)\n"),
 285                         ON(pset.popt.topt.tuples_only));
 286         fprintf(output, _("  \\T [STRING]            set HTML <table> tag attributes, or unset if none\n"));
 287         fprintf(output, _("  \\x [on|off|auto]       toggle expanded output (currently %s)\n"),
 288                         pset.popt.topt.expanded == 2 ? "auto" : ON(pset.popt.topt.expanded));
 289         fprintf(output, "\n");
 290
 291         fprintf(output, _("Connection\n"));
 292         if (currdb)
 293                 fprintf(output, _("  \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
 294                                                   "                         connect to new database (currently \"%s\")\n"),
 295                                 currdb);
 296         else
 297                 fprintf(output, _("  \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
 298                                                   "                         connect to new database (currently no connection)\n"));
 299         fprintf(output, _("  \\conninfo              display information about current connection\n"));
 300         fprintf(output, _("  \\encoding [ENCODING]   show or set client encoding\n"));
 301         fprintf(output, _("  \\password [USERNAME]   securely change the password for a user\n"));
 302         fprintf(output, "\n");
 303
 304         fprintf(output, _("Operating System\n"));
 305         fprintf(output, _("  \\cd [DIR]              change the current working directory\n"));
 306         fprintf(output, _("  \\setenv NAME [VALUE]   set or unset environment variable\n"));
 307         fprintf(output, _("  \\timing [on|off]       toggle timing of commands (currently %s)\n"),
 308                         ON(pset.timing));
 309         fprintf(output, _("  \\! [COMMAND]           execute command in shell or start interactive shell\n"));
 310         fprintf(output, "\n");
 311
 312         fprintf(output, _("Variables\n"));
 313         fprintf(output, _("  \\prompt [TEXT] NAME    prompt user to set internal variable\n"));
 314         fprintf(output, _("  \\set [NAME [VALUE]]    set internal variable, or list all if no parameters\n"));
 315         fprintf(output, _("  \\unset NAME            unset (delete) internal variable\n"));
 316         fprintf(output, "\n");
 317
 318         fprintf(output, _("Large Objects\n"));
 319         fprintf(output, _("  \\lo_export LOBOID FILE\n"
 320                                           "  \\lo_import FILE [COMMENT]\n"
 321                                           "  \\lo_list\n"
 322                                           "  \\lo_unlink LOBOID      large object operations\n"));
 323
 324         ClosePager(output);
 325 }
 326
 327
 328 /*
 329  * helpVariables
 330  *
 331  * show list of available variables (options) from command line
 332  */
 333 void
 334 helpVariables(unsigned short int pager)
 335 {
 336         FILE       *output;
 337
 338         /*
 339          * Keep this line count in sync with the number of lines printed below!
 340          * Use "psql --help=variables | wc" to count correctly; but notice that
 341          * Windows builds currently print one more line than non-Windows builds.
 342          * Using the larger number is fine.
 343          */
 344         output = PageOutput(158, pager ? &(pset.popt.topt) : NULL);
 345
 346         fprintf(output, _("List of specially treated variables\n\n"));
 347
 348         fprintf(output, _("psql variables:\n"));
 349         fprintf(output, _("Usage:\n"));
 350         fprintf(output, _("  psql --set=NAME=VALUE\n  or \\set NAME VALUE inside psql\n\n"));
 351
 352         fprintf(output, _("  AUTOCOMMIT\n"
 353                                           "    if set, successful SQL commands are automatically committed\n"));
 354         fprintf(output, _("  COMP_KEYWORD_CASE\n"
 355                                           "    determines the case used to complete SQL key words\n"
 356                                           "    [lower, upper, preserve-lower, preserve-upper]\n"));
 357         fprintf(output, _("  DBNAME\n"
 358                                           "    the currently connected database name\n"));
 359         fprintf(output, _("  ECHO\n"
 360                                           "    controls what input is written to standard output\n"
 361                                           "    [all, errors, none, queries]\n"));
 362         fprintf(output, _("  ECHO_HIDDEN\n"
 363                                           "    if set, display internal queries executed by backslash commands;\n"
 364                                           "    if set to \"noexec\", just show them without execution\n"));
 365         fprintf(output, _("  ENCODING\n"
 366                                           "    current client character set encoding\n"));
 367         fprintf(output, _("  ERROR\n"
 368                                           "    true if last query failed, else false\n"));
 369         fprintf(output, _("  FETCH_COUNT\n"
 370                                           "    the number of result rows to fetch and display at a time (0 = unlimited)\n"));
 371         fprintf(output, _("  HIDE_TABLEAM\n"
 372                                           "    if set, table access methods are not displayed\n"));
 373         fprintf(output, _("  HISTCONTROL\n"
 374                                           "    controls command history [ignorespace, ignoredups, ignoreboth]\n"));
 375         fprintf(output, _("  HISTFILE\n"
 376                                           "    file name used to store the command history\n"));
 377         fprintf(output, _("  HISTSIZE\n"
 378                                           "    maximum number of commands to store in the command history\n"));
 379         fprintf(output, _("  HOST\n"
 380                                           "    the currently connected database server host\n"));
 381         fprintf(output, _("  IGNOREEOF\n"
 382                                           "    number of EOFs needed to terminate an interactive session\n"));
 383         fprintf(output, _("  LASTOID\n"
 384                                           "    value of the last affected OID\n"));
 385         fprintf(output, _("  LAST_ERROR_MESSAGE\n"
 386                                           "  LAST_ERROR_SQLSTATE\n"
 387                                           "    message and SQLSTATE of last error, or empty string and \"00000\" if none\n"));
 388         fprintf(output, _("  ON_ERROR_ROLLBACK\n"
 389                                           "    if set, an error doesn't stop a transaction (uses implicit savepoints)\n"));
 390         fprintf(output, _("  ON_ERROR_STOP\n"
 391                                           "    stop batch execution after error\n"));
 392         fprintf(output, _("  PORT\n"
 393                                           "    server port of the current connection\n"));
 394         fprintf(output, _("  PROMPT1\n"
 395                                           "    specifies the standard psql prompt\n"));
 396         fprintf(output, _("  PROMPT2\n"
 397                                           "    specifies the prompt used when a statement continues from a previous line\n"));
 398         fprintf(output, _("  PROMPT3\n"
 399                                           "    specifies the prompt used during COPY ... FROM STDIN\n"));
 400         fprintf(output, _("  QUIET\n"
 401                                           "    run quietly (same as -q option)\n"));
 402         fprintf(output, _("  ROW_COUNT\n"
 403                                           "    number of rows returned or affected by last query, or 0\n"));
 404         fprintf(output, _("  SERVER_VERSION_NAME\n"
 405                                           "  SERVER_VERSION_NUM\n"
 406                                           "    server's version (in short string or numeric format)\n"));
 407         fprintf(output, _("  SHOW_CONTEXT\n"
 408                                           "    controls display of message context fields [never, errors, always]\n"));
 409         fprintf(output, _("  SINGLELINE\n"
 410                                           "    if set, end of line terminates SQL commands (same as -S option)\n"));
 411         fprintf(output, _("  SINGLESTEP\n"
 412                                           "    single-step mode (same as -s option)\n"));
 413         fprintf(output, _("  SQLSTATE\n"
 414                                           "    SQLSTATE of last query, or \"00000\" if no error\n"));
 415         fprintf(output, _("  USER\n"
 416                                           "    the currently connected database user\n"));
 417         fprintf(output, _("  VERBOSITY\n"
 418                                           "    controls verbosity of error reports [default, verbose, terse, sqlstate]\n"));
 419         fprintf(output, _("  VERSION\n"
 420                                           "  VERSION_NAME\n"
 421                                           "  VERSION_NUM\n"
 422                                           "    psql's version (in verbose string, short string, or numeric format)\n"));
 423
 424         fprintf(output, _("\nDisplay settings:\n"));
 425         fprintf(output, _("Usage:\n"));
 426         fprintf(output, _("  psql --pset=NAME[=VALUE]\n  or \\pset NAME [VALUE] inside psql\n\n"));
 427
 428         fprintf(output, _("  border\n"
 429                                           "    border style (number)\n"));
 430         fprintf(output, _("  columns\n"
 431                                           "    target width for the wrapped format\n"));
 432         fprintf(output, _("  expanded (or x)\n"
 433                                           "    expanded output [on, off, auto]\n"));
 434         fprintf(output, _("  fieldsep\n"
 435                                           "    field separator for unaligned output (default \"%s\")\n"),
 436                         DEFAULT_FIELD_SEP);
 437         fprintf(output, _("  fieldsep_zero\n"
 438                                           "    set field separator for unaligned output to a zero byte\n"));
 439         fprintf(output, _("  footer\n"
 440                                           "    enable or disable display of the table footer [on, off]\n"));
 441         fprintf(output, _("  format\n"
 442                                           "    set output format [unaligned, aligned, wrapped, html, asciidoc, ...]\n"));
 443         fprintf(output, _("  linestyle\n"
 444                                           "    set the border line drawing style [ascii, old-ascii, unicode]\n"));
 445         fprintf(output, _("  null\n"
 446                                           "    set the string to be printed in place of a null value\n"));
 447         fprintf(output, _("  numericlocale\n"
 448                                           "    enable display of a locale-specific character to separate groups of digits\n"));
 449         fprintf(output, _("  pager\n"
 450                                           "    control when an external pager is used [yes, no, always]\n"));
 451         fprintf(output, _("  recordsep\n"
 452                                           "    record (line) separator for unaligned output\n"));
 453         fprintf(output, _("  recordsep_zero\n"
 454                                           "    set record separator for unaligned output to a zero byte\n"));
 455         fprintf(output, _("  tableattr (or T)\n"
 456                                           "    specify attributes for table tag in html format, or proportional\n"
 457                                           "    column widths for left-aligned data types in latex-longtable format\n"));
 458         fprintf(output, _("  title\n"
 459                                           "    set the table title for subsequently printed tables\n"));
 460         fprintf(output, _("  tuples_only\n"
 461                                           "    if set, only actual table data is shown\n"));
 462         fprintf(output, _("  unicode_border_linestyle\n"
 463                                           "  unicode_column_linestyle\n"
 464                                           "  unicode_header_linestyle\n"
 465                                           "    set the style of Unicode line drawing [single, double]\n"));
 466
 467         fprintf(output, _("\nEnvironment variables:\n"));
 468         fprintf(output, _("Usage:\n"));
 469
 470 #ifndef WIN32
 471         fprintf(output, _("  NAME=VALUE [NAME=VALUE] psql ...\n  or \\setenv NAME [VALUE] inside psql\n\n"));
 472 #else
 473         fprintf(output, _("  set NAME=VALUE\n  psql ...\n  or \\setenv NAME [VALUE] inside psql\n\n"));
 474 #endif
 475
 476         fprintf(output, _("  COLUMNS\n"
 477                                           "    number of columns for wrapped format\n"));
 478         fprintf(output, _("  PGAPPNAME\n"
 479                                           "    same as the application_name connection parameter\n"));
 480         fprintf(output, _("  PGDATABASE\n"
 481                                           "    same as the dbname connection parameter\n"));
 482         fprintf(output, _("  PGHOST\n"
 483                                           "    same as the host connection parameter\n"));
 484         fprintf(output, _("  PGPASSWORD\n"
 485                                           "    connection password (not recommended)\n"));
 486         fprintf(output, _("  PGPASSFILE\n"
 487                                           "    password file name\n"));
 488         fprintf(output, _("  PGPORT\n"
 489                                           "    same as the port connection parameter\n"));
 490         fprintf(output, _("  PGUSER\n"
 491                                           "    same as the user connection parameter\n"));
 492         fprintf(output, _("  PSQL_EDITOR, EDITOR, VISUAL\n"
 493                                           "    editor used by the \\e, \\ef, and \\ev commands\n"));
 494         fprintf(output, _("  PSQL_EDITOR_LINENUMBER_ARG\n"
 495                                           "    how to specify a line number when invoking the editor\n"));
 496         fprintf(output, _("  PSQL_HISTORY\n"
 497                                           "    alternative location for the command history file\n"));
 498         fprintf(output, _("  PSQL_PAGER, PAGER\n"
 499                                           "    name of external pager program\n"));
 500         fprintf(output, _("  PSQLRC\n"
 501                                           "    alternative location for the user's .psqlrc file\n"));
 502         fprintf(output, _("  SHELL\n"
 503                                           "    shell used by the \\! command\n"));
 504         fprintf(output, _("  TMPDIR\n"
 505                                           "    directory for temporary files\n"));
 506
 507         ClosePager(output);
 508 }
 509
 510
 511 /*
 512  * helpSQL -- help with SQL commands
 513  *
 514  * Note: we assume caller removed any trailing spaces in "topic".
 515  */
 516 void
 517 helpSQL(const char *topic, unsigned short int pager)
 518 {
 519 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
 520
 521         if (!topic || strlen(topic) == 0)
 522         {
 523                 /* Print all the available command names */
 524                 int                     screen_width;
 525                 int                     ncolumns;
 526                 int                     nrows;
 527                 FILE       *output;
 528                 int                     i;
 529                 int                     j;
 530
 531 #ifdef TIOCGWINSZ
 532                 struct winsize screen_size;
 533
 534                 if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
 535                         screen_width = 80;      /* ioctl failed, assume 80 */
 536                 else
 537                         screen_width = screen_size.ws_col;
 538 #else
 539                 screen_width = 80;              /* default assumption */
 540 #endif
 541
 542                 ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
 543                 ncolumns = Max(ncolumns, 1);
 544                 nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
 545
 546                 output = PageOutput(nrows + 1, pager ? &(pset.popt.topt) : NULL);
 547
 548                 fputs(_("Available help:\n"), output);
 549
 550                 for (i = 0; i < nrows; i++)
 551                 {
 552                         fprintf(output, "  ");
 553                         for (j = 0; j < ncolumns - 1; j++)
 554                                 fprintf(output, "%-*s",
 555                                                 QL_MAX_CMD_LEN + 1,
 556                                                 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
 557                         if (i + j * nrows < QL_HELP_COUNT)
 558                                 fprintf(output, "%s",
 559                                                 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
 560                         fputc('\n', output);
 561                 }
 562
 563                 ClosePager(output);
 564         }
 565         else
 566         {
 567                 int                     i,
 568                                         j,
 569                                         x = 0;
 570                 bool            help_found = false;
 571                 FILE       *output = NULL;
 572                 size_t          len,
 573                                         wordlen;
 574                 int                     nl_count = 0;
 575
 576                 /*
 577                  * We first try exact match, then first + second words, then first
 578                  * word only.
 579                  */
 580                 len = strlen(topic);
 581
 582                 for (x = 1; x <= 3; x++)
 583                 {
 584                         if (x > 1)                      /* Nothing on first pass - try the opening
 585                                                                  * word(s) */
 586                         {
 587                                 wordlen = j = 1;
 588                                 while (topic[j] != ' ' && j++ < len)
 589                                         wordlen++;
 590                                 if (x == 2)
 591                                 {
 592                                         j++;
 593                                         while (topic[j] != ' ' && j++ <= len)
 594                                                 wordlen++;
 595                                 }
 596                                 if (wordlen >= len) /* Don't try again if the same word */
 597                                 {
 598                                         if (!output)
 599                                                 output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
 600                                         break;
 601                                 }
 602                                 len = wordlen;
 603                         }
 604
 605                         /* Count newlines for pager */
 606                         for (i = 0; QL_HELP[i].cmd; i++)
 607                         {
 608                                 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
 609                                         strcmp(topic, "*") == 0)
 610                                 {
 611                                         nl_count += 5 + QL_HELP[i].nl_count;
 612
 613                                         /* If we have an exact match, exit.  Fixes \h SELECT */
 614                                         if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
 615                                                 break;
 616                                 }
 617                         }
 618
 619                         if (!output)
 620                                 output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
 621
 622                         for (i = 0; QL_HELP[i].cmd; i++)
 623                         {
 624                                 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
 625                                         strcmp(topic, "*") == 0)
 626                                 {
 627                                         PQExpBufferData buffer;
 628                                         char       *url;
 629
 630                                         initPQExpBuffer(&buffer);
 631                                         QL_HELP[i].syntaxfunc(&buffer);
 632                                         help_found = true;
 633                                         url = psprintf("https://www.postgresql.org/docs/%s/%s.html",
 634                                                                    strstr(PG_VERSION, "devel") ? "devel" : PG_MAJORVERSION,
 635                                                                    QL_HELP[i].docbook_id);
 636                                         fprintf(output, _("Command:     %s\n"
 637                                                                           "Description: %s\n"
 638                                                                           "Syntax:\n%s\n\n"
 639                                                                           "URL: %s\n\n"),
 640                                                         QL_HELP[i].cmd,
 641                                                         _(QL_HELP[i].help),
 642                                                         buffer.data,
 643                                                         url);
 644                                         free(url);
 645                                         /* If we have an exact match, exit.  Fixes \h SELECT */
 646                                         if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
 647                                                 break;
 648                                 }
 649                         }
 650                         if (help_found)         /* Don't keep trying if we got a match */
 651                                 break;
 652                 }
 653
 654                 if (!help_found)
 655                         fprintf(output, _("No help available for \"%s\".\nTry \\h with no arguments to see available help.\n"), topic);
 656
 657                 ClosePager(output);
 658         }
 659 }
 660
 661
 662
 663 void
 664 print_copyright(void)
 665 {
 666         puts(
 667                  "PostgreSQL Database Management System\n"
 668                  "(formerly known as Postgres, then as Postgres95)\n\n"
 669                  "Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group\n\n"
 670                  "Portions Copyright (c) 1994, The Regents of the University of California\n\n"
 671                  "Permission to use, copy, modify, and distribute this software and its\n"
 672                  "documentation for any purpose, without fee, and without a written agreement\n"
 673                  "is hereby granted, provided that the above copyright notice and this\n"
 674                  "paragraph and the following two paragraphs appear in all copies.\n\n"
 675                  "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
 676                  "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING\n"
 677                  "LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS\n"
 678                  "DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE\n"
 679                  "POSSIBILITY OF SUCH DAMAGE.\n\n"
 680                  "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,\n"
 681                  "INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\n"
 682                  "AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS\n"
 683                  "ON AN \"AS IS\" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO\n"
 684                  "PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\n"
 685                 );
 686 }