src/bin/psql/help.c

   1 /*
   2  * psql - the PostgreSQL interactive terminal
   3  *
   4  * Copyright (c) 2000-2008, 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, _("  \\d [NAME]      describe table, index, sequence, or view\n"));
 198         fprintf(output, _("  \\d{t|i|s|v|S} [PATTERN] (add \"+\" for more detail)\n"
 199         "                 list tables/indexes/sequences/views/system tables\n"));
 200         fprintf(output, _("  \\da [PATTERN]  list aggregate functions\n"));
 201         fprintf(output, _("  \\db [PATTERN]  list tablespaces (add \"+\" for more detail)\n"));
 202         fprintf(output, _("  \\dc [PATTERN]  list conversions\n"));
 203         fprintf(output, _("  \\dC [PATTERN]  list casts\n"));
 204         fprintf(output, _("  \\dd [PATTERN]  show comment for object\n"));
 205         fprintf(output, _("  \\dD [PATTERN]  list domains\n"));
 206         fprintf(output, _("  \\df [PATTERN]  list functions (add \"+\" for more detail)\n"));
 207         fprintf(output, _("  \\dF [PATTERN]  list text search configurations (add \"+\" for more detail)\n"));
 208         fprintf(output, _("  \\dFd [PATTERN] list text search dictionaries (add \"+\" for more detail)\n"));
 209         fprintf(output, _("  \\dFt [PATTERN] list text search templates\n"));
 210         fprintf(output, _("  \\dFp [PATTERN] list text search parsers (add \"+\" for more detail)\n"));
 211         fprintf(output, _("  \\dg [PATTERN]  list roles (groups)\n"));
 212         fprintf(output, _("  \\dn [PATTERN]  list schemas (add \"+\" for more detail)\n"));
 213         fprintf(output, _("  \\do [NAME]     list operators\n"));
 214         fprintf(output, _("  \\dl            list large objects, same as \\lo_list\n"));
 215         fprintf(output, _("  \\dp [PATTERN]  list table, view, and sequence access privileges\n"));
 216         fprintf(output, _("  \\dT [PATTERN]  list data types (add \"+\" for more detail)\n"));
 217         fprintf(output, _("  \\du [PATTERN]  list roles (users)\n"));
 218         fprintf(output, _("  \\l             list all databases (add \"+\" for more detail)\n"));
 219         fprintf(output, _("  \\z [PATTERN]   list table, view, and sequence access privileges (same as \\dp)\n"));
 220         fprintf(output, "\n");
 221
 222         fprintf(output, _("Formatting\n"));
 223         fprintf(output, _("  \\a             toggle between unaligned and aligned output mode\n"));
 224         fprintf(output, _("  \\C [STRING]    set table title, or unset if none\n"));
 225         fprintf(output, _("  \\f [STRING]    show or set field separator for unaligned query output\n"));
 226         fprintf(output, _("  \\H             toggle HTML output mode (currently %s)\n"),
 227                         ON(pset.popt.topt.format == PRINT_HTML));
 228         fprintf(output, _("  \\pset NAME [VALUE]  set table output option\n"
 229                                           "                 (NAME := {format|border|expanded|fieldsep|footer|null|\n"
 230                                           "                 numericlocale|recordsep|tuples_only|title|tableattr|pager})\n"));
 231         fprintf(output, _("  \\t [on|off]    show only rows (currently %s)\n"),
 232                         ON(pset.popt.topt.tuples_only));
 233         fprintf(output, _("  \\T [STRING]    set HTML <table> tag attributes, or unset if none\n"));
 234         fprintf(output, _("  \\x [on|off]    toggle expanded output (currently %s)\n"),
 235                         ON(pset.popt.topt.expanded));
 236         fprintf(output, "\n");
 237
 238         fprintf(output, _("Connection\n"));
 239         fprintf(output, _("  \\c[onnect] [DBNAME|- USER|- HOST|- PORT|-]\n"
 240                         "                 connect to new database (currently \"%s\")\n"),
 241                         PQdb(pset.db));
 242         fprintf(output, _("  \\encoding [ENCODING]  show or set client encoding\n"));
 243         fprintf(output, _("  \\password [USERNAME]  securely change the password for a user\n"));
 244         fprintf(output, "\n");
 245
 246         fprintf(output, _("External\n"));
 247         fprintf(output, _("  \\cd [DIR]         change the current working directory\n"));
 248         fprintf(output, _("  \\timing [on|off]  toggle timing of commands (currently %s)\n"),
 249                         ON(pset.timing));
 250         fprintf(output, _("  \\! [COMMAND]      execute command in shell or start interactive shell\n"));
 251         fprintf(output, "\n");
 252
 253         fprintf(output, _("Variable\n"));
 254         fprintf(output, _("  \\prompt [TEXT] NAME  prompt user to set internal variable\n"));
 255         fprintf(output, _("  \\set [NAME [VALUE]]  set internal variable, or list all if no parameters\n"));
 256         fprintf(output, _("  \\unset NAME          unset (delete) internal variable\n"));
 257         fprintf(output, "\n");
 258
 259         fprintf(output, _("Large Object\n"));
 260         fprintf(output, _("  \\lo_export LOBOID FILE\n"
 261                                           "  \\lo_import FILE [COMMENT]\n"
 262                                           "  \\lo_list\n"
 263                                           "  \\lo_unlink LOBOID    large object operations\n"));
 264
 265         if (output != stdout)
 266         {
 267                 pclose(output);
 268 #ifndef WIN32
 269                 pqsignal(SIGPIPE, SIG_DFL);
 270 #endif
 271         }
 272 }
 273
 274
 275
 276 /*
 277  * helpSQL -- help with SQL commands
 278  *
 279  */
 280 void
 281 helpSQL(const char *topic, unsigned short int pager)
 282 {
 283 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
 284
 285         if (!topic || strlen(topic) == 0)
 286         {
 287                 /* Print all the available command names */
 288                 int                     screen_width;
 289                 int                     ncolumns;
 290                 int                     nrows;
 291                 FILE       *output;
 292                 int                     i;
 293                 int                     j;
 294
 295 #ifdef TIOCGWINSZ
 296                 struct winsize screen_size;
 297
 298                 if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
 299                         screen_width = 80;      /* ioctl failed, assume 80 */
 300                 else
 301                         screen_width = screen_size.ws_col;
 302 #else
 303                 screen_width = 80;              /* default assumption */
 304 #endif
 305
 306                 ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
 307                 ncolumns = Max(ncolumns, 1);
 308                 nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
 309
 310                 output = PageOutput(nrows + 1, pager);
 311
 312                 fputs(_("Available help:\n"), output);
 313
 314                 for (i = 0; i < nrows; i++)
 315                 {
 316                         fprintf(output, "  ");
 317                         for (j = 0; j < ncolumns-1; j++)
 318                                 fprintf(output, "%-*s",
 319                                                 QL_MAX_CMD_LEN + 1,
 320                                                 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
 321                         if (i + j * nrows < QL_HELP_COUNT)
 322                                 fprintf(output, "%s",
 323                                                 VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
 324                         fputc('\n', output);
 325                 }
 326
 327                 /* Only close if we used the pager */
 328                 if (output != stdout)
 329                 {
 330                         pclose(output);
 331 #ifndef WIN32
 332                         pqsignal(SIGPIPE, SIG_DFL);
 333 #endif
 334                 }
 335         }
 336         else
 337         {
 338                 int                     i,
 339                                         j,
 340                                         x = 0;
 341                 bool            help_found = false;
 342                 FILE       *output;
 343                 size_t          len,
 344                                         wordlen;
 345                 int                     nl_count = 0;
 346                 const char *ch;
 347
 348                 /* User gets two chances: exact match, then the first word */
 349
 350                 /* First pass : strip trailing spaces and semicolons */
 351                 len = strlen(topic);
 352                 while (topic[len - 1] == ' ' || topic[len - 1] == ';')
 353                         len--;
 354
 355                 for (x = 1; x <= 3; x++)        /* Three chances to guess that word... */
 356                 {
 357                         if (x > 1)                      /* Nothing on first pass - try the opening
 358                                                                  * words */
 359                         {
 360                                 wordlen = j = 1;
 361                                 while (topic[j] != ' ' && j++ < len)
 362                                         wordlen++;
 363                                 if (x == 2)
 364                                 {
 365                                         j++;
 366                                         while (topic[j] != ' ' && j++ <= len)
 367                                                 wordlen++;
 368                                 }
 369                                 if (wordlen >= len)             /* Don't try again if the same word */
 370                                 {
 371                                         output = PageOutput(nl_count, pager);
 372                                         break;
 373                                 }
 374                                 len = wordlen;
 375                         }
 376
 377                         /* Count newlines for pager */
 378                         for (i = 0; QL_HELP[i].cmd; i++)
 379                         {
 380                                 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
 381                                         strcmp(topic, "*") == 0)
 382                                 {
 383                                         nl_count += 5;
 384                                         for (ch = QL_HELP[i].syntax; *ch != '\0'; ch++)
 385                                                 if (*ch == '\n')
 386                                                         nl_count++;
 387                                         /* If we have an exact match, exit.  Fixes \h SELECT */
 388                                         if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
 389                                                 break;
 390                                 }
 391                         }
 392
 393                         output = PageOutput(nl_count, pager);
 394
 395                         for (i = 0; QL_HELP[i].cmd; i++)
 396                         {
 397                                 if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
 398                                         strcmp(topic, "*") == 0)
 399                                 {
 400                                         help_found = true;
 401                                         fprintf(output, _("Command:     %s\n"
 402                                                                           "Description: %s\n"
 403                                                                           "Syntax:\n%s\n\n"),
 404                                                         QL_HELP[i].cmd,
 405                                                         _(QL_HELP[i].help),
 406                                                         _(QL_HELP[i].syntax));
 407                                         /* If we have an exact match, exit.  Fixes \h SELECT */
 408                                         if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
 409                                                 break;
 410                                 }
 411                         }
 412                         if (help_found)         /* Don't keep trying if we got a match */
 413                                 break;
 414                 }
 415
 416                 if (!help_found)
 417                         fprintf(output, _("No help available for \"%-.*s\".\nTry \\h with no arguments to see available help.\n"), (int) len, topic);
 418
 419                 /* Only close if we used the pager */
 420                 if (output != stdout)
 421                 {
 422                         pclose(output);
 423 #ifndef WIN32
 424                         pqsignal(SIGPIPE, SIG_DFL);
 425 #endif
 426                 }
 427         }
 428 }
 429
 430
 431
 432 void
 433 print_copyright(void)
 434 {
 435         puts(
 436                  "PostgreSQL Data Base Management System\n\n"
 437                  "Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group\n\n"
 438                  "This software is based on Postgres95, formerly known as Postgres, which\n"
 439                  "contains the following notice:\n\n"
 440         "Portions Copyright(c) 1994, Regents of the University of California\n\n"
 441         "Permission to use, copy, modify, and distribute this software and its\n"
 442                  "documentation for any purpose, without fee, and without a written agreement\n"
 443                  "is hereby granted, provided that the above copyright notice and this paragraph\n"
 444                  "and the following two paragraphs appear in all copies.\n\n"
 445                  "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
 446                  "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST\n"
 447                  "PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF\n"
 448                  "THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH\n"
 449                  "DAMAGE.\n\n"
 450                  "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,\n"
 451                  "BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A\n"
 452                  "PARTICULAR PURPOSE.THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\" BASIS,\n"
 453                  "AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,\n"
 454                  "SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
 455                 );
 456 }