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