← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to src/bin/psql/help.c

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

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