granicus.if.org Git - postgresql/blob - src/bin/psql/help.c

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