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

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