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