src/bin/psql/help.c

   1 /*
   2  * psql - the PostgreSQL interactive terminal
   3  *
   4  * Copyright (c) 2000-2010, PostgreSQL Global Development Group
   5  *
   6  * src/bin/psql/help.c
   7  */
   8 #include "postgres_fe.h"
   9
  10 #ifndef WIN32
  11 #ifdef HAVE_PWD_H
  12 #include <pwd.h>                                /* for getpwuid() */
  13 #endif
  14 #include <sys/types.h>                  /* (ditto) */
  15 #include <unistd.h>                             /* for geteuid() */
  16 #else
  17 #include <win32.h>
  18 #endif
  19
  20 #ifndef WIN32
  21 #include <sys/ioctl.h>                  /* for ioctl() */
  22 #endif
  23
  24 #ifdef HAVE_TERMIOS_H
  25 #include <termios.h>
  26 #endif
  27
  28 #include "common.h"
  29 #include "help.h"
  30 #include "input.h"
  31 #include "settings.h"
  32 #include "sql_help.h"
  33
  34
  35 /*
  36  * PLEASE:
  37  * If you change something in this file, also make the same changes
  38  * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
  39  * know how to do it, please find someone who can help you.
  40  */
  41
  42
  43 /*
  44  * usage
  45  *
  46  * print out command line arguments
  47  */
  48 #define ON(var) (var ? _("on") : _("off"))
  49
  50 void
  51 usage(void)
  52 {
  53         const char *env;
  54         const char *user;
  55
  56 #ifndef WIN32
  57         struct passwd *pw = NULL;
  58 #endif
  59
  60         /* Find default user, in case we need it. */
  61         user = getenv("PGUSER");
  62         if (!user)
  63         {
  64 #if !defined(WIN32) && !defined(__OS2__)
  65                 pw = getpwuid(geteuid());
  66                 if (pw)
  67                         user = pw->pw_name;
  68                 else
  69                 {
  70                         psql_error("could not get current user name: %s\n", strerror(errno));
  71                         exit(EXIT_FAILURE);
  72                 }
  73 #else                                                   /* WIN32 */
  74                 char            buf[128];
  75                 DWORD           bufsize = sizeof(buf) - 1;
  76
  77                 if (GetUserName(buf, &bufsize))
  78                         user = buf;
  79 #endif   /* WIN32 */
  80         }
  81
  82         printf(_("psql is the PostgreSQL interactive terminal.\n\n"));
  83         printf(_("Usage:\n"));
  84         printf(_("  psql [OPTION]... [DBNAME [USERNAME]]\n\n"));
  85
  86         printf(_("General options:\n"));
  87         /* Display default database */
  88         env = getenv("PGDATABASE");
  89         if (!env)
  90                 env = user;
  91         printf(_("  -c, --command=COMMAND    run only single command (SQL or internal) and exit\n"));
  92         printf(_("  -d, --dbname=DBNAME      database name to connect to (default: \"%s\")\n"), env);
  93         printf(_("  -f, --file=FILENAME      execute commands from file, then exit\n"));
  94         printf(_("  -l, --list               list available databases, then exit\n"));
  95         printf(_("  -v, --set=, --variable=NAME=VALUE\n"
  96                          "                           set psql variable NAME to VALUE\n"));
  97         printf(_("  -X, --no-psqlrc          do not read startup file (~/.psqlrc)\n"));
  98         printf(_("  -1 (\"one\"), --single-transaction\n"
  99                          "                           execute command file as a single transaction\n"));
 100         printf(_("  --help                   show this help, then exit\n"));
 101         printf(_("  --version                output version information, then exit\n"));
 102
 103         printf(_("\nInput and output options:\n"));
 104         printf(_("  -a, --echo-all           echo all input from script\n"));
 105         printf(_("  -e, --echo-queries       echo commands sent to server\n"));
 106         printf(_("  -E, --echo-hidden        display queries that internal commands generate\n"));
 107         printf(_("  -L, --log-file=FILENAME  send session log to file\n"));
 108         printf(_("  -n, --no-readline        disable enhanced command line editing (readline)\n"));
 109         printf(_("  -o, --output=FILENAME    send query results to file (or |pipe)\n"));
 110         printf(_("  -q, --quiet              run quietly (no messages, only query output)\n"));
 111         printf(_("  -s, --single-step        single-step mode (confirm each query)\n"));
 112         printf(_("  -S, --single-line        single-line mode (end of line terminates SQL command)\n"));
 113
 114         printf(_("\nOutput format options:\n"));
 115         printf(_("  -A, --no-align           unaligned table output mode\n"));
 116         printf(_("  -F, --field-separator=STRING\n"
 117            "                           set field separator (default: \"%s\")\n"),
 118                    DEFAULT_FIELD_SEP);
 119         printf(_("  -H, --html               HTML table output mode\n"));
 120         printf(_("  -P, --pset=VAR[=ARG]     set printing option VAR to ARG (see \\pset command)\n"));
 121         printf(_("  -R, --record-separator=STRING\n"
 122         "                           set record separator (default: newline)\n"));
 123         printf(_("  -t, --tuples-only        print rows only\n"));
 124         printf(_("  -T, --table-attr=TEXT    set HTML table tag attributes (e.g., width, border)\n"));
 125         printf(_("  -x, --expanded           turn on expanded table output\n"));
 126
 127         printf(_("\nConnection options:\n"));
 128         /* Display default host */
 129         env = getenv("PGHOST");
 130         printf(_("  -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         printf(_("  -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         printf(_("  -U, --username=USERNAME  database user name (default: \"%s\")\n"), env);
 141         printf(_("  -w, --no-password        never prompt for password\n"));
 142         printf(_("  -W, --password           force password prompt (should happen automatically)\n"));
 143
 144         printf(_("\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         printf(_("Report bugs to <pgsql-bugs@postgresql.org>.\n"));
 148 }
 149
 150
 151 /*
 152  * slashUsage
 153  *
 154  * print out help for the backslash commands
 155  */
 156 void
 157 slashUsage(unsigned short int pager)
 158 {
 159         FILE       *output;
 160
 161         output = PageOutput(90, pager);
 162
 163         /* if you add/remove a line here, change the row count above */
 164
 165         fprintf(output, _("General\n"));
 166         fprintf(output, _("  \\copyright             show PostgreSQL usage and distribution terms\n"));
 167         fprintf(output, _("  \\g [FILE] or ;         execute query (and send results to file or |pipe)\n"));
 168         fprintf(output, _("  \\h [NAME]              help on syntax of SQL commands, * for all commands\n"));
 169         fprintf(output, _("  \\q                     quit psql\n"));
 170         fprintf(output, "\n");
 171
 172         fprintf(output, _("Query Buffer\n"));
 173         fprintf(output, _("  \\e [FILE] [LINE]       edit the query buffer (or file) with external editor\n"));
 174         fprintf(output, _("  \\ef [FUNCNAME [LINE]]  edit function definition with external editor\n"));
 175         fprintf(output, _("  \\p                     show the contents of the query buffer\n"));
 176         fprintf(output, _("  \\r                     reset (clear) the query buffer\n"));
 177 #ifdef USE_READLINE
 178         fprintf(output, _("  \\s [FILE]              display history or save it to file\n"));
 179 #endif
 180         fprintf(output, _("  \\w FILE                write query buffer to file\n"));
 181         fprintf(output, "\n");
 182
 183         fprintf(output, _("Input/Output\n"));
 184         fprintf(output, _("  \\copy ...              perform SQL COPY with data stream to the client host\n"));
 185         fprintf(output, _("  \\echo [STRING]         write string to standard output\n"));
 186         fprintf(output, _("  \\i FILE                execute commands from file\n"));
 187         fprintf(output, _("  \\o [FILE]              send all query results to file or |pipe\n"));
 188         fprintf(output, _("  \\qecho [STRING]        write string to query output stream (see \\o)\n"));
 189         fprintf(output, "\n");
 190
 191         fprintf(output, _("Informational\n"));
 192         fprintf(output, _("  (options: S = show system objects, + = additional detail)\n"));
 193         fprintf(output, _("  \\d[S+]                 list tables, views, and sequences\n"));
 194         fprintf(output, _("  \\d[S+]  NAME           describe table, view, sequence, or index\n"));
 195         fprintf(output, _("  \\da[S]  [PATTERN]      list aggregates\n"));
 196         fprintf(output, _("  \\db[+]  [PATTERN]      list tablespaces\n"));
 197         fprintf(output, _("  \\dc[S]  [PATTERN]      list conversions\n"));
 198         fprintf(output, _("  \\dC     [PATTERN]      list casts\n"));
 199         fprintf(output, _("  \\dd[S]  [PATTERN]      show comments on objects\n"));
 200         fprintf(output, _("  \\ddp    [PATTERN]      list default privileges\n"));
 201         fprintf(output, _("  \\dD[S]  [PATTERN]      list domains\n"));
 202         fprintf(output, _("  \\des[+] [PATTERN]      list foreign servers\n"));
 203         fprintf(output, _("  \\deu[+] [PATTERN]      list user mappings\n"));
 204         fprintf(output, _("  \\dew[+] [PATTERN]      list foreign-data wrappers\n"));
 205         fprintf(output, _("  \\df[antw][S+] [PATRN]  list [only agg/normal/trigger/window] functions\n"));
 206         fprintf(output, _("  \\dF[+]  [PATTERN]      list text search configurations\n"));
 207         fprintf(output, _("  \\dFd[+] [PATTERN]      list text search dictionaries\n"));
 208         fprintf(output, _("  \\dFp[+] [PATTERN]      list text search parsers\n"));
 209         fprintf(output, _("  \\dFt[+] [PATTERN]      list text search templates\n"));
 210         fprintf(output, _("  \\dg[+]  [PATTERN]      list roles\n"));
 211         fprintf(output, _("  \\di[S+] [PATTERN]      list indexes\n"));
 212         fprintf(output, _("  \\dl                    list large objects, same as \\lo_list\n"));
 213         fprintf(output, _("  \\dn[+]  [PATTERN]      list schemas\n"));
 214         fprintf(output, _("  \\do[S]  [PATTERN]      list operators\n"));
 215         fprintf(output, _("  \\dp     [PATTERN]      list table, view, and sequence access privileges\n"));
 216         fprintf(output, _("  \\drds [PATRN1 [PATRN2]] list per-database role settings\n"));
 217         fprintf(output, _("  \\ds[S+] [PATTERN]      list sequences\n"));
 218         fprintf(output, _("  \\dt[S+] [PATTERN]      list tables\n"));
 219         fprintf(output, _("  \\dT[S+] [PATTERN]      list data types\n"));
 220         fprintf(output, _("  \\du[+]  [PATTERN]      list roles\n"));
 221         fprintf(output, _("  \\dv[S+] [PATTERN]      list views\n"));
 222         fprintf(output, _("  \\l[+]                  list all databases\n"));
 223         fprintf(output, _("  \\sf[+] FUNCNAME        show a function's definition\n"));
 224         fprintf(output, _("  \\z      [PATTERN]      same as \\dp\n"));
 225         fprintf(output, "\n");
 226
 227         fprintf(output, _("Formatting\n"));
 228         fprintf(output, _("  \\a                     toggle between unaligned and aligned output mode\n"));
 229         fprintf(output, _("  \\C [STRING]            set table title, or unset if none\n"));
 230         fprintf(output, _("  \\f [STRING]            show or set field separator for unaligned query output\n"));
 231         fprintf(output, _("  \\H                     toggle HTML output mode (currently %s)\n"),
 232                         ON(pset.popt.topt.format == PRINT_HTML));
 233         fprintf(output, _("  \\pset NAME [VALUE]     set table output option\n"
 234                                           "                         (NAME := {format|border|expanded|fieldsep|footer|null|\n"
 235                                           "                         numericlocale|recordsep|tuples_only|title|tableattr|pager})\n"));
 236         fprintf(output, _("  \\t [on|off]            show only rows (currently %s)\n"),
 237                         ON(pset.popt.topt.tuples_only));
 238         fprintf(output, _("  \\T [STRING]            set HTML <table> tag attributes, or unset if none\n"));
 239         fprintf(output, _("  \\x [on|off]            toggle expanded output (currently %s)\n"),
 240                         ON(pset.popt.topt.expanded));
 241         fprintf(output, "\n");
 242
 243         fprintf(output, _("Connection\n"));
 244         fprintf(output, _("  \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n"
 245         "                         connect to new database (currently \"%s\")\n"),
 246                         PQdb(pset.db));
 247         fprintf(output, _("  \\encoding [ENCODING]   show or set client encoding\n"));
 248         fprintf(output, _("  \\password [USERNAME]   securely change the password for a user\n"));
 249         fprintf(output, _("  \\conninfo              display information about current connection\n"));
 250         fprintf(output, "\n");
 251
 252         fprintf(output, _("Operating System\n"));
 253         fprintf(output, _("  \\cd [DIR]              change the current working directory\n"));
 254         fprintf(output, _("  \\timing [on|off]       toggle timing of commands (currently %s)\n"),
 255                         ON(pset.timing));
 256         fprintf(output, _("  \\! [COMMAND]           execute command in shell or start interactive shell\n"));
 257         fprintf(output, "\n");
 258
 259         fprintf(output, _("Variables\n"));
 260         fprintf(output, _("  \\prompt [TEXT] NAME    prompt user to set internal variable\n"));
 261         fprintf(output, _("  \\set [NAME [VALUE]]    set internal variable, or list all if no parameters\n"));
 262         fprintf(output, _("  \\unset NAME            unset (delete) internal variable\n"));
 263         fprintf(output, "\n");
 264
 265         fprintf(output, _("Large Objects\n"));
 266         fprintf(output, _("  \\lo_export LOBOID FILE\n"
 267                                           "  \\lo_import FILE [COMMENT]\n"
 268                                           "  \\lo_list\n"
 269                                           "  \\lo_unlink LOBOID      large object operations\n"));
 270
 271         ClosePager(output);
 272 }
 273
 274
 275
 276 /*
 277  * helpSQL -- help with SQL commands
 278  *
 279  * Note: we assume caller removed any trailing spaces in "topic".
 280  */
 281 void
 282 helpSQL(const char *topic, unsigned short int pager)
 283 {
 284 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
 285
 286         if (!topic || strlen(topic) == 0)
 287         {
 288                 /* Print all the available command names */
 289                 int                     screen_width;
 290                 int                     ncolumns;
 291                 int                     nrows;
 292                 FILE       *output;
 293                 int                     i;
 294                 int                     j;
 295
 296 #ifdef TIOCGWINSZ
 297                 struct winsize screen_size;
 298
 299                 if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
 300                         screen_width = 80;      /* ioctl failed, assume 80 */
 301                 else
 302                         screen_width = screen_size.ws_col;
 303 #else
 304                 screen_width = 80;              /* default assumption */
 305 #endif
 306
 307                 ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
 308                 ncolumns = Max(ncolumns, 1);
 309                 nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
 310
 311                 output = PageOutput(nrows + 1, pager);
 312
 313                 fputs(_("Available help:\n"), output);
 314
 315                 for (i = 0; i < nrows; i++)
 316                 {
 317                         fprintf(output, "  ");
 318                         for (j = 0; j < ncolumns - 1; j++)
 319                                 fprintf(output, "%-*s",
 320                                                 QL_MAX_CMD_LEN + 1,
 321                                                 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
 322                         if (i + j * nrows < QL_HELP_COUNT)
 323                                 fprintf(output, "%s",
 324                                                 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
 325                         fputc('\n', output);
 326                 }
 327
 328                 ClosePager(output);
 329         }
 330         else
 331         {
 332                 int                     i,
 333                                         j,
 334                                         x = 0;
 335                 bool            help_found = false;
 336                 FILE       *output = NULL;
 337                 size_t          len,
 338                                         wordlen;
 339                 int                     nl_count = 0;
 340
 341                 /*
 342                  * We first try exact match, then first + second words, then first
 343                  * word only.
 344                  */
 345                 len = strlen(topic);
 346
 347                 for (x = 1; x <= 3; x++)
 348                 {
 349                         if (x > 1)                      /* Nothing on first pass - try the opening
 350                                                                  * word(s) */
 351                         {
 352                                 wordlen = j = 1;
 353                                 while (topic[j] != ' ' && j++ < len)
 354                                         wordlen++;
 355                                 if (x == 2)
 356                                 {
 357                                         j++;
 358                                         while (topic[j] != ' ' && j++ <= len)
 359                                                 wordlen++;
 360                                 }
 361                                 if (wordlen >= len)             /* Don't try again if the same word */
 362                                 {
 363                                         if (!output)
 364                                                 output = PageOutput(nl_count, pager);
 365                                         break;
 366                                 }
 367                                 len = wordlen;
 368                         }
 369
 370                         /* Count newlines for pager */
 371                         for (i = 0; QL_HELP[i].cmd; i++)
 372                         {
 373                                 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
 374                                         strcmp(topic, "*") == 0)
 375                                 {
 376                                         nl_count += 5 + QL_HELP[i].nl_count;
 377
 378                                         /* If we have an exact match, exit.  Fixes \h SELECT */
 379                                         if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
 380                                                 break;
 381                                 }
 382                         }
 383
 384                         if (!output)
 385                                 output = PageOutput(nl_count, pager);
 386
 387                         for (i = 0; QL_HELP[i].cmd; i++)
 388                         {
 389                                 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
 390                                         strcmp(topic, "*") == 0)
 391                                 {
 392                                         PQExpBufferData buffer;
 393
 394                                         initPQExpBuffer(&buffer);
 395                                         QL_HELP[i].syntaxfunc(&buffer);
 396                                         help_found = true;
 397                                         fprintf(output, _("Command:     %s\n"
 398                                                                           "Description: %s\n"
 399                                                                           "Syntax:\n%s\n\n"),
 400                                                         QL_HELP[i].cmd,
 401                                                         _(QL_HELP[i].help),
 402                                                         buffer.data);
 403                                         /* If we have an exact match, exit.  Fixes \h SELECT */
 404                                         if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
 405                                                 break;
 406                                 }
 407                         }
 408                         if (help_found)         /* Don't keep trying if we got a match */
 409                                 break;
 410                 }
 411
 412                 if (!help_found)
 413                         fprintf(output, _("No help available for \"%s\".\nTry \\h with no arguments to see available help.\n"), topic);
 414
 415                 ClosePager(output);
 416         }
 417 }
 418
 419
 420
 421 void
 422 print_copyright(void)
 423 {
 424         puts(
 425                  "PostgreSQL Data Base Management System\n\n"
 426                  "Portions Copyright (c) 1996-2010, PostgreSQL Global Development Group\n\n"
 427                  "This software is based on Postgres95, formerly known as Postgres, which\n"
 428                  "contains the following notice:\n\n"
 429         "Portions Copyright(c) 1994, Regents of the University of California\n\n"
 430         "Permission to use, copy, modify, and distribute this software and its\n"
 431                  "documentation for any purpose, without fee, and without a written agreement\n"
 432                  "is hereby granted, provided that the above copyright notice and this paragraph\n"
 433                  "and the following two paragraphs appear in all copies.\n\n"
 434                  "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
 435                  "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST\n"
 436                  "PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF\n"
 437                  "THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH\n"
 438                  "DAMAGE.\n\n"
 439                  "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,\n"
 440                  "BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A\n"
 441                  "PARTICULAR PURPOSE.THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\" BASIS,\n"
 442                  "AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,\n"
 443                  "SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
 444                 );
 445 }