Adding upstream version 13.4.upstream/13.4upstream

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

1 files changed, 156 insertions, 0 deletions

diff --git a/doc/src/sgml/man1/pg_checksums.1 b/doc/src/sgml/man1/pg_checksums.1
new file mode 100644
index 0000000..11602de
--- /dev/null
+++ b/doc/src/sgml/man1/pg_checksums.1
@@ -0,0 +1,156 @@
+'\" t
+.\"     Title: pg_checksums
+.\"    Author: The PostgreSQL Global Development Group
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      Date: 2021
+.\"    Manual: PostgreSQL 13.4 Documentation
+.\"    Source: PostgreSQL 13.4
+.\"  Language: English
+.\"
+.TH "PG_CHECKSUMS" "1" "2021" "PostgreSQL 13.4" "PostgreSQL 13.4 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_checksums \- enable, disable or check data checksums in a PostgreSQL database cluster
+.SH "SYNOPSIS"
+.HP \w'\fBpg_checksums\fR\ 'u
+\fBpg_checksums\fR [\fIoption\fR...] [[\fB\-D\fR | \fB\-\-pgdata\fR]\fIdatadir\fR]
+.SH "DESCRIPTION"
+.PP
+pg_checksums
+checks, enables or disables data checksums in a
+PostgreSQL
+cluster\&. The server must be shut down cleanly before running
+pg_checksums\&. When verifying checksums, the exit status is zero if there are no checksum errors, and nonzero if at least one checksum failure is detected\&. When enabling or disabling checksums, the exit status is nonzero if the operation failed\&.
+.PP
+When verifying checksums, every file in the cluster is scanned\&. When enabling checksums, every file in the cluster is rewritten in\-place\&. Disabling checksums only updates the file
+pg_control\&.
+.SH "OPTIONS"
+.PP
+The following command\-line options are available:
+.PP
+\fB\-D \fR\fB\fIdirectory\fR\fR
+.br
+\fB\-\-pgdata=\fR\fB\fIdirectory\fR\fR
+.RS 4
+Specifies the directory where the database cluster is stored\&.
+.RE
+.PP
+\fB\-c\fR
+.br
+\fB\-\-check\fR
+.RS 4
+Checks checksums\&. This is the default mode if nothing else is specified\&.
+.RE
+.PP
+\fB\-d\fR
+.br
+\fB\-\-disable\fR
+.RS 4
+Disables checksums\&.
+.RE
+.PP
+\fB\-e\fR
+.br
+\fB\-\-enable\fR
+.RS 4
+Enables checksums\&.
+.RE
+.PP
+\fB\-f \fR\fB\fIfilenode\fR\fR
+.br
+\fB\-\-filenode=\fR\fB\fIfilenode\fR\fR
+.RS 4
+Only validate checksums in the relation with filenode
+\fIfilenode\fR\&.
+.RE
+.PP
+\fB\-N\fR
+.br
+\fB\-\-no\-sync\fR
+.RS 4
+By default,
+\fBpg_checksums\fR
+will wait for all files to be written safely to disk\&. This option causes
+\fBpg_checksums\fR
+to return without waiting, which is faster, but means that a subsequent operating system crash can leave the updated data directory corrupt\&. Generally, this option is useful for testing but should not be used on a production installation\&. This option has no effect when using
+\-\-check\&.
+.RE
+.PP
+\fB\-P\fR
+.br
+\fB\-\-progress\fR
+.RS 4
+Enable progress reporting\&. Turning this on will deliver a progress report while checking or enabling checksums\&.
+.RE
+.PP
+\fB\-v\fR
+.br
+\fB\-\-verbose\fR
+.RS 4
+Enable verbose output\&. Lists all checked files\&.
+.RE
+.PP
+\fB\-V\fR
+.br
+\fB\-\-version\fR
+.RS 4
+Print the
+pg_checksums
+version and exit\&.
+.RE
+.PP
+\fB\-?\fR
+.br
+\fB\-\-help\fR
+.RS 4
+Show help about
+pg_checksums
+command line arguments, and exit\&.
+.RE
+.SH "ENVIRONMENT"
+.PP
+\fBPGDATA\fR
+.RS 4
+Specifies the directory where the database cluster is stored; can be overridden using the
+\fB\-D\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
+Enabling checksums in a large cluster can potentially take a long time\&. During this operation, the cluster or other programs that write to the data directory must not be started or else data loss may occur\&.
+.PP
+When using a replication setup with tools which perform direct copies of relation file blocks (for example
+\fBpg_rewind\fR(1)), enabling or disabling checksums can lead to page corruptions in the shape of incorrect checksums if the operation is not done consistently across all nodes\&. When enabling or disabling checksums in a replication setup, it is thus recommended to stop all the clusters before switching them all consistently\&. Destroying all standbys, performing the operation on the primary and finally recreating the standbys from scratch is also safe\&.
+.PP
+If
+pg_checksums
+is aborted or killed while enabling or disabling checksums, the cluster\*(Aqs data checksum configuration remains unchanged, and
+pg_checksums
+can be re\-run to perform the same operation\&.