Adding upstream version 16.2.upstream/16.2

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 312 insertions, 0 deletions

diff --git a/doc/src/sgml/man1/pg_waldump.1 b/doc/src/sgml/man1/pg_waldump.1
new file mode 100644
index 0000000..1ffdfc0
--- /dev/null
+++ b/doc/src/sgml/man1/pg_waldump.1
@@ -0,0 +1,312 @@
+'\" t
+.\"     Title: pg_waldump
+.\"    Author: The PostgreSQL Global Development Group
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 2024
+.\"    Manual: PostgreSQL 16.2 Documentation
+.\"    Source: PostgreSQL 16.2
+.\"  Language: English
+.\"
+.TH "PG_WALDUMP" "1" "2024" "PostgreSQL 16.2" "PostgreSQL 16.2 Documentation"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+pg_waldump \- display a human\-readable rendering of the write\-ahead log of a PostgreSQL database cluster
+.SH "SYNOPSIS"
+.HP \w'\fBpg_waldump\fR\ 'u
+\fBpg_waldump\fR [\fBoption\fR...] [\fBstartseg\fR\ [\fBendseg\fR]]
+.SH "DESCRIPTION"
+.PP
+\fBpg_waldump\fR
+displays the write\-ahead log (WAL) and is mainly useful for debugging or educational purposes\&.
+.PP
+This utility can only be run by the user who installed the server, because it requires read\-only access to the data directory\&.
+.SH "OPTIONS"
+.PP
+The following command\-line options control the location and format of the output:
+.PP
+\fIstartseg\fR
+.RS 4
+Start reading at the specified WAL segment file\&. This implicitly determines the path in which files will be searched for, and the timeline to use\&.
+.RE
+.PP
+\fIendseg\fR
+.RS 4
+Stop after reading the specified WAL segment file\&.
+.RE
+.PP
+\fB\-b\fR
+.br
+\fB\-\-bkp\-details\fR
+.RS 4
+Output detailed information about backup blocks\&.
+.RE
+.PP
+\fB\-B \fR\fB\fIblock\fR\fR
+.br
+\fB\-\-block=\fR\fB\fIblock\fR\fR
+.RS 4
+Only display records that modify the given block\&. The relation must also be provided with
+\fB\-\-relation\fR
+or
+\fB\-R\fR\&.
+.RE
+.PP
+\fB\-e \fR\fB\fIend\fR\fR
+.br
+\fB\-\-end=\fR\fB\fIend\fR\fR
+.RS 4
+Stop reading at the specified WAL location, instead of reading to the end of the log stream\&.
+.RE
+.PP
+\fB\-f\fR
+.br
+\fB\-\-follow\fR
+.RS 4
+After reaching the end of valid WAL, keep polling once per second for new WAL to appear\&.
+.RE
+.PP
+\fB\-F \fR\fB\fIfork\fR\fR
+.br
+\fB\-\-fork=\fR\fB\fIfork\fR\fR
+.RS 4
+If provided, only display records that modify blocks in the given fork\&. The valid values are
+main
+for the main fork,
+fsm
+for the free space map,
+vm
+for the visibility map, and
+init
+for the init fork\&.
+.RE
+.PP
+\fB\-n \fR\fB\fIlimit\fR\fR
+.br
+\fB\-\-limit=\fR\fB\fIlimit\fR\fR
+.RS 4
+Display the specified number of records, then stop\&.
+.RE
+.PP
+\fB\-p \fR\fB\fIpath\fR\fR
+.br
+\fB\-\-path=\fR\fB\fIpath\fR\fR
+.RS 4
+Specifies a directory to search for WAL segment files or a directory with a
+pg_wal
+subdirectory that contains such files\&. The default is to search in the current directory, the
+pg_wal
+subdirectory of the current directory, and the
+pg_wal
+subdirectory of
+\fBPGDATA\fR\&.
+.RE
+.PP
+\fB\-q\fR
+.br
+\fB\-\-quiet\fR
+.RS 4
+Do not print any output, except for errors\&. This option can be useful when you want to know whether a range of WAL records can be successfully parsed but don\*(Aqt care about the record contents\&.
+.RE
+.PP
+\fB\-r \fR\fB\fIrmgr\fR\fR
+.br
+\fB\-\-rmgr=\fR\fB\fIrmgr\fR\fR
+.RS 4
+Only display records generated by the specified resource manager\&. You can specify the option multiple times to select multiple resource managers\&. If
+list
+is passed as name, print a list of valid resource manager names, and exit\&.
+.sp
+Extensions may define custom resource managers, but pg_waldump does not load the extension module and therefore does not recognize custom resource managers by name\&. Instead, you can specify the custom resource managers as
+custom###
+where "###" is the three\-digit resource manager ID\&. Names of this form will always be considered valid\&.
+.RE
+.PP
+\fB\-R \fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR
+.br
+\fB\-\-relation=\fR\fB\fItblspc\fR\fR\fB/\fR\fB\fIdb\fR\fR\fB/\fR\fB\fIrel\fR\fR
+.RS 4
+Only display records that modify blocks in the given relation\&. The relation is specified with tablespace OID, database OID, and relfilenode separated by slashes, for example
+1234/12345/12345\&. This is the same format used for relations in the program\*(Aqs output\&.
+.RE
+.PP
+\fB\-s \fR\fB\fIstart\fR\fR
+.br
+\fB\-\-start=\fR\fB\fIstart\fR\fR
+.RS 4
+WAL location at which to start reading\&. The default is to start reading the first valid WAL record found in the earliest file found\&.
+.RE
+.PP
+\fB\-t \fR\fB\fItimeline\fR\fR
+.br
+\fB\-\-timeline=\fR\fB\fItimeline\fR\fR
+.RS 4
+Timeline from which to read WAL records\&. The default is to use the value in
+\fIstartseg\fR, if that is specified; otherwise, the default is 1\&. The value can be specified in decimal or hexadecimal, for example
+17
+or
+0x11\&.
+.RE
+.PP
+\fB\-V\fR
+.br
+\fB\-\-version\fR
+.RS 4
+Print the
+pg_waldump
+version and exit\&.
+.RE
+.PP
+\fB\-w\fR
+.br
+\fB\-\-fullpage\fR
+.RS 4
+Only display records that include full page images\&.
+.RE
+.PP
+\fB\-x \fR\fB\fIxid\fR\fR
+.br
+\fB\-\-xid=\fR\fB\fIxid\fR\fR
+.RS 4
+Only display records marked with the given transaction ID\&.
+.RE
+.PP
+\fB\-z\fR
+.br
+\fB\-\-stats[=record]\fR
+.RS 4
+Display summary statistics (number and size of records and full\-page images) instead of individual records\&. Optionally generate statistics per\-record instead of per\-rmgr\&.
+.sp
+If
+pg_waldump
+is terminated by signal
+SIGINT
+(Control+C), the summary of the statistics computed is displayed up to the termination point\&. This operation is not supported on
+Windows\&.
+.RE
+.PP
+\fB\-\-save\-fullpage=\fR\fB\fIsave_path\fR\fR
+.RS 4
+Save full page images found in the WAL records to the
+\fIsave_path\fR
+directory\&. The images saved are subject to the same filtering and limiting criteria as the records displayed\&.
+.sp
+The full page images are saved with the following file name format:
+\fITIMELINE\fR\-\fILSN\fR\&.\fIRELTABLESPACE\fR\&.\fIDATOID\fR\&.\fIRELNODE\fR\&.\fIBLKNO\fR\fIFORK\fR
+The file names are composed of the following parts:
+.TS
+allbox tab(:);
+lB lB.
+T{
+Component
+T}:T{
+Description
+T}
+.T&
+l l
+l l
+l l
+l l
+l l
+l l
+l l.
+T{
+TIMELINE
+T}:T{
+The timeline of the WAL segment file where the record
+             is located formatted as one 8\-character hexadecimal number
+             %08X
+T}
+T{
+LSN
+T}:T{
+The LSN of the record with this image,
+             formatted as two 8\-character hexadecimal numbers
+             %08X\-%08X
+T}
+T{
+RELTABLESPACE
+T}:T{
+tablespace OID of the block
+T}
+T{
+DATOID
+T}:T{
+database OID of the block
+T}
+T{
+RELNODE
+T}:T{
+filenode of the block
+T}
+T{
+BLKNO
+T}:T{
+block number of the block
+T}
+T{
+FORK
+T}:T{
+The name of the fork the full page image came from, such as
+             _main, _fsm,
+             _vm, or _init\&.
+T}
+.TE
+.sp 1
+.RE
+.PP
+\fB\-?\fR
+.br
+\fB\-\-help\fR
+.RS 4
+Show help about
+pg_waldump
+command line arguments, and exit\&.
+.RE
+.SH "ENVIRONMENT"
+.PP
+\fBPGDATA\fR
+.RS 4
+Data directory; see also the
+\fB\-p\fR
+option\&.
+.RE
+.PP
+\fBPG_COLOR\fR
+.RS 4
+Specifies whether to use color in diagnostic messages\&. Possible values are
+always,
+auto
+and
+never\&.
+.RE
+.SH "NOTES"
+.PP
+Can give wrong results when the server is running\&.
+.PP
+Only the specified timeline is displayed (or the default, if none is specified)\&. Records in other timelines are ignored\&.
+.PP
+pg_waldump
+cannot read WAL files with suffix
+\&.partial\&. If those files need to be read,
+\&.partial
+suffix needs to be removed from the file name\&.
+.SH "SEE ALSO"
+Section\ \&30.6