src/include/access/xlog_internal.h

   1 /*
   2  * xlog_internal.h
   3  *
   4  * PostgreSQL transaction log internal declarations
   5  *
   6  * NOTE: this file is intended to contain declarations useful for
   7  * manipulating the XLOG files directly, but it is not supposed to be
   8  * needed by rmgr routines (redo support for individual record types).
   9  * So the XLogRecord typedef and associated stuff appear in xlog.h.
  10  *
  11  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  12  * Portions Copyright (c) 1994, Regents of the University of California
  13  *
  14  * $PostgreSQL$
  15  */
  16 #ifndef XLOG_INTERNAL_H
  17 #define XLOG_INTERNAL_H
  18
  19 #include "access/xlog.h"
  20 #include "fmgr.h"
  21 #include "pgtime.h"
  22 #include "storage/block.h"
  23 #include "storage/relfilenode.h"
  24
  25
  26 /*
  27  * Header info for a backup block appended to an XLOG record.
  28  *
  29  * As a trivial form of data compression, the XLOG code is aware that
  30  * PG data pages usually contain an unused "hole" in the middle, which
  31  * contains only zero bytes.  If hole_length > 0 then we have removed
  32  * such a "hole" from the stored data (and it's not counted in the
  33  * XLOG record's CRC, either).  Hence, the amount of block data actually
  34  * present following the BkpBlock struct is BLCKSZ - hole_length bytes.
  35  *
  36  * Note that we don't attempt to align either the BkpBlock struct or the
  37  * block's data.  So, the struct must be copied to aligned local storage
  38  * before use.
  39  */
  40 typedef struct BkpBlock
  41 {
  42         RelFileNode node;                       /* relation containing block */
  43         ForkNumber      fork;                   /* fork within the relation */
  44         BlockNumber block;                      /* block number */
  45         uint16          hole_offset;    /* number of bytes before "hole" */
  46         uint16          hole_length;    /* number of bytes in "hole" */
  47
  48         /* ACTUAL BLOCK DATA FOLLOWS AT END OF STRUCT */
  49 } BkpBlock;
  50
  51 /*
  52  * When there is not enough space on current page for whole record, we
  53  * continue on the next page with continuation record.  (However, the
  54  * XLogRecord header will never be split across pages; if there's less than
  55  * SizeOfXLogRecord space left at the end of a page, we just waste it.)
  56  *
  57  * Note that xl_rem_len includes backup-block data; that is, it tracks
  58  * xl_tot_len not xl_len in the initial header.  Also note that the
  59  * continuation data isn't necessarily aligned.
  60  */
  61 typedef struct XLogContRecord
  62 {
  63         uint32          xl_rem_len;             /* total len of remaining data for record */
  64
  65         /* ACTUAL LOG DATA FOLLOWS AT END OF STRUCT */
  66
  67 } XLogContRecord;
  68
  69 #define SizeOfXLogContRecord    sizeof(XLogContRecord)
  70
  71 /*
  72  * Each page of XLOG file has a header like this:
  73  */
  74 #define XLOG_PAGE_MAGIC 0xD063  /* can be used as WAL version indicator */
  75
  76 typedef struct XLogPageHeaderData
  77 {
  78         uint16          xlp_magic;              /* magic value for correctness checks */
  79         uint16          xlp_info;               /* flag bits, see below */
  80         TimeLineID      xlp_tli;                /* TimeLineID of first record on page */
  81         XLogRecPtr      xlp_pageaddr;   /* XLOG address of this page */
  82 } XLogPageHeaderData;
  83
  84 #define SizeOfXLogShortPHD      MAXALIGN(sizeof(XLogPageHeaderData))
  85
  86 typedef XLogPageHeaderData *XLogPageHeader;
  87
  88 /*
  89  * When the XLP_LONG_HEADER flag is set, we store additional fields in the
  90  * page header.  (This is ordinarily done just in the first page of an
  91  * XLOG file.)  The additional fields serve to identify the file accurately.
  92  */
  93 typedef struct XLogLongPageHeaderData
  94 {
  95         XLogPageHeaderData std;         /* standard header fields */
  96         uint64          xlp_sysid;              /* system identifier from pg_control */
  97         uint32          xlp_seg_size;   /* just as a cross-check */
  98         uint32          xlp_xlog_blcksz;        /* just as a cross-check */
  99 } XLogLongPageHeaderData;
 100
 101 #define SizeOfXLogLongPHD       MAXALIGN(sizeof(XLogLongPageHeaderData))
 102
 103 typedef XLogLongPageHeaderData *XLogLongPageHeader;
 104
 105 /* When record crosses page boundary, set this flag in new page's header */
 106 #define XLP_FIRST_IS_CONTRECORD         0x0001
 107 /* This flag indicates a "long" page header */
 108 #define XLP_LONG_HEADER                         0x0002
 109 /* All defined flag bits in xlp_info (used for validity checking of header) */
 110 #define XLP_ALL_FLAGS                           0x0003
 111
 112 #define XLogPageHeaderSize(hdr)         \
 113         (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)
 114
 115 /*
 116  * We break each logical log file (xlogid value) into segment files of the
 117  * size indicated by XLOG_SEG_SIZE.  One possible segment at the end of each
 118  * log file is wasted, to ensure that we don't have problems representing
 119  * last-byte-position-plus-1.
 120  */
 121 #define XLogSegSize             ((uint32) XLOG_SEG_SIZE)
 122 #define XLogSegsPerFile (((uint32) 0xffffffff) / XLogSegSize)
 123 #define XLogFileSize    (XLogSegsPerFile * XLogSegSize)
 124
 125
 126 /*
 127  * Macros for manipulating XLOG pointers
 128  */
 129
 130 /* Increment an xlogid/segment pair */
 131 #define NextLogSeg(logId, logSeg)       \
 132         do { \
 133                 if ((logSeg) >= XLogSegsPerFile-1) \
 134                 { \
 135                         (logId)++; \
 136                         (logSeg) = 0; \
 137                 } \
 138                 else \
 139                         (logSeg)++; \
 140         } while (0)
 141
 142 /* Decrement an xlogid/segment pair (assume it's not 0,0) */
 143 #define PrevLogSeg(logId, logSeg)       \
 144         do { \
 145                 if (logSeg) \
 146                         (logSeg)--; \
 147                 else \
 148                 { \
 149                         (logId)--; \
 150                         (logSeg) = XLogSegsPerFile-1; \
 151                 } \
 152         } while (0)
 153
 154 /*
 155  * Compute ID and segment from an XLogRecPtr.
 156  *
 157  * For XLByteToSeg, do the computation at face value.  For XLByteToPrevSeg,
 158  * a boundary byte is taken to be in the previous segment.      This is suitable
 159  * for deciding which segment to write given a pointer to a record end,
 160  * for example.  (We can assume xrecoff is not zero, since no valid recptr
 161  * can have that.)
 162  */
 163 #define XLByteToSeg(xlrp, logId, logSeg)        \
 164         ( logId = (xlrp).xlogid, \
 165           logSeg = (xlrp).xrecoff / XLogSegSize \
 166         )
 167 #define XLByteToPrevSeg(xlrp, logId, logSeg)    \
 168         ( logId = (xlrp).xlogid, \
 169           logSeg = ((xlrp).xrecoff - 1) / XLogSegSize \
 170         )
 171
 172 /*
 173  * Is an XLogRecPtr within a particular XLOG segment?
 174  *
 175  * For XLByteInSeg, do the computation at face value.  For XLByteInPrevSeg,
 176  * a boundary byte is taken to be in the previous segment.
 177  */
 178 #define XLByteInSeg(xlrp, logId, logSeg)        \
 179         ((xlrp).xlogid == (logId) && \
 180          (xlrp).xrecoff / XLogSegSize == (logSeg))
 181
 182 #define XLByteInPrevSeg(xlrp, logId, logSeg)    \
 183         ((xlrp).xlogid == (logId) && \
 184          ((xlrp).xrecoff - 1) / XLogSegSize == (logSeg))
 185
 186 /* Check if an xrecoff value is in a plausible range */
 187 #define XRecOffIsValid(xrecoff) \
 188                 ((xrecoff) % XLOG_BLCKSZ >= SizeOfXLogShortPHD && \
 189                 (XLOG_BLCKSZ - (xrecoff) % XLOG_BLCKSZ) >= SizeOfXLogRecord)
 190
 191 /*
 192  * The XLog directory and control file (relative to $PGDATA)
 193  */
 194 #define XLOGDIR                         "pg_xlog"
 195 #define XLOG_CONTROL_FILE       "global/pg_control"
 196
 197 /*
 198  * These macros encapsulate knowledge about the exact layout of XLog file
 199  * names, timeline history file names, and archive-status file names.
 200  */
 201 #define MAXFNAMELEN             64
 202
 203 #define XLogFileName(fname, tli, log, seg)      \
 204         snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg)
 205
 206 #define XLogFilePath(path, tli, log, seg)       \
 207         snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli, log, seg)
 208
 209 #define TLHistoryFileName(fname, tli)   \
 210         snprintf(fname, MAXFNAMELEN, "%08X.history", tli)
 211
 212 #define TLHistoryFilePath(path, tli)    \
 213         snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli)
 214
 215 #define StatusFilePath(path, xlog, suffix)      \
 216         snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix)
 217
 218 #define BackupHistoryFileName(fname, tli, log, seg, offset) \
 219         snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli, log, seg, offset)
 220
 221 #define BackupHistoryFilePath(path, tli, log, seg, offset)      \
 222         snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli, log, seg, offset)
 223
 224
 225 /*
 226  * Method table for resource managers.
 227  *
 228  * RmgrTable[] is indexed by RmgrId values (see rmgr.h).
 229  */
 230 typedef struct RmgrData
 231 {
 232         const char *rm_name;
 233         void            (*rm_redo) (XLogRecPtr lsn, XLogRecord *rptr);
 234         void            (*rm_desc) (StringInfo buf, uint8 xl_info, char *rec);
 235         void            (*rm_startup) (void);
 236         void            (*rm_cleanup) (void);
 237         bool            (*rm_safe_restartpoint) (void);
 238 } RmgrData;
 239
 240 extern const RmgrData RmgrTable[];
 241
 242 /*
 243  * Exported to support xlog switching from bgwriter
 244  */
 245 extern pg_time_t GetLastSegSwitchTime(void);
 246 extern XLogRecPtr RequestXLogSwitch(void);
 247
 248 /*
 249  * These aren't in xlog.h because I'd rather not include fmgr.h there.
 250  */
 251 extern Datum pg_start_backup(PG_FUNCTION_ARGS);
 252 extern Datum pg_stop_backup(PG_FUNCTION_ARGS);
 253 extern Datum pg_switch_xlog(PG_FUNCTION_ARGS);
 254 extern Datum pg_current_xlog_location(PG_FUNCTION_ARGS);
 255 extern Datum pg_current_xlog_insert_location(PG_FUNCTION_ARGS);
 256 extern Datum pg_xlogfile_name_offset(PG_FUNCTION_ARGS);
 257 extern Datum pg_xlogfile_name(PG_FUNCTION_ARGS);
 258
 259 #endif   /* XLOG_INTERNAL_H */