src/bin/psql/help.c

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