]> granicus.if.org Git - postgresql/blob - src/include/access/xlogrecord.h
Fix incorrect comment about XLogRecordBlockHeader.data_length field.
[postgresql] / src / include / access / xlogrecord.h
1 /*
2  * xlogrecord.h
3  *
4  * Definitions for the WAL record format.
5  *
6  * Portions Copyright (c) 1996-2014, 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 "storage/block.h"
17 #include "storage/relfilenode.h"
18 #include "utils/pg_crc.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_crc32        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_crc32))
56
57 /*
58  * The high 4 bits in xl_info may be used freely by rmgr. The
59  * XLR_SPECIAL_REL_UPDATE bit can be passed by XLogInsert caller. The rest
60  * 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  * Header info for block data appended to an XLOG record.
75  *
76  * 'data_length' is the length of the rmgr-specific payload data associated
77  * with this block. It does not include the possible full page image, nor
78  * XLogRecordBlockHeader struct itself.
79  *
80  * Note that we don't attempt to align the XLogRecordBlockHeader struct!
81  * So, the struct must be copied to aligned local storage before use.
82  */
83 typedef struct XLogRecordBlockHeader
84 {
85         uint8           id;                             /* block reference ID */
86         uint8           fork_flags;             /* fork within the relation, and flags */
87         uint16          data_length;    /* number of payload bytes (not including page
88                                                                  * image) */
89
90         /* If BKPBLOCK_HAS_IMAGE, an XLogRecordBlockImageHeader struct follows */
91         /* If !BKPBLOCK_SAME_REL is not set, a RelFileNode follows */
92         /* BlockNumber follows */
93 } XLogRecordBlockHeader;
94
95 #define SizeOfXLogRecordBlockHeader (offsetof(XLogRecordBlockHeader, data_length) + sizeof(uint16))
96
97 /*
98  * Additional header information when a full-page image is included
99  * (i.e. when BKPBLOCK_HAS_IMAGE is set).
100  *
101  * As a trivial form of data compression, the XLOG code is aware that
102  * PG data pages usually contain an unused "hole" in the middle, which
103  * contains only zero bytes.  If hole_length > 0 then we have removed
104  * such a "hole" from the stored data (and it's not counted in the
105  * XLOG record's CRC, either).  Hence, the amount of block data actually
106  * present is BLCKSZ - hole_length bytes.
107  */
108 typedef struct XLogRecordBlockImageHeader
109 {
110         uint16          hole_offset;    /* number of bytes before "hole" */
111         uint16          hole_length;    /* number of bytes in "hole" */
112 } XLogRecordBlockImageHeader;
113
114 #define SizeOfXLogRecordBlockImageHeader sizeof(XLogRecordBlockImageHeader)
115
116 /*
117  * Maximum size of the header for a block reference. This is used to size a
118  * temporary buffer for constructing the header.
119  */
120 #define MaxSizeOfXLogRecordBlockHeader \
121         (SizeOfXLogRecordBlockHeader + \
122          SizeOfXLogRecordBlockImageHeader + \
123          sizeof(RelFileNode) + \
124          sizeof(BlockNumber))
125
126 /*
127  * The fork number fits in the lower 4 bits in the fork_flags field. The upper
128  * bits are used for flags.
129  */
130 #define BKPBLOCK_FORK_MASK      0x0F
131 #define BKPBLOCK_FLAG_MASK      0xF0
132 #define BKPBLOCK_HAS_IMAGE      0x10    /* block data is an XLogRecordBlockImage */
133 #define BKPBLOCK_HAS_DATA       0x20
134 #define BKPBLOCK_WILL_INIT      0x40    /* redo will re-init the page */
135 #define BKPBLOCK_SAME_REL       0x80    /* RelFileNode omitted, same as previous */
136
137 /*
138  * XLogRecordDataHeaderShort/Long are used for the "main data" portion of
139  * the record. If the length of the data is less than 256 bytes, the short
140  * form is used, with a single byte to hold the length. Otherwise the long
141  * form is used.
142  *
143  * (These structs are currently not used in the code, they are here just for
144  * documentation purposes).
145  */
146 typedef struct XLogRecordDataHeaderShort
147 {
148         uint8           id;                             /* XLR_BLOCK_ID_DATA_SHORT */
149         uint8           data_length;    /* number of payload bytes */
150 } XLogRecordDataHeaderShort;
151
152 #define SizeOfXLogRecordDataHeaderShort (sizeof(uint8) * 2)
153
154 typedef struct XLogRecordDataHeaderLong
155 {
156         uint8           id;                             /* XLR_BLOCK_ID_DATA_LONG */
157         /* followed by uint32 data_length, unaligned */
158 } XLogRecordDataHeaderLong;
159
160 #define SizeOfXLogRecordDataHeaderLong (sizeof(uint8) + sizeof(uint32))
161
162 /*
163  * Block IDs used to distinguish different kinds of record fragments. Block
164  * references are numbered from 0 to XLR_MAX_BLOCK_ID. A rmgr is free to use
165  * any ID number in that range (although you should stick to small numbers,
166  * because the WAL machinery is optimized for that case). A couple of ID
167  * numbers are reserved to denote the "main" data portion of the record.
168  *
169  * The maximum is currently set at 32, quite arbitrarily. Most records only
170  * need a handful of block references, but there are a few exceptions that
171  * need more.
172  */
173 #define XLR_MAX_BLOCK_ID                        32
174
175 #define XLR_BLOCK_ID_DATA_SHORT         255
176 #define XLR_BLOCK_ID_DATA_LONG          254
177
178 #endif   /* XLOGRECORD_H */