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