LCOV - code coverage report
Current view: top level - src/bin/psql - help.c (source / functions) Hit Total Coverage
Test: PostgreSQL 18devel Lines: 357 372 96.0 %
Date: 2025-04-24 01:16:12 Functions: 5 5 100.0 %
Legend: Lines: hit not hit

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

Generated by: LCOV version 1.14