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

   1 #include <config.h>
   2 #include <c.h>
   3 #include "help.h"
   4
   5 #include <stdio.h>
   6 #include <stdlib.h>
   7 #include <signal.h>
   8
   9 #ifndef WIN32
  10 #include <sys/ioctl.h>                  /* for ioctl() */
  11 #ifdef HAVE_PWD_H
  12 #include <pwd.h>                                /* for getpwuid() */
  13 #endif
  14 #include <sys/types.h>                  /* (ditto) */
  15 #include <unistd.h>                             /* for getuid() */
  16 #else
  17 #define strcasecmp(x,y) stricmp(x,y)
  18 #define popen(x,y) _popen(x,y)
  19 #define pclose(x) _pclose(x)
  20 #endif
  21
  22 #include <pqsignal.h>
  23 #include <libpq-fe.h>
  24
  25 #include "settings.h"
  26 #include "common.h"
  27 #include "sql_help.h"
  28
  29
  30 /*
  31  * usage
  32  *
  33  * print out command line arguments and exit
  34  */
  35 #define ON(var) (var ? "on" : "off")
  36
  37 void
  38 usage(void)
  39 {
  40         const char *env;
  41         const char *user;
  42
  43 #ifndef WIN32
  44         struct passwd *pw = NULL;
  45
  46 #endif
  47
  48         /* Find default user, in case we need it. */
  49         user = getenv("USER");
  50         if (!user)
  51         {
  52 #ifndef WIN32
  53                 pw = getpwuid(getuid());
  54                 if (pw)
  55                         user = pw->pw_name;
  56                 else
  57                 {
  58                         perror("getpwuid()");
  59                         exit(EXIT_FAILURE);
  60                 }
  61 #else
  62                 user = "?";
  63 #endif
  64         }
  65
  66 /* If string begins " here, then it ought to end there to fit on an 80 column terminal> > > > > > > " */
  67         fprintf(stderr, "Usage: psql [options] [dbname [username]] \n");
  68         fprintf(stderr, "    -A              Unaligned table output mode (-P format=unaligned)\n");
  69         fprintf(stderr, "    -c query        Run single query (slash commands, too) and exit\n");
  70
  71         /* Display default database */
  72         env = getenv("PGDATABASE");
  73         if (!env)
  74                 env = user;
  75         fprintf(stderr, "    -d dbname       Specify database name to connect to (default: %s)\n", env);
  76
  77         fprintf(stderr, "    -e              Echo all input in non-interactive mode\n");
  78         fprintf(stderr, "    -E              Display queries that internal commands generate\n");
  79         fprintf(stderr, "    -f filename     Execute queries from file, then exit\n");
  80         fprintf(stderr, "    -F sep          Set field separator (default: '" DEFAULT_FIELD_SEP "') (-P fieldsep=)\n");
  81
  82         /* Display default host */
  83         env = getenv("PGHOST");
  84         fprintf(stderr, "    -h host         Specify database server host (default: ");
  85         if (env)
  86                 fprintf(stderr, env);
  87         else
  88                 fprintf(stderr, "domain socket");
  89         fprintf(stderr, ")\n");
  90
  91         fprintf(stderr, "    -H              HTML table output mode (-P format=html)\n");
  92         fprintf(stderr, "    -l              List available databases, then exit\n");
  93         fprintf(stderr, "    -n              Do not use readline and history\n");
  94         fprintf(stderr, "    -o filename     Send query output to filename (or |pipe)\n");
  95
  96         /* Display default port */
  97         env = getenv("PGPORT");
  98         fprintf(stderr, "    -p port         Specify database server port (default: %s)\n",
  99                         env ? env : "hardwired");
 100
 101         fprintf(stderr, "    -P var[=arg]    Set printing option 'var' to 'arg'. (see \\pset command)\n");
 102         fprintf(stderr, "    -q              Run quietly (no messages, no prompts)\n");
 103         fprintf(stderr, "    -s              Single step mode (confirm each query)\n");
 104         fprintf(stderr, "    -S              Single line mode (newline sends query)\n");
 105         fprintf(stderr, "    -t              Don't print headings and row count (-P tuples_only)\n");
 106         fprintf(stderr, "    -T text         Set HTML table tag options (e.g., width, border)\n");
 107         fprintf(stderr, "    -u              Prompt for username and password (same as \"-U ? -W\")\n");
 108
 109         /* Display default user */
 110         env = getenv("PGUSER");
 111         if (!env)
 112                 env = user;
 113         fprintf(stderr, "    -U [username]   Specifiy username, \"?\"=prompt (default user: %s)\n", env);
 114
 115         fprintf(stderr, "    -x              Turn on expanded table output (-P expanded)\n");
 116         fprintf(stderr, "    -v name=val     Set psql variable 'name' to 'value'\n");
 117         fprintf(stderr, "    -V              Show version information and exit\n");
 118         fprintf(stderr, "    -W              Prompt for password (should happen automatically)\n");
 119
 120         fprintf(stderr, "Consult the documentation for the complete details.\n");
 121
 122 #ifndef WIN32
 123         if (pw)
 124                 free(pw);
 125 #endif
 126 }
 127
 128
 129
 130 /*
 131  * slashUsage
 132  *
 133  * print out help for the backslash commands
 134  */
 135
 136 #ifndef TIOCGWINSZ
 137 struct winsize
 138 {
 139         int                     ws_row;
 140         int                     ws_col;
 141 };
 142
 143 #endif
 144
 145 void
 146 slashUsage(PsqlSettings *pset)
 147 {
 148         bool            usePipe = false;
 149         const char *pagerenv;
 150         FILE       *fout;
 151         struct winsize screen_size;
 152
 153 #ifdef TIOCGWINSZ
 154         if (pset->notty == 0 &&
 155                 (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1 ||
 156                  screen_size.ws_col == 0 ||
 157                  screen_size.ws_row == 0))
 158         {
 159 #endif
 160                 screen_size.ws_row = 24;
 161                 screen_size.ws_col = 80;
 162 #ifdef TIOCGWINSZ
 163         }
 164 #endif
 165
 166         if (pset->notty == 0 &&
 167                 (pagerenv = getenv("PAGER")) &&
 168                 (pagerenv[0] != '\0') &&
 169                 screen_size.ws_row <= 36 &&
 170                 (fout = popen(pagerenv, "w")))
 171         {
 172                 usePipe = true;
 173                 pqsignal(SIGPIPE, SIG_IGN);
 174         }
 175         else
 176                 fout = stdout;
 177
 178         /* if you add/remove a line here, change the row test above */
 179         fprintf(fout, " \\?           -- help\n");
 180         fprintf(fout, " \\c[onnect] [<dbname>|- [<user>|?]] -- connect to new database (currently '%s')\n", PQdb(pset->db));
 181         fprintf(fout, " \\copy [binary] <table> [with oids] {from|to} <fname> [with delimiters '<char>']\n");
 182         fprintf(fout, " \\copyright   -- show PostgreSQL copyright\n");
 183         fprintf(fout, " \\d           -- list tables, views, and sequences\n");
 184         fprintf(fout, " \\distvS      -- list only indices/sequences/tables/views/system tables\n");
 185         fprintf(fout, " \\da          -- list aggregates\n");
 186         fprintf(fout, " \\dd [<object>]- list comment for table, type, function, or operator\n");
 187         fprintf(fout, " \\df          -- list functions\n");
 188         fprintf(fout, " \\do          -- list operators\n");
 189         fprintf(fout, " \\dT          -- list data types\n");
 190         fprintf(fout, " \\e [<fname>] -- edit the current query buffer or <fname> with external editor\n");
 191         fprintf(fout, " \\echo <text> -- write text to stdout\n");
 192         fprintf(fout, " \\g [<fname>] -- send query to backend (and results in <fname> or |pipe)\n");
 193         fprintf(fout, " \\h [<cmd>]   -- help on syntax of sql commands, * for all commands\n");
 194         fprintf(fout, " \\i <fname>   -- read and execute queries from filename\n");
 195         fprintf(fout, " \\l           -- list all databases\n");
 196         fprintf(fout, " \\lo_export, \\lo_import, \\lo_list, \\lo_unlink -- large object operations\n");
 197         fprintf(fout, " \\o [<fname>] -- send all query results to <fname>, or |pipe\n");
 198         fprintf(fout, " \\p           -- print the content of the current query buffer\n");
 199         fprintf(fout, " \\pset        -- set table output options\n");
 200         fprintf(fout, " \\q           -- quit\n");
 201         fprintf(fout, " \\qecho <text>-- write text to query output stream (see \\o)\n");
 202         fprintf(fout, " \\r           -- reset (clear) the query buffer\n");
 203         fprintf(fout, " \\s [<fname>] -- print history or save it in <fname>\n");
 204         fprintf(fout, " \\set <var> [<value>] -- set/unset internal variable\n");
 205         fprintf(fout, " \\t           -- don't show table headers or footers (currently %s)\n", ON(pset->popt.topt.tuples_only));
 206         fprintf(fout, " \\x           -- toggle expanded output (currently %s)\n", ON(pset->popt.topt.expanded));
 207         fprintf(fout, " \\w <fname>   -- write current query buffer to a file\n");
 208         fprintf(fout, " \\z           -- list table access permissions\n");
 209         fprintf(fout, " \\! [<cmd>]   -- shell escape or command\n");
 210
 211         if (usePipe)
 212         {
 213                 pclose(fout);
 214                 pqsignal(SIGPIPE, SIG_DFL);
 215         }
 216 }
 217
 218
 219
 220 /*
 221  * helpSQL -- help with SQL commands
 222  *
 223  */
 224 void
 225 helpSQL(const char *topic)
 226 {
 227         if (!topic || strlen(topic) == 0)
 228         {
 229                 char            left_center_right;      /* Which column we're displaying */
 230                 int                     i;                      /* Index into QL_HELP[] */
 231
 232                 puts("Syntax: \\h <cmd> or \\help <cmd>, where <cmd> is one of the following:");
 233
 234                 left_center_right = 'L';/* Start with left column */
 235                 i = 0;
 236                 while (QL_HELP[i].cmd != NULL)
 237                 {
 238                         switch (left_center_right)
 239                         {
 240                                 case 'L':
 241                                         printf("    %-25s", QL_HELP[i].cmd);
 242                                         left_center_right = 'C';
 243                                         break;
 244                                 case 'C':
 245                                         printf("%-25s", QL_HELP[i].cmd);
 246                                         left_center_right = 'R';
 247                                         break;
 248                                 case 'R':
 249                                         printf("%-25s\n", QL_HELP[i].cmd);
 250                                         left_center_right = 'L';
 251                                         break;
 252                         }
 253                         i++;
 254                 }
 255                 if (left_center_right != 'L')
 256                         puts("\n");
 257                 puts("Or type \\h * for a complete description of all commands.");
 258         }
 259
 260
 261         else
 262         {
 263                 int                     i;
 264                 bool            help_found = false;
 265
 266                 for (i = 0; QL_HELP[i].cmd; i++)
 267                 {
 268                         if (strcasecmp(QL_HELP[i].cmd, topic) == 0 ||
 269                                 strcmp(topic, "*") == 0)
 270                         {
 271                                 help_found = true;
 272                                 printf("Command: %s\nDescription: %s\nSyntax:\n%s\n\n",
 273                                          QL_HELP[i].cmd, QL_HELP[i].help, QL_HELP[i].syntax);
 274                         }
 275                 }
 276
 277                 if (!help_found)
 278                         printf("No help available for '%s'.\nTry \\h with no arguments to see available help.\n", topic);
 279         }
 280 }
 281
 282
 283
 284
 285 void
 286 print_copyright(void)
 287 {
 288         puts(
 289                  "
 290                  PostgreSQL Data Base Management System
 291
 292                  Copyright(c) 1996 - 9 PostgreSQL Global Development Group
 293
 294                  This software is based on Postgres95, formerly known as Postgres, which
 295                  contains the following notice:
 296
 297                  Copyright(c) 1994 - 7 Regents of the University of California
 298
 299         Permission to use, copy, modify, and distribute this software and its
 300                  documentation for any purpose, without fee, and without a written agreement
 301                  is hereby granted, provided that the above copyright notice and this paragraph
 302                  and the following two paragraphs appear in all copies.
 303
 304                  IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
 305                  DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST
 306                  PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
 307                  THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
 308                  DAMAGE.
 309
 310                  THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
 311                  BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 312                  PARTICULAR PURPOSE.THE SOFTWARE PROVIDED HEREUNDER IS ON AN \"AS IS\"  BASIS,
 313                  AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,
 314                  SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 315
 316                  (end of terms) "
 317         );
 318 }