PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
xlogrecord.h
Go to the documentation of this file.
1 /*
2  * xlogrecord.h
3  *
4  * Definitions for the WAL record format.
5  *
6  * Portions Copyright (c) 1996-2017, PostgreSQL Global Development Group
7  * Portions Copyright (c) 1994, Regents of the University of California
8  *
9  * src/include/access/xlogrecord.h
10  */
11 #ifndef XLOGRECORD_H
12 #define XLOGRECORD_H
13 
14 #include "access/rmgr.h"
15 #include "access/xlogdefs.h"
16 #include "port/pg_crc32c.h"
17 #include "storage/block.h"
18 #include "storage/relfilenode.h"
19 
20 /*
21  * The overall layout of an XLOG record is:
22  * Fixed-size header (XLogRecord struct)
23  * XLogRecordBlockHeader struct
24  * XLogRecordBlockHeader struct
25  * ...
26  * XLogRecordDataHeader[Short|Long] struct
27  * block data
28  * block data
29  * ...
30  * main data
31  *
32  * There can be zero or more XLogRecordBlockHeaders, and 0 or more bytes of
33  * rmgr-specific data not associated with a block. XLogRecord structs
34  * always start on MAXALIGN boundaries in the WAL files, but the rest of
35  * the fields are not aligned.
36  *
37  * The XLogRecordBlockHeader, XLogRecordDataHeaderShort and
38  * XLogRecordDataHeaderLong structs all begin with a single 'id' byte. It's
39  * used to distinguish between block references, and the main data structs.
40  */
41 typedef struct XLogRecord
42 {
43  uint32 xl_tot_len; /* total len of entire record */
44  TransactionId xl_xid; /* xact id */
45  XLogRecPtr xl_prev; /* ptr to previous record in log */
46  uint8 xl_info; /* flag bits, see below */
47  RmgrId xl_rmid; /* resource manager for this record */
48  /* 2 bytes of padding here, initialize to zero */
49  pg_crc32c xl_crc; /* CRC for this record */
50 
51  /* XLogRecordBlockHeaders and XLogRecordDataHeader follow, no padding */
52 
53 } XLogRecord;
54 
55 #define SizeOfXLogRecord (offsetof(XLogRecord, xl_crc) + sizeof(pg_crc32c))
56 
57 /*
58  * The high 4 bits in xl_info may be used freely by rmgr. The
59  * XLR_SPECIAL_REL_UPDATE and XLR_CHECK_CONSISTENCY bits can be passed by
60  * XLogInsert caller. The rest are set internally by XLogInsert.
61  */
62 #define XLR_INFO_MASK 0x0F
63 #define XLR_RMGR_INFO_MASK 0xF0
64 
65 /*
66  * If a WAL record modifies any relation files, in ways not covered by the
67  * usual block references, this flag is set. This is not used for anything
68  * by PostgreSQL itself, but it allows external tools that read WAL and keep
69  * track of modified blocks to recognize such special record types.
70  */
71 #define XLR_SPECIAL_REL_UPDATE 0x01
72 
73 /*
74  * Enforces consistency checks of replayed WAL at recovery. If enabled,
75  * each record will log a full-page write for each block modified by the
76  * record and will reuse it afterwards for consistency checks. The caller
77  * of XLogInsert can use this value if necessary, but if
78  * wal_consistency_checking is enabled for a rmgr this is set unconditionally.
79  */
80 #define XLR_CHECK_CONSISTENCY 0x02
81 
82 /*
83  * Header info for block data appended to an XLOG record.
84  *
85  * 'data_length' is the length of the rmgr-specific payload data associated
86  * with this block. It does not include the possible full page image, nor
87  * XLogRecordBlockHeader struct itself.
88  *
89  * Note that we don't attempt to align the XLogRecordBlockHeader struct!
90  * So, the struct must be copied to aligned local storage before use.
91  */
92 typedef struct XLogRecordBlockHeader
93 {
94  uint8 id; /* block reference ID */
95  uint8 fork_flags; /* fork within the relation, and flags */
96  uint16 data_length; /* number of payload bytes (not including page
97  * image) */
98 
99  /* If BKPBLOCK_HAS_IMAGE, an XLogRecordBlockImageHeader struct follows */
100  /* If BKPBLOCK_SAME_REL is not set, a RelFileNode follows */
101  /* BlockNumber follows */
103 
104 #define SizeOfXLogRecordBlockHeader (offsetof(XLogRecordBlockHeader, data_length) + sizeof(uint16))
105 
106 /*
107  * Additional header information when a full-page image is included
108  * (i.e. when BKPBLOCK_HAS_IMAGE is set).
109  *
110  * As a trivial form of data compression, the XLOG code is aware that
111  * PG data pages usually contain an unused "hole" in the middle, which
112  * contains only zero bytes. If the length of "hole" > 0 then we have removed
113  * such a "hole" from the stored data (and it's not counted in the
114  * XLOG record's CRC, either). Hence, the amount of block data actually
115  * present is BLCKSZ - the length of "hole" bytes.
116  *
117  * When wal_compression is enabled, a full page image which "hole" was
118  * removed is additionally compressed using PGLZ compression algorithm.
119  * This can reduce the WAL volume, but at some extra cost of CPU spent
120  * on the compression during WAL logging. In this case, since the "hole"
121  * length cannot be calculated by subtracting the number of page image bytes
122  * from BLCKSZ, basically it needs to be stored as an extra information.
123  * But when no "hole" exists, we can assume that the "hole" length is zero
124  * and no such an extra information needs to be stored. Note that
125  * the original version of page image is stored in WAL instead of the
126  * compressed one if the number of bytes saved by compression is less than
127  * the length of extra information. Hence, when a page image is successfully
128  * compressed, the amount of block data actually present is less than
129  * BLCKSZ - the length of "hole" bytes - the length of extra information.
130  */
132 {
133  uint16 length; /* number of page image bytes */
134  uint16 hole_offset; /* number of bytes before "hole" */
135  uint8 bimg_info; /* flag bits, see below */
136 
137  /*
138  * If BKPIMAGE_HAS_HOLE and BKPIMAGE_IS_COMPRESSED, an
139  * XLogRecordBlockCompressHeader struct follows.
140  */
142 
143 #define SizeOfXLogRecordBlockImageHeader \
144  (offsetof(XLogRecordBlockImageHeader, bimg_info) + sizeof(uint8))
145 
146 /* Information stored in bimg_info */
147 #define BKPIMAGE_HAS_HOLE 0x01 /* page image has "hole" */
148 #define BKPIMAGE_IS_COMPRESSED 0x02 /* page image is compressed */
149 #define BKPIMAGE_APPLY 0x04 /* page image should be restored during
150  * replay */
151 
152 /*
153  * Extra header information used when page image has "hole" and
154  * is compressed.
155  */
157 {
158  uint16 hole_length; /* number of bytes in "hole" */
160 
161 #define SizeOfXLogRecordBlockCompressHeader \
162  sizeof(XLogRecordBlockCompressHeader)
163 
164 /*
165  * Maximum size of the header for a block reference. This is used to size a
166  * temporary buffer for constructing the header.
167  */
168 #define MaxSizeOfXLogRecordBlockHeader \
169  (SizeOfXLogRecordBlockHeader + \
170  SizeOfXLogRecordBlockImageHeader + \
171  SizeOfXLogRecordBlockCompressHeader + \
172  sizeof(RelFileNode) + \
173  sizeof(BlockNumber))
174 
175 /*
176  * The fork number fits in the lower 4 bits in the fork_flags field. The upper
177  * bits are used for flags.
178  */
179 #define BKPBLOCK_FORK_MASK 0x0F
180 #define BKPBLOCK_FLAG_MASK 0xF0
181 #define BKPBLOCK_HAS_IMAGE 0x10 /* block data is an XLogRecordBlockImage */
182 #define BKPBLOCK_HAS_DATA 0x20
183 #define BKPBLOCK_WILL_INIT 0x40 /* redo will re-init the page */
184 #define BKPBLOCK_SAME_REL 0x80 /* RelFileNode omitted, same as previous */
185 
186 /*
187  * XLogRecordDataHeaderShort/Long are used for the "main data" portion of
188  * the record. If the length of the data is less than 256 bytes, the short
189  * form is used, with a single byte to hold the length. Otherwise the long
190  * form is used.
191  *
192  * (These structs are currently not used in the code, they are here just for
193  * documentation purposes).
194  */
196 {
197  uint8 id; /* XLR_BLOCK_ID_DATA_SHORT */
198  uint8 data_length; /* number of payload bytes */
200 
201 #define SizeOfXLogRecordDataHeaderShort (sizeof(uint8) * 2)
202 
204 {
205  uint8 id; /* XLR_BLOCK_ID_DATA_LONG */
206  /* followed by uint32 data_length, unaligned */
208 
209 #define SizeOfXLogRecordDataHeaderLong (sizeof(uint8) + sizeof(uint32))
210 
211 /*
212  * Block IDs used to distinguish different kinds of record fragments. Block
213  * references are numbered from 0 to XLR_MAX_BLOCK_ID. A rmgr is free to use
214  * any ID number in that range (although you should stick to small numbers,
215  * because the WAL machinery is optimized for that case). A couple of ID
216  * numbers are reserved to denote the "main" data portion of the record.
217  *
218  * The maximum is currently set at 32, quite arbitrarily. Most records only
219  * need a handful of block references, but there are a few exceptions that
220  * need more.
221  */
222 #define XLR_MAX_BLOCK_ID 32
223 
224 #define XLR_BLOCK_ID_DATA_SHORT 255
225 #define XLR_BLOCK_ID_DATA_LONG 254
226 #define XLR_BLOCK_ID_ORIGIN 253
227 
228 #endif /* XLOGRECORD_H */
XLogRecPtr xl_prev
Definition: xlogrecord.h:45
struct XLogRecordBlockHeader XLogRecordBlockHeader
uint32 TransactionId
Definition: c.h:397
uint32 pg_crc32c
Definition: pg_crc32c.h:38
unsigned char uint8
Definition: c.h:266
struct XLogRecordBlockImageHeader XLogRecordBlockImageHeader
RmgrId xl_rmid
Definition: xlogrecord.h:47
unsigned short uint16
Definition: c.h:267
uint32 xl_tot_len
Definition: xlogrecord.h:43
struct XLogRecordBlockCompressHeader XLogRecordBlockCompressHeader
struct XLogRecordDataHeaderLong XLogRecordDataHeaderLong
unsigned int uint32
Definition: c.h:268
struct XLogRecord XLogRecord
uint8 RmgrId
Definition: rmgr.h:11
struct XLogRecordDataHeaderShort XLogRecordDataHeaderShort
uint64 XLogRecPtr
Definition: xlogdefs.h:21
uint8 xl_info
Definition: xlogrecord.h:46
pg_crc32c xl_crc
Definition: xlogrecord.h:49
TransactionId xl_xid
Definition: xlogrecord.h:44