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