PostgreSQL Source Code  git master
help.c
Go to the documentation of this file.
1 /*
2  * psql - the PostgreSQL interactive terminal
3  *
4  * Copyright (c) 2000-2019, PostgreSQL Global Development Group
5  *
6  * src/bin/psql/help.c
7  */
8 #include "postgres_fe.h"
9 
10 #ifndef WIN32
11 #include <unistd.h> /* for geteuid() */
12 #else
13 #include <win32.h>
14 #endif
15 
16 #ifndef WIN32
17 #include <sys/ioctl.h> /* for ioctl() */
18 #endif
19 
20 #ifdef HAVE_TERMIOS_H
21 #include <termios.h>
22 #endif
23 
24 #include "common/logging.h"
25 #include "common/username.h"
26 
27 #include "common.h"
28 #include "help.h"
29 #include "input.h"
30 #include "settings.h"
31 #include "sql_help.h"
32 
33 /*
34  * PLEASE:
35  * If you change something in this file, also make the same changes
36  * in the DocBook documentation, file ref/psql-ref.sgml. If you don't
37  * know how to do it, please find someone who can help you.
38  */
39 
40 
41 /*
42  * usage
43  *
44  * print out command line arguments
45  */
46 #define ON(var) (var ? _("on") : _("off"))
47 
48 void
49 usage(unsigned short int pager)
50 {
51  const char *env;
52  const char *user;
53  char *errstr;
54  FILE *output;
55 
56  /* Find default user, in case we need it. */
57  user = getenv("PGUSER");
58  if (!user)
59  {
60  user = get_user_name(&errstr);
61  if (!user)
62  {
63  pg_log_fatal("%s", errstr);
64  exit(EXIT_FAILURE);
65  }
66  }
67 
68  /*
69  * Keep this line count in sync with the number of lines printed below!
70  * Use "psql --help=options | wc" to count correctly.
71  */
72  output = PageOutput(62, pager ? &(pset.popt.topt) : NULL);
73 
74  fprintf(output, _("psql is the PostgreSQL interactive terminal.\n\n"));
75  fprintf(output, _("Usage:\n"));
76  fprintf(output, _(" psql [OPTION]... [DBNAME [USERNAME]]\n\n"));
77 
78  fprintf(output, _("General options:\n"));
79  /* Display default database */
80  env = getenv("PGDATABASE");
81  if (!env)
82  env = user;
83  fprintf(output, _(" -c, --command=COMMAND run only single command (SQL or internal) and exit\n"));
84  fprintf(output, _(" -d, --dbname=DBNAME database name to connect to (default: \"%s\")\n"), env);
85  fprintf(output, _(" -f, --file=FILENAME execute commands from file, then exit\n"));
86  fprintf(output, _(" -l, --list list available databases, then exit\n"));
87  fprintf(output, _(" -v, --set=, --variable=NAME=VALUE\n"
88  " set psql variable NAME to VALUE\n"
89  " (e.g., -v ON_ERROR_STOP=1)\n"));
90  fprintf(output, _(" -V, --version output version information, then exit\n"));
91  fprintf(output, _(" -X, --no-psqlrc do not read startup file (~/.psqlrc)\n"));
92  fprintf(output, _(" -1 (\"one\"), --single-transaction\n"
93  " execute as a single transaction (if non-interactive)\n"));
94  fprintf(output, _(" -?, --help[=options] show this help, then exit\n"));
95  fprintf(output, _(" --help=commands list backslash commands, then exit\n"));
96  fprintf(output, _(" --help=variables list special variables, then exit\n"));
97 
98  fprintf(output, _("\nInput and output options:\n"));
99  fprintf(output, _(" -a, --echo-all echo all input from script\n"));
100  fprintf(output, _(" -b, --echo-errors echo failed commands\n"));
101  fprintf(output, _(" -e, --echo-queries echo commands sent to server\n"));
102  fprintf(output, _(" -E, --echo-hidden display queries that internal commands generate\n"));
103  fprintf(output, _(" -L, --log-file=FILENAME send session log to file\n"));
104  fprintf(output, _(" -n, --no-readline disable enhanced command line editing (readline)\n"));
105  fprintf(output, _(" -o, --output=FILENAME send query results to file (or |pipe)\n"));
106  fprintf(output, _(" -q, --quiet run quietly (no messages, only query output)\n"));
107  fprintf(output, _(" -s, --single-step single-step mode (confirm each query)\n"));
108  fprintf(output, _(" -S, --single-line single-line mode (end of line terminates SQL command)\n"));
109 
110  fprintf(output, _("\nOutput format options:\n"));
111  fprintf(output, _(" -A, --no-align unaligned table output mode\n"));
112  fprintf(output, _(" --csv CSV (Comma-Separated Values) table output mode\n"));
113  fprintf(output, _(" -F, --field-separator=STRING\n"
114  " field separator for unaligned output (default: \"%s\")\n"),
116  fprintf(output, _(" -H, --html HTML table output mode\n"));
117  fprintf(output, _(" -P, --pset=VAR[=ARG] set printing option VAR to ARG (see \\pset command)\n"));
118  fprintf(output, _(" -R, --record-separator=STRING\n"
119  " record separator for unaligned output (default: newline)\n"));
120  fprintf(output, _(" -t, --tuples-only print rows only\n"));
121  fprintf(output, _(" -T, --table-attr=TEXT set HTML table tag attributes (e.g., width, border)\n"));
122  fprintf(output, _(" -x, --expanded turn on expanded table output\n"));
123  fprintf(output, _(" -z, --field-separator-zero\n"
124  " set field separator for unaligned output to zero byte\n"));
125  fprintf(output, _(" -0, --record-separator-zero\n"
126  " set record separator for unaligned output to zero byte\n"));
127 
128  fprintf(output, _("\nConnection options:\n"));
129  /* Display default host */
130  env = getenv("PGHOST");
131  fprintf(output, _(" -h, --host=HOSTNAME database server host or socket directory (default: \"%s\")\n"),
132  env ? env : _("local socket"));
133  /* Display default port */
134  env = getenv("PGPORT");
135  fprintf(output, _(" -p, --port=PORT database server port (default: \"%s\")\n"),
136  env ? env : DEF_PGPORT_STR);
137  /* Display default user */
138  env = getenv("PGUSER");
139  if (!env)
140  env = user;
141  fprintf(output, _(" -U, --username=USERNAME database user name (default: \"%s\")\n"), env);
142  fprintf(output, _(" -w, --no-password never prompt for password\n"));
143  fprintf(output, _(" -W, --password force password prompt (should happen automatically)\n"));
144 
145  fprintf(output, _("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n"
146  "commands) from within psql, or consult the psql section in the PostgreSQL\n"
147  "documentation.\n\n"));
148  fprintf(output, _("Report bugs to <pgsql-bugs@lists.postgresql.org>.\n"));
149 
150  ClosePager(output);
151 }
152 
153 
154 /*
155  * slashUsage
156  *
157  * print out help for the backslash commands
158  */
159 void
160 slashUsage(unsigned short int pager)
161 {
162  FILE *output;
163  char *currdb;
164 
165  currdb = PQdb(pset.db);
166 
167  /*
168  * Keep this line count in sync with the number of lines printed below!
169  * Use "psql --help=commands | wc" to count correctly. It's okay to count
170  * the USE_READLINE line even in builds without that.
171  */
172  output = PageOutput(128, pager ? &(pset.popt.topt) : NULL);
173 
174  fprintf(output, _("General\n"));
175  fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n"));
176  fprintf(output, _(" \\crosstabview [COLUMNS] execute query and display results in crosstab\n"));
177  fprintf(output, _(" \\errverbose show most recent error message at maximum verbosity\n"));
178  fprintf(output, _(" \\g [FILE] or ; execute query (and send results to file or |pipe)\n"));
179  fprintf(output, _(" \\gdesc describe result of query, without executing it\n"));
180  fprintf(output, _(" \\gexec execute query, then execute each value in its result\n"));
181  fprintf(output, _(" \\gset [PREFIX] execute query and store results in psql variables\n"));
182  fprintf(output, _(" \\gx [FILE] as \\g, but forces expanded output mode\n"));
183  fprintf(output, _(" \\q quit psql\n"));
184  fprintf(output, _(" \\watch [SEC] execute query every SEC seconds\n"));
185  fprintf(output, "\n");
186 
187  fprintf(output, _("Help\n"));
188 
189  fprintf(output, _(" \\? [commands] show help on backslash commands\n"));
190  fprintf(output, _(" \\? options show help on psql command-line options\n"));
191  fprintf(output, _(" \\? variables show help on special variables\n"));
192  fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n"));
193  fprintf(output, "\n");
194 
195  fprintf(output, _("Query Buffer\n"));
196  fprintf(output, _(" \\e [FILE] [LINE] edit the query buffer (or file) with external editor\n"));
197  fprintf(output, _(" \\ef [FUNCNAME [LINE]] edit function definition with external editor\n"));
198  fprintf(output, _(" \\ev [VIEWNAME [LINE]] edit view definition with external editor\n"));
199  fprintf(output, _(" \\p show the contents of the query buffer\n"));
200  fprintf(output, _(" \\r reset (clear) the query buffer\n"));
201 #ifdef USE_READLINE
202  fprintf(output, _(" \\s [FILE] display history or save it to file\n"));
203 #endif
204  fprintf(output, _(" \\w FILE write query buffer to file\n"));
205  fprintf(output, "\n");
206 
207  fprintf(output, _("Input/Output\n"));
208  fprintf(output, _(" \\copy ... perform SQL COPY with data stream to the client host\n"));
209  fprintf(output, _(" \\echo [-n] [STRING] write string to standard output (-n for no newline)\n"));
210  fprintf(output, _(" \\i FILE execute commands from file\n"));
211  fprintf(output, _(" \\ir FILE as \\i, but relative to location of current script\n"));
212  fprintf(output, _(" \\o [FILE] send all query results to file or |pipe\n"));
213  fprintf(output, _(" \\qecho [-n] [STRING] write string to \\o output stream (-n for no newline)\n"));
214  fprintf(output, _(" \\warn [-n] [STRING] write string to standard error (-n for no newline)\n"));
215  fprintf(output, "\n");
216 
217  fprintf(output, _("Conditional\n"));
218  fprintf(output, _(" \\if EXPR begin conditional block\n"));
219  fprintf(output, _(" \\elif EXPR alternative within current conditional block\n"));
220  fprintf(output, _(" \\else final alternative within current conditional block\n"));
221  fprintf(output, _(" \\endif end conditional block\n"));
222  fprintf(output, "\n");
223 
224  fprintf(output, _("Informational\n"));
225  fprintf(output, _(" (options: S = show system objects, + = additional detail)\n"));
226  fprintf(output, _(" \\d[S+] list tables, views, and sequences\n"));
227  fprintf(output, _(" \\d[S+] NAME describe table, view, sequence, or index\n"));
228  fprintf(output, _(" \\da[S] [PATTERN] list aggregates\n"));
229  fprintf(output, _(" \\dA[+] [PATTERN] list access methods\n"));
230  fprintf(output, _(" \\db[+] [PATTERN] list tablespaces\n"));
231  fprintf(output, _(" \\dc[S+] [PATTERN] list conversions\n"));
232  fprintf(output, _(" \\dC[+] [PATTERN] list casts\n"));
233  fprintf(output, _(" \\dd[S] [PATTERN] show object descriptions not displayed elsewhere\n"));
234  fprintf(output, _(" \\dD[S+] [PATTERN] list domains\n"));
235  fprintf(output, _(" \\ddp [PATTERN] list default privileges\n"));
236  fprintf(output, _(" \\dE[S+] [PATTERN] list foreign tables\n"));
237  fprintf(output, _(" \\det[+] [PATTERN] list foreign tables\n"));
238  fprintf(output, _(" \\des[+] [PATTERN] list foreign servers\n"));
239  fprintf(output, _(" \\deu[+] [PATTERN] list user mappings\n"));
240  fprintf(output, _(" \\dew[+] [PATTERN] list foreign-data wrappers\n"));
241  fprintf(output, _(" \\df[anptw][S+] [PATRN] list [only agg/normal/procedures/trigger/window] functions\n"));
242  fprintf(output, _(" \\dF[+] [PATTERN] list text search configurations\n"));
243  fprintf(output, _(" \\dFd[+] [PATTERN] list text search dictionaries\n"));
244  fprintf(output, _(" \\dFp[+] [PATTERN] list text search parsers\n"));
245  fprintf(output, _(" \\dFt[+] [PATTERN] list text search templates\n"));
246  fprintf(output, _(" \\dg[S+] [PATTERN] list roles\n"));
247  fprintf(output, _(" \\di[S+] [PATTERN] list indexes\n"));
248  fprintf(output, _(" \\dl list large objects, same as \\lo_list\n"));
249  fprintf(output, _(" \\dL[S+] [PATTERN] list procedural languages\n"));
250  fprintf(output, _(" \\dm[S+] [PATTERN] list materialized views\n"));
251  fprintf(output, _(" \\dn[S+] [PATTERN] list schemas\n"));
252  fprintf(output, _(" \\do[S] [PATTERN] list operators\n"));
253  fprintf(output, _(" \\dO[S+] [PATTERN] list collations\n"));
254  fprintf(output, _(" \\dp [PATTERN] list table, view, and sequence access privileges\n"));
255  fprintf(output, _(" \\dP[itn+] [PATTERN] list [only index/table] partitioned relations [n=nested]\n"));
256  fprintf(output, _(" \\drds [PATRN1 [PATRN2]] list per-database role settings\n"));
257  fprintf(output, _(" \\dRp[+] [PATTERN] list replication publications\n"));
258  fprintf(output, _(" \\dRs[+] [PATTERN] list replication subscriptions\n"));
259  fprintf(output, _(" \\ds[S+] [PATTERN] list sequences\n"));
260  fprintf(output, _(" \\dt[S+] [PATTERN] list tables\n"));
261  fprintf(output, _(" \\dT[S+] [PATTERN] list data types\n"));
262  fprintf(output, _(" \\du[S+] [PATTERN] list roles\n"));
263  fprintf(output, _(" \\dv[S+] [PATTERN] list views\n"));
264  fprintf(output, _(" \\dx[+] [PATTERN] list extensions\n"));
265  fprintf(output, _(" \\dy [PATTERN] list event triggers\n"));
266  fprintf(output, _(" \\l[+] [PATTERN] list databases\n"));
267  fprintf(output, _(" \\sf[+] FUNCNAME show a function's definition\n"));
268  fprintf(output, _(" \\sv[+] VIEWNAME show a view's definition\n"));
269  fprintf(output, _(" \\z [PATTERN] same as \\dp\n"));
270  fprintf(output, "\n");
271 
272  fprintf(output, _("Formatting\n"));
273  fprintf(output, _(" \\a toggle between unaligned and aligned output mode\n"));
274  fprintf(output, _(" \\C [STRING] set table title, or unset if none\n"));
275  fprintf(output, _(" \\f [STRING] show or set field separator for unaligned query output\n"));
276  fprintf(output, _(" \\H toggle HTML output mode (currently %s)\n"),
278  fprintf(output, _(" \\pset [NAME [VALUE]] set table output option\n"
279  " (border|columns|csv_fieldsep|expanded|fieldsep|\n"
280  " fieldsep_zero|footer|format|linestyle|null|\n"
281  " numericlocale|pager|pager_min_lines|recordsep|\n"
282  " recordsep_zero|tableattr|title|tuples_only|\n"
283  " unicode_border_linestyle|unicode_column_linestyle|\n"
284  " unicode_header_linestyle)\n"));
285  fprintf(output, _(" \\t [on|off] show only rows (currently %s)\n"),
287  fprintf(output, _(" \\T [STRING] set HTML <table> tag attributes, or unset if none\n"));
288  fprintf(output, _(" \\x [on|off|auto] toggle expanded output (currently %s)\n"),
289  pset.popt.topt.expanded == 2 ? "auto" : ON(pset.popt.topt.expanded));
290  fprintf(output, "\n");
291 
292  fprintf(output, _("Connection\n"));
293  if (currdb)
294  fprintf(output, _(" \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
295  " connect to new database (currently \"%s\")\n"),
296  currdb);
297  else
298  fprintf(output, _(" \\c[onnect] {[DBNAME|- USER|- HOST|- PORT|-] | conninfo}\n"
299  " connect to new database (currently no connection)\n"));
300  fprintf(output, _(" \\conninfo display information about current connection\n"));
301  fprintf(output, _(" \\encoding [ENCODING] show or set client encoding\n"));
302  fprintf(output, _(" \\password [USERNAME] securely change the password for a user\n"));
303  fprintf(output, "\n");
304 
305  fprintf(output, _("Operating System\n"));
306  fprintf(output, _(" \\cd [DIR] change the current working directory\n"));
307  fprintf(output, _(" \\setenv NAME [VALUE] set or unset environment variable\n"));
308  fprintf(output, _(" \\timing [on|off] toggle timing of commands (currently %s)\n"),
309  ON(pset.timing));
310  fprintf(output, _(" \\! [COMMAND] execute command in shell or start interactive shell\n"));
311  fprintf(output, "\n");
312 
313  fprintf(output, _("Variables\n"));
314  fprintf(output, _(" \\prompt [TEXT] NAME prompt user to set internal variable\n"));
315  fprintf(output, _(" \\set [NAME [VALUE]] set internal variable, or list all if no parameters\n"));
316  fprintf(output, _(" \\unset NAME unset (delete) internal variable\n"));
317  fprintf(output, "\n");
318 
319  fprintf(output, _("Large Objects\n"));
320  fprintf(output, _(" \\lo_export LOBOID FILE\n"
321  " \\lo_import FILE [COMMENT]\n"
322  " \\lo_list\n"
323  " \\lo_unlink LOBOID large object operations\n"));
324 
325  ClosePager(output);
326 }
327 
328 
329 /*
330  * helpVariables
331  *
332  * show list of available variables (options) from command line
333  */
334 void
335 helpVariables(unsigned short int pager)
336 {
337  FILE *output;
338 
339  /*
340  * Keep this line count in sync with the number of lines printed below!
341  * Use "psql --help=variables | wc" to count correctly; but notice that
342  * Windows builds currently print one more line than non-Windows builds.
343  * Using the larger number is fine.
344  */
345  output = PageOutput(158, pager ? &(pset.popt.topt) : NULL);
346 
347  fprintf(output, _("List of specially treated variables\n\n"));
348 
349  fprintf(output, _("psql variables:\n"));
350  fprintf(output, _("Usage:\n"));
351  fprintf(output, _(" psql --set=NAME=VALUE\n or \\set NAME VALUE inside psql\n\n"));
352 
353  fprintf(output, _(" AUTOCOMMIT\n"
354  " if set, successful SQL commands are automatically committed\n"));
355  fprintf(output, _(" COMP_KEYWORD_CASE\n"
356  " determines the case used to complete SQL key words\n"
357  " [lower, upper, preserve-lower, preserve-upper]\n"));
358  fprintf(output, _(" DBNAME\n"
359  " the currently connected database name\n"));
360  fprintf(output, _(" ECHO\n"
361  " controls what input is written to standard output\n"
362  " [all, errors, none, queries]\n"));
363  fprintf(output, _(" ECHO_HIDDEN\n"
364  " if set, display internal queries executed by backslash commands;\n"
365  " if set to \"noexec\", just show them without execution\n"));
366  fprintf(output, _(" ENCODING\n"
367  " current client character set encoding\n"));
368  fprintf(output, _(" ERROR\n"
369  " true if last query failed, else false\n"));
370  fprintf(output, _(" FETCH_COUNT\n"
371  " the number of result rows to fetch and display at a time (0 = unlimited)\n"));
372  fprintf(output, _(" HIDE_TABLEAM\n"
373  " if set, table access methods are not displayed\n"));
374  fprintf(output, _(" HISTCONTROL\n"
375  " controls command history [ignorespace, ignoredups, ignoreboth]\n"));
376  fprintf(output, _(" HISTFILE\n"
377  " file name used to store the command history\n"));
378  fprintf(output, _(" HISTSIZE\n"
379  " maximum number of commands to store in the command history\n"));
380  fprintf(output, _(" HOST\n"
381  " the currently connected database server host\n"));
382  fprintf(output, _(" IGNOREEOF\n"
383  " number of EOFs needed to terminate an interactive session\n"));
384  fprintf(output, _(" LASTOID\n"
385  " value of the last affected OID\n"));
386  fprintf(output, _(" LAST_ERROR_MESSAGE\n"
387  " LAST_ERROR_SQLSTATE\n"
388  " message and SQLSTATE of last error, or empty string and \"00000\" if none\n"));
389  fprintf(output, _(" ON_ERROR_ROLLBACK\n"
390  " if set, an error doesn't stop a transaction (uses implicit savepoints)\n"));
391  fprintf(output, _(" ON_ERROR_STOP\n"
392  " stop batch execution after error\n"));
393  fprintf(output, _(" PORT\n"
394  " server port of the current connection\n"));
395  fprintf(output, _(" PROMPT1\n"
396  " specifies the standard psql prompt\n"));
397  fprintf(output, _(" PROMPT2\n"
398  " specifies the prompt used when a statement continues from a previous line\n"));
399  fprintf(output, _(" PROMPT3\n"
400  " specifies the prompt used during COPY ... FROM STDIN\n"));
401  fprintf(output, _(" QUIET\n"
402  " run quietly (same as -q option)\n"));
403  fprintf(output, _(" ROW_COUNT\n"
404  " number of rows returned or affected by last query, or 0\n"));
405  fprintf(output, _(" SERVER_VERSION_NAME\n"
406  " SERVER_VERSION_NUM\n"
407  " server's version (in short string or numeric format)\n"));
408  fprintf(output, _(" SHOW_CONTEXT\n"
409  " controls display of message context fields [never, errors, always]\n"));
410  fprintf(output, _(" SINGLELINE\n"
411  " if set, end of line terminates SQL commands (same as -S option)\n"));
412  fprintf(output, _(" SINGLESTEP\n"
413  " single-step mode (same as -s option)\n"));
414  fprintf(output, _(" SQLSTATE\n"
415  " SQLSTATE of last query, or \"00000\" if no error\n"));
416  fprintf(output, _(" USER\n"
417  " the currently connected database user\n"));
418  fprintf(output, _(" VERBOSITY\n"
419  " controls verbosity of error reports [default, verbose, terse, sqlstate]\n"));
420  fprintf(output, _(" VERSION\n"
421  " VERSION_NAME\n"
422  " VERSION_NUM\n"
423  " psql's version (in verbose string, short string, or numeric format)\n"));
424 
425  fprintf(output, _("\nDisplay settings:\n"));
426  fprintf(output, _("Usage:\n"));
427  fprintf(output, _(" psql --pset=NAME[=VALUE]\n or \\pset NAME [VALUE] inside psql\n\n"));
428 
429  fprintf(output, _(" border\n"
430  " border style (number)\n"));
431  fprintf(output, _(" columns\n"
432  " target width for the wrapped format\n"));
433  fprintf(output, _(" expanded (or x)\n"
434  " expanded output [on, off, auto]\n"));
435  fprintf(output, _(" fieldsep\n"
436  " field separator for unaligned output (default \"%s\")\n"),
438  fprintf(output, _(" fieldsep_zero\n"
439  " set field separator for unaligned output to a zero byte\n"));
440  fprintf(output, _(" footer\n"
441  " enable or disable display of the table footer [on, off]\n"));
442  fprintf(output, _(" format\n"
443  " set output format [unaligned, aligned, wrapped, html, asciidoc, ...]\n"));
444  fprintf(output, _(" linestyle\n"
445  " set the border line drawing style [ascii, old-ascii, unicode]\n"));
446  fprintf(output, _(" null\n"
447  " set the string to be printed in place of a null value\n"));
448  fprintf(output, _(" numericlocale\n"
449  " enable display of a locale-specific character to separate groups of digits\n"));
450  fprintf(output, _(" pager\n"
451  " control when an external pager is used [yes, no, always]\n"));
452  fprintf(output, _(" recordsep\n"
453  " record (line) separator for unaligned output\n"));
454  fprintf(output, _(" recordsep_zero\n"
455  " set record separator for unaligned output to a zero byte\n"));
456  fprintf(output, _(" tableattr (or T)\n"
457  " specify attributes for table tag in html format, or proportional\n"
458  " column widths for left-aligned data types in latex-longtable format\n"));
459  fprintf(output, _(" title\n"
460  " set the table title for subsequently printed tables\n"));
461  fprintf(output, _(" tuples_only\n"
462  " if set, only actual table data is shown\n"));
463  fprintf(output, _(" unicode_border_linestyle\n"
464  " unicode_column_linestyle\n"
465  " unicode_header_linestyle\n"
466  " set the style of Unicode line drawing [single, double]\n"));
467 
468  fprintf(output, _("\nEnvironment variables:\n"));
469  fprintf(output, _("Usage:\n"));
470 
471 #ifndef WIN32
472  fprintf(output, _(" NAME=VALUE [NAME=VALUE] psql ...\n or \\setenv NAME [VALUE] inside psql\n\n"));
473 #else
474  fprintf(output, _(" set NAME=VALUE\n psql ...\n or \\setenv NAME [VALUE] inside psql\n\n"));
475 #endif
476 
477  fprintf(output, _(" COLUMNS\n"
478  " number of columns for wrapped format\n"));
479  fprintf(output, _(" PGAPPNAME\n"
480  " same as the application_name connection parameter\n"));
481  fprintf(output, _(" PGDATABASE\n"
482  " same as the dbname connection parameter\n"));
483  fprintf(output, _(" PGHOST\n"
484  " same as the host connection parameter\n"));
485  fprintf(output, _(" PGPASSWORD\n"
486  " connection password (not recommended)\n"));
487  fprintf(output, _(" PGPASSFILE\n"
488  " password file name\n"));
489  fprintf(output, _(" PGPORT\n"
490  " same as the port connection parameter\n"));
491  fprintf(output, _(" PGUSER\n"
492  " same as the user connection parameter\n"));
493  fprintf(output, _(" PSQL_EDITOR, EDITOR, VISUAL\n"
494  " editor used by the \\e, \\ef, and \\ev commands\n"));
495  fprintf(output, _(" PSQL_EDITOR_LINENUMBER_ARG\n"
496  " how to specify a line number when invoking the editor\n"));
497  fprintf(output, _(" PSQL_HISTORY\n"
498  " alternative location for the command history file\n"));
499  fprintf(output, _(" PSQL_PAGER, PAGER\n"
500  " name of external pager program\n"));
501  fprintf(output, _(" PSQLRC\n"
502  " alternative location for the user's .psqlrc file\n"));
503  fprintf(output, _(" SHELL\n"
504  " shell used by the \\! command\n"));
505  fprintf(output, _(" TMPDIR\n"
506  " directory for temporary files\n"));
507 
508  ClosePager(output);
509 }
510 
511 
512 /*
513  * helpSQL -- help with SQL commands
514  *
515  * Note: we assume caller removed any trailing spaces in "topic".
516  */
517 void
518 helpSQL(const char *topic, unsigned short int pager)
519 {
520 #define VALUE_OR_NULL(a) ((a) ? (a) : "")
521 
522  if (!topic || strlen(topic) == 0)
523  {
524  /* Print all the available command names */
525  int screen_width;
526  int ncolumns;
527  int nrows;
528  FILE *output;
529  int i;
530  int j;
531 
532 #ifdef TIOCGWINSZ
533  struct winsize screen_size;
534 
535  if (ioctl(fileno(stdout), TIOCGWINSZ, &screen_size) == -1)
536  screen_width = 80; /* ioctl failed, assume 80 */
537  else
538  screen_width = screen_size.ws_col;
539 #else
540  screen_width = 80; /* default assumption */
541 #endif
542 
543  ncolumns = (screen_width - 3) / (QL_MAX_CMD_LEN + 1);
544  ncolumns = Max(ncolumns, 1);
545  nrows = (QL_HELP_COUNT + (ncolumns - 1)) / ncolumns;
546 
547  output = PageOutput(nrows + 1, pager ? &(pset.popt.topt) : NULL);
548 
549  fputs(_("Available help:\n"), output);
550 
551  for (i = 0; i < nrows; i++)
552  {
553  fprintf(output, " ");
554  for (j = 0; j < ncolumns - 1; j++)
555  fprintf(output, "%-*s",
556  QL_MAX_CMD_LEN + 1,
557  VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
558  if (i + j * nrows < QL_HELP_COUNT)
559  fprintf(output, "%s",
560  VALUE_OR_NULL(QL_HELP[i + j * nrows].cmd));
561  fputc('\n', output);
562  }
563 
564  ClosePager(output);
565  }
566  else
567  {
568  int i,
569  j,
570  x = 0;
571  bool help_found = false;
572  FILE *output = NULL;
573  size_t len,
574  wordlen;
575  int nl_count = 0;
576 
577  /*
578  * We first try exact match, then first + second words, then first
579  * word only.
580  */
581  len = strlen(topic);
582 
583  for (x = 1; x <= 3; x++)
584  {
585  if (x > 1) /* Nothing on first pass - try the opening
586  * word(s) */
587  {
588  wordlen = j = 1;
589  while (topic[j] != ' ' && j++ < len)
590  wordlen++;
591  if (x == 2)
592  {
593  j++;
594  while (topic[j] != ' ' && j++ <= len)
595  wordlen++;
596  }
597  if (wordlen >= len) /* Don't try again if the same word */
598  {
599  if (!output)
600  output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
601  break;
602  }
603  len = wordlen;
604  }
605 
606  /* Count newlines for pager */
607  for (i = 0; QL_HELP[i].cmd; i++)
608  {
609  if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
610  strcmp(topic, "*") == 0)
611  {
612  nl_count += 5 + QL_HELP[i].nl_count;
613 
614  /* If we have an exact match, exit. Fixes \h SELECT */
615  if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
616  break;
617  }
618  }
619 
620  if (!output)
621  output = PageOutput(nl_count, pager ? &(pset.popt.topt) : NULL);
622 
623  for (i = 0; QL_HELP[i].cmd; i++)
624  {
625  if (pg_strncasecmp(topic, QL_HELP[i].cmd, len) == 0 ||
626  strcmp(topic, "*") == 0)
627  {
628  PQExpBufferData buffer;
629  char *url;
630 
631  initPQExpBuffer(&buffer);
632  QL_HELP[i].syntaxfunc(&buffer);
633  help_found = true;
634  url = psprintf("https://www.postgresql.org/docs/%s/%s.html",
635  strstr(PG_VERSION, "devel") ? "devel" : PG_MAJORVERSION,
636  QL_HELP[i].docbook_id);
637  fprintf(output, _("Command: %s\n"
638  "Description: %s\n"
639  "Syntax:\n%s\n\n"
640  "URL: %s\n\n"),
641  QL_HELP[i].cmd,
642  _(QL_HELP[i].help),
643  buffer.data,
644  url);
645  free(url);
646  /* If we have an exact match, exit. Fixes \h SELECT */
647  if (pg_strcasecmp(topic, QL_HELP[i].cmd) == 0)
648  break;
649  }
650  }
651  if (help_found) /* Don't keep trying if we got a match */
652  break;
653  }
654 
655  if (!help_found)
656  fprintf(output, _("No help available for \"%s\".\nTry \\h with no arguments to see available help.\n"), topic);
657 
658  ClosePager(output);
659  }
660 }
661 
662 
663 
664 void
666 {
667  puts(
668  "PostgreSQL Database Management System\n"
669  "(formerly known as Postgres, then as Postgres95)\n\n"
670  "Portions Copyright (c) 1996-2019, PostgreSQL Global Development Group\n\n"
671  "Portions Copyright (c) 1994, The Regents of the University of California\n\n"
672  "Permission to use, copy, modify, and distribute this software and its\n"
673  "documentation for any purpose, without fee, and without a written agreement\n"
674  "is hereby granted, provided that the above copyright notice and this\n"
675  "paragraph and the following two paragraphs appear in all copies.\n\n"
676  "IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR\n"
677  "DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING\n"
678  "LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS\n"
679  "DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE\n"
680  "POSSIBILITY OF SUCH DAMAGE.\n\n"
681  "THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,\n"
682  "INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\n"
683  "AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS\n"
684  "ON AN \"AS IS\" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO\n"
685  "PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.\n"
686  );
687 }
PGconn * db
Definition: settings.h:83
void print_copyright(void)
Definition: help.c:665
PsqlSettings pset
Definition: startup.c:35
static void output(uint64 loop_count)
void ClosePager(FILE *pagerpipe)
Definition: print.c:3045
char * psprintf(const char *fmt,...)
Definition: psprintf.c:46
enum printFormat format
Definition: print.h:99
printTableOpt topt
Definition: print.h:167
#define ON(var)
Definition: help.c:46
int pg_strcasecmp(const char *s1, const char *s2)
Definition: pgstrcasecmp.c:36
#define fprintf
Definition: port.h:196
void usage(unsigned short int pager)
Definition: help.c:49
const char * get_user_name(char **errstr)
Definition: username.c:31
int pg_strncasecmp(const char *s1, const char *s2, size_t n)
Definition: pgstrcasecmp.c:69
unsigned short int expanded
Definition: print.h:100
FILE * PageOutput(int lines, const printTableOpt *topt)
Definition: print.c:2994
bool tuples_only
Definition: print.h:108
void helpVariables(unsigned short int pager)
Definition: help.c:335
#define free(a)
Definition: header.h:65
char * PQdb(const PGconn *conn)
Definition: fe-connect.c:6446
#define Max(x, y)
Definition: c.h:898
printQueryOpt popt
Definition: settings.h:92
static char * user
Definition: pg_regress.c:95
void helpSQL(const char *topic, unsigned short int pager)
Definition: help.c:518
int i
#define EXIT_FAILURE
Definition: settings.h:154
#define DEFAULT_FIELD_SEP
Definition: settings.h:16
#define VALUE_OR_NULL(a)
#define _(x)
Definition: elog.c:84
void slashUsage(unsigned short int pager)
Definition: help.c:160
void initPQExpBuffer(PQExpBuffer str)
Definition: pqexpbuffer.c:92
#define pg_log_fatal(...)
Definition: logging.h:75