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