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