PostgreSQL Source Code  git master
xlog_internal.h
Go to the documentation of this file.
1 /*
2  * xlog_internal.h
3  *
4  * PostgreSQL write-ahead 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 xlogrecord.h.
10  *
11  * Note: This file must be includable in both frontend and backend contexts,
12  * to allow stand-alone tools like pg_receivewal to deal with WAL files.
13  *
14  * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
15  * Portions Copyright (c) 1994, Regents of the University of California
16  *
17  * src/include/access/xlog_internal.h
18  */
19 #ifndef XLOG_INTERNAL_H
20 #define XLOG_INTERNAL_H
21 
22 #include "access/xlogdefs.h"
23 #include "access/xlogreader.h"
24 #include "datatype/timestamp.h"
25 #include "lib/stringinfo.h"
26 #include "pgtime.h"
27 #include "storage/block.h"
28 #include "storage/relfilenode.h"
29 
30 
31 /*
32  * Each page of XLOG file has a header like this:
33  */
34 #define XLOG_PAGE_MAGIC 0xD108 /* can be used as WAL version indicator */
35 
36 typedef struct XLogPageHeaderData
37 {
38  uint16 xlp_magic; /* magic value for correctness checks */
39  uint16 xlp_info; /* flag bits, see below */
40  TimeLineID xlp_tli; /* TimeLineID of first record on page */
41  XLogRecPtr xlp_pageaddr; /* XLOG address of this page */
42 
43  /*
44  * When there is not enough space on current page for whole record, we
45  * continue on the next page. xlp_rem_len is the number of bytes
46  * remaining from a previous page; it tracks xl_tot_len in the initial
47  * header. Note that the continuation data isn't necessarily aligned.
48  */
49  uint32 xlp_rem_len; /* total len of remaining data for record */
51 
52 #define SizeOfXLogShortPHD MAXALIGN(sizeof(XLogPageHeaderData))
53 
55 
56 /*
57  * When the XLP_LONG_HEADER flag is set, we store additional fields in the
58  * page header. (This is ordinarily done just in the first page of an
59  * XLOG file.) The additional fields serve to identify the file accurately.
60  */
61 typedef struct XLogLongPageHeaderData
62 {
63  XLogPageHeaderData std; /* standard header fields */
64  uint64 xlp_sysid; /* system identifier from pg_control */
65  uint32 xlp_seg_size; /* just as a cross-check */
66  uint32 xlp_xlog_blcksz; /* just as a cross-check */
68 
69 #define SizeOfXLogLongPHD MAXALIGN(sizeof(XLogLongPageHeaderData))
70 
72 
73 /* When record crosses page boundary, set this flag in new page's header */
74 #define XLP_FIRST_IS_CONTRECORD 0x0001
75 /* This flag indicates a "long" page header */
76 #define XLP_LONG_HEADER 0x0002
77 /* This flag indicates backup blocks starting in this page are optional */
78 #define XLP_BKP_REMOVABLE 0x0004
79 /* All defined flag bits in xlp_info (used for validity checking of header) */
80 #define XLP_ALL_FLAGS 0x0007
81 
82 #define XLogPageHeaderSize(hdr) \
83  (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)
84 
85 /* wal_segment_size can range from 1MB to 1GB */
86 #define WalSegMinSize 1024 * 1024
87 #define WalSegMaxSize 1024 * 1024 * 1024
88 /* default number of min and max wal segments */
89 #define DEFAULT_MIN_WAL_SEGS 5
90 #define DEFAULT_MAX_WAL_SEGS 64
91 
92 /* check that the given size is a valid wal_segment_size */
93 #define IsPowerOf2(x) (x > 0 && ((x) & ((x)-1)) == 0)
94 #define IsValidWalSegSize(size) \
95  (IsPowerOf2(size) && \
96  ((size) >= WalSegMinSize && (size) <= WalSegMaxSize))
97 
98 #define XLogSegmentsPerXLogId(wal_segsz_bytes) \
99  (UINT64CONST(0x100000000) / (wal_segsz_bytes))
100 
101 #define XLogSegNoOffsetToRecPtr(segno, offset, wal_segsz_bytes, dest) \
102  (dest) = (segno) * (wal_segsz_bytes) + (offset)
103 
104 #define XLogSegmentOffset(xlogptr, wal_segsz_bytes) \
105  ((xlogptr) & ((wal_segsz_bytes) - 1))
106 
107 /*
108  * Compute a segment number from an XLogRecPtr.
109  *
110  * For XLByteToSeg, do the computation at face value. For XLByteToPrevSeg,
111  * a boundary byte is taken to be in the previous segment. This is suitable
112  * for deciding which segment to write given a pointer to a record end,
113  * for example.
114  */
115 #define XLByteToSeg(xlrp, logSegNo, wal_segsz_bytes) \
116  logSegNo = (xlrp) / (wal_segsz_bytes)
117 
118 #define XLByteToPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
119  logSegNo = ((xlrp) - 1) / (wal_segsz_bytes)
120 
121 /*
122  * Convert values of GUCs measured in megabytes to equiv. segment count.
123  * Rounds down.
124  */
125 #define XLogMBVarToSegs(mbvar, wal_segsz_bytes) \
126  ((mbvar) / ((wal_segsz_bytes) / (1024 * 1024)))
127 
128 /*
129  * Is an XLogRecPtr within a particular XLOG segment?
130  *
131  * For XLByteInSeg, do the computation at face value. For XLByteInPrevSeg,
132  * a boundary byte is taken to be in the previous segment.
133  */
134 #define XLByteInSeg(xlrp, logSegNo, wal_segsz_bytes) \
135  (((xlrp) / (wal_segsz_bytes)) == (logSegNo))
136 
137 #define XLByteInPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
138  ((((xlrp) - 1) / (wal_segsz_bytes)) == (logSegNo))
139 
140 /* Check if an XLogRecPtr value is in a plausible range */
141 #define XRecOffIsValid(xlrp) \
142  ((xlrp) % XLOG_BLCKSZ >= SizeOfXLogShortPHD)
143 
144 /*
145  * The XLog directory and control file (relative to $PGDATA)
146  */
147 #define XLOGDIR "pg_wal"
148 #define XLOG_CONTROL_FILE "global/pg_control"
149 
150 /*
151  * These macros encapsulate knowledge about the exact layout of XLog file
152  * names, timeline history file names, and archive-status file names.
153  */
154 #define MAXFNAMELEN 64
155 
156 /* Length of XLog file name */
157 #define XLOG_FNAME_LEN 24
158 
159 /*
160  * Generate a WAL segment file name. Do not use this macro in a helper
161  * function allocating the result generated.
162  */
163 #define XLogFileName(fname, tli, logSegNo, wal_segsz_bytes) \
164  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, \
165  (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
166  (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)))
167 
168 #define XLogFileNameById(fname, tli, log, seg) \
169  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg)
170 
171 #define IsXLogFileName(fname) \
172  (strlen(fname) == XLOG_FNAME_LEN && \
173  strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN)
174 
175 /*
176  * XLOG segment with .partial suffix. Used by pg_receivewal and at end of
177  * archive recovery, when we want to archive a WAL segment but it might not
178  * be complete yet.
179  */
180 #define IsPartialXLogFileName(fname) \
181  (strlen(fname) == XLOG_FNAME_LEN + strlen(".partial") && \
182  strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN && \
183  strcmp((fname) + XLOG_FNAME_LEN, ".partial") == 0)
184 
185 #define XLogFromFileName(fname, tli, logSegNo, wal_segsz_bytes) \
186  do { \
187  uint32 log; \
188  uint32 seg; \
189  sscanf(fname, "%08X%08X%08X", tli, &log, &seg); \
190  *logSegNo = (uint64) log * XLogSegmentsPerXLogId(wal_segsz_bytes) + seg; \
191  } while (0)
192 
193 #define XLogFilePath(path, tli, logSegNo, wal_segsz_bytes) \
194  snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli, \
195  (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
196  (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)))
197 
198 #define TLHistoryFileName(fname, tli) \
199  snprintf(fname, MAXFNAMELEN, "%08X.history", tli)
200 
201 #define IsTLHistoryFileName(fname) \
202  (strlen(fname) == 8 + strlen(".history") && \
203  strspn(fname, "0123456789ABCDEF") == 8 && \
204  strcmp((fname) + 8, ".history") == 0)
205 
206 #define TLHistoryFilePath(path, tli) \
207  snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli)
208 
209 #define StatusFilePath(path, xlog, suffix) \
210  snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix)
211 
212 #define BackupHistoryFileName(fname, tli, logSegNo, startpoint, wal_segsz_bytes) \
213  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli, \
214  (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
215  (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)), \
216  (uint32) (XLogSegmentOffset(startpoint, wal_segsz_bytes)))
217 
218 #define IsBackupHistoryFileName(fname) \
219  (strlen(fname) > XLOG_FNAME_LEN && \
220  strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN && \
221  strcmp((fname) + strlen(fname) - strlen(".backup"), ".backup") == 0)
222 
223 #define BackupHistoryFilePath(path, tli, logSegNo, startpoint, wal_segsz_bytes) \
224  snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli, \
225  (uint32) ((logSegNo) / XLogSegmentsPerXLogId(wal_segsz_bytes)), \
226  (uint32) ((logSegNo) % XLogSegmentsPerXLogId(wal_segsz_bytes)), \
227  (uint32) (XLogSegmentOffset((startpoint), wal_segsz_bytes)))
228 
229 /*
230  * Information logged when we detect a change in one of the parameters
231  * important for Hot Standby.
232  */
233 typedef struct xl_parameter_change
234 {
244 
245 /* logs restore point */
246 typedef struct xl_restore_point
247 {
249  char rp_name[MAXFNAMELEN];
251 
252 /* End of recovery mark, when we don't do an END_OF_RECOVERY checkpoint */
253 typedef struct xl_end_of_recovery
254 {
256  TimeLineID ThisTimeLineID; /* new TLI */
257  TimeLineID PrevTimeLineID; /* previous TLI we forked off from */
259 
260 /*
261  * The functions in xloginsert.c construct a chain of XLogRecData structs
262  * to represent the final WAL record.
263  */
264 typedef struct XLogRecData
265 {
266  struct XLogRecData *next; /* next struct in chain, or NULL */
267  char *data; /* start of rmgr data to include */
268  uint32 len; /* length of rmgr data to include */
269 } XLogRecData;
270 
271 /*
272  * Recovery target action.
273  */
274 typedef enum
275 {
280 
281 /*
282  * Method table for resource managers.
283  *
284  * This struct must be kept in sync with the PG_RMGR definition in
285  * rmgr.c.
286  *
287  * rm_identify must return a name for the record based on xl_info (without
288  * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
289  * "VACUUM". rm_desc can then be called to obtain additional detail for the
290  * record, if available (e.g. the last block).
291  *
292  * rm_mask takes as input a page modified by the resource manager and masks
293  * out bits that shouldn't be flagged by wal_consistency_checking.
294  *
295  * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h).
296  */
297 typedef struct RmgrData
298 {
299  const char *rm_name;
300  void (*rm_redo) (XLogReaderState *record);
301  void (*rm_desc) (StringInfo buf, XLogReaderState *record);
302  const char *(*rm_identify) (uint8 info);
303  void (*rm_startup) (void);
304  void (*rm_cleanup) (void);
305  void (*rm_mask) (char *pagedata, BlockNumber blkno);
306 } RmgrData;
307 
308 extern const RmgrData RmgrTable[];
309 
310 /*
311  * Exported to support xlog switching from checkpointer
312  */
313 extern pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN);
314 extern XLogRecPtr RequestXLogSwitch(bool mark_unimportant);
315 
316 extern void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli);
317 
318 /*
319  * Exported for the functions in timeline.c and xlogarchive.c. Only valid
320  * in the startup process.
321  */
322 extern bool ArchiveRecoveryRequested;
323 extern bool InArchiveRecovery;
324 extern bool StandbyMode;
325 extern char *recoveryRestoreCommand;
326 
327 #endif /* XLOG_INTERNAL_H */
struct XLogLongPageHeaderData XLogLongPageHeaderData
uint32 TimeLineID
Definition: xlogdefs.h:52
int64 pg_time_t
Definition: pgtime.h:23
struct xl_end_of_recovery xl_end_of_recovery
TimeLineID PrevTimeLineID
struct xl_parameter_change xl_parameter_change
int64 TimestampTz
Definition: timestamp.h:39
XLogRecPtr RequestXLogSwitch(bool mark_unimportant)
Definition: xlog.c:9691
unsigned char uint8
Definition: c.h:372
pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN)
Definition: xlog.c:8473
bool StandbyMode
Definition: xlog.c:301
XLogPageHeaderData * XLogPageHeader
Definition: xlog_internal.h:54
uint32 BlockNumber
Definition: block.h:31
XLogLongPageHeaderData * XLogLongPageHeader
Definition: xlog_internal.h:71
RecoveryTargetAction
unsigned short uint16
Definition: c.h:373
char * recoveryRestoreCommand
Definition: xlog.c:280
static char * buf
Definition: pg_test_fsync.c:68
struct XLogRecData XLogRecData
bool ArchiveRecoveryRequested
Definition: xlog.c:266
unsigned int uint32
Definition: c.h:374
TimeLineID xlp_tli
Definition: xlog_internal.h:40
XLogRecPtr xlp_pageaddr
Definition: xlog_internal.h:41
struct xl_restore_point xl_restore_point
#define MAXFNAMELEN
bool InArchiveRecovery
Definition: xlog.c:267
TimestampTz end_time
uint64 XLogRecPtr
Definition: xlogdefs.h:21
const RmgrData RmgrTable[]
Definition: rmgr.c:36
const char * rm_name
struct XLogRecData * next
TimestampTz rp_time
TimeLineID ThisTimeLineID
XLogPageHeaderData std
Definition: xlog_internal.h:63
void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli)
Definition: xlog.c:11537
struct XLogPageHeaderData XLogPageHeaderData
struct RmgrData RmgrData