src/bin/psql/help.c

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