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