PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
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-2017, 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 0xD097 /* 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.
47  *
48  * Note that xl_rem_len includes backup-block data; that is, it tracks
49  * xl_tot_len not xl_len in the initial header. Also note that the
50  * continuation data isn't necessarily aligned.
51  */
52  uint32 xlp_rem_len; /* total len of remaining data for record */
54 
55 #define SizeOfXLogShortPHD MAXALIGN(sizeof(XLogPageHeaderData))
56 
58 
59 /*
60  * When the XLP_LONG_HEADER flag is set, we store additional fields in the
61  * page header. (This is ordinarily done just in the first page of an
62  * XLOG file.) The additional fields serve to identify the file accurately.
63  */
64 typedef struct XLogLongPageHeaderData
65 {
66  XLogPageHeaderData std; /* standard header fields */
67  uint64 xlp_sysid; /* system identifier from pg_control */
68  uint32 xlp_seg_size; /* just as a cross-check */
69  uint32 xlp_xlog_blcksz; /* just as a cross-check */
71 
72 #define SizeOfXLogLongPHD MAXALIGN(sizeof(XLogLongPageHeaderData))
73 
75 
76 /* When record crosses page boundary, set this flag in new page's header */
77 #define XLP_FIRST_IS_CONTRECORD 0x0001
78 /* This flag indicates a "long" page header */
79 #define XLP_LONG_HEADER 0x0002
80 /* This flag indicates backup blocks starting in this page are optional */
81 #define XLP_BKP_REMOVABLE 0x0004
82 /* All defined flag bits in xlp_info (used for validity checking of header) */
83 #define XLP_ALL_FLAGS 0x0007
84 
85 #define XLogPageHeaderSize(hdr) \
86  (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)
87 
88 /*
89  * The XLOG is split into WAL segments (physical files) of the size indicated
90  * by XLOG_SEG_SIZE.
91  */
92 #define XLogSegSize ((uint32) XLOG_SEG_SIZE)
93 #define XLogSegmentsPerXLogId (UINT64CONST(0x100000000) / XLOG_SEG_SIZE)
94 
95 #define XLogSegNoOffsetToRecPtr(segno, offset, dest) \
96  (dest) = (segno) * XLOG_SEG_SIZE + (offset)
97 
98 /*
99  * Compute ID and segment from an XLogRecPtr.
100  *
101  * For XLByteToSeg, do the computation at face value. For XLByteToPrevSeg,
102  * a boundary byte is taken to be in the previous segment. This is suitable
103  * for deciding which segment to write given a pointer to a record end,
104  * for example.
105  */
106 #define XLByteToSeg(xlrp, logSegNo) \
107  logSegNo = (xlrp) / XLogSegSize
108 
109 #define XLByteToPrevSeg(xlrp, logSegNo) \
110  logSegNo = ((xlrp) - 1) / XLogSegSize
111 
112 /*
113  * Is an XLogRecPtr within a particular XLOG segment?
114  *
115  * For XLByteInSeg, do the computation at face value. For XLByteInPrevSeg,
116  * a boundary byte is taken to be in the previous segment.
117  */
118 #define XLByteInSeg(xlrp, logSegNo) \
119  (((xlrp) / XLogSegSize) == (logSegNo))
120 
121 #define XLByteInPrevSeg(xlrp, logSegNo) \
122  ((((xlrp) - 1) / XLogSegSize) == (logSegNo))
123 
124 /* Check if an XLogRecPtr value is in a plausible range */
125 #define XRecOffIsValid(xlrp) \
126  ((xlrp) % XLOG_BLCKSZ >= SizeOfXLogShortPHD)
127 
128 /*
129  * The XLog directory and control file (relative to $PGDATA)
130  */
131 #define XLOGDIR "pg_wal"
132 #define XLOG_CONTROL_FILE "global/pg_control"
133 
134 /*
135  * These macros encapsulate knowledge about the exact layout of XLog file
136  * names, timeline history file names, and archive-status file names.
137  */
138 #define MAXFNAMELEN 64
139 
140 /* Length of XLog file name */
141 #define XLOG_FNAME_LEN 24
142 
143 #define XLogFileName(fname, tli, logSegNo) \
144  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, \
145  (uint32) ((logSegNo) / XLogSegmentsPerXLogId), \
146  (uint32) ((logSegNo) % XLogSegmentsPerXLogId))
147 
148 #define XLogFileNameById(fname, tli, log, seg) \
149  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg)
150 
151 #define IsXLogFileName(fname) \
152  (strlen(fname) == XLOG_FNAME_LEN && \
153  strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN)
154 
155 /*
156  * XLOG segment with .partial suffix. Used by pg_receivewal and at end of
157  * archive recovery, when we want to archive a WAL segment but it might not
158  * be complete yet.
159  */
160 #define IsPartialXLogFileName(fname) \
161  (strlen(fname) == XLOG_FNAME_LEN + strlen(".partial") && \
162  strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN && \
163  strcmp((fname) + XLOG_FNAME_LEN, ".partial") == 0)
164 
165 #define XLogFromFileName(fname, tli, logSegNo) \
166  do { \
167  uint32 log; \
168  uint32 seg; \
169  sscanf(fname, "%08X%08X%08X", tli, &log, &seg); \
170  *logSegNo = (uint64) log * XLogSegmentsPerXLogId + seg; \
171  } while (0)
172 
173 #define XLogFilePath(path, tli, logSegNo) \
174  snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli, \
175  (uint32) ((logSegNo) / XLogSegmentsPerXLogId), \
176  (uint32) ((logSegNo) % XLogSegmentsPerXLogId))
177 
178 #define TLHistoryFileName(fname, tli) \
179  snprintf(fname, MAXFNAMELEN, "%08X.history", tli)
180 
181 #define IsTLHistoryFileName(fname) \
182  (strlen(fname) == 8 + strlen(".history") && \
183  strspn(fname, "0123456789ABCDEF") == 8 && \
184  strcmp((fname) + 8, ".history") == 0)
185 
186 #define TLHistoryFilePath(path, tli) \
187  snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli)
188 
189 #define StatusFilePath(path, xlog, suffix) \
190  snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix)
191 
192 #define BackupHistoryFileName(fname, tli, logSegNo, offset) \
193  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli, \
194  (uint32) ((logSegNo) / XLogSegmentsPerXLogId), \
195  (uint32) ((logSegNo) % XLogSegmentsPerXLogId), offset)
196 
197 #define IsBackupHistoryFileName(fname) \
198  (strlen(fname) > XLOG_FNAME_LEN && \
199  strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN && \
200  strcmp((fname) + strlen(fname) - strlen(".backup"), ".backup") == 0)
201 
202 #define BackupHistoryFilePath(path, tli, logSegNo, offset) \
203  snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli, \
204  (uint32) ((logSegNo) / XLogSegmentsPerXLogId), \
205  (uint32) ((logSegNo) % XLogSegmentsPerXLogId), offset)
206 
207 /*
208  * Information logged when we detect a change in one of the parameters
209  * important for Hot Standby.
210  */
211 typedef struct xl_parameter_change
212 {
221 
222 /* logs restore point */
223 typedef struct xl_restore_point
224 {
228 
229 /* End of recovery mark, when we don't do an END_OF_RECOVERY checkpoint */
230 typedef struct xl_end_of_recovery
231 {
233  TimeLineID ThisTimeLineID; /* new TLI */
234  TimeLineID PrevTimeLineID; /* previous TLI we forked off from */
236 
237 /*
238  * The functions in xloginsert.c construct a chain of XLogRecData structs
239  * to represent the final WAL record.
240  */
241 typedef struct XLogRecData
242 {
243  struct XLogRecData *next; /* next struct in chain, or NULL */
244  char *data; /* start of rmgr data to include */
245  uint32 len; /* length of rmgr data to include */
246 } XLogRecData;
247 
248 /*
249  * Recovery target action.
250  */
251 typedef enum
252 {
257 
258 /*
259  * Method table for resource managers.
260  *
261  * This struct must be kept in sync with the PG_RMGR definition in
262  * rmgr.c.
263  *
264  * rm_identify must return a name for the record based on xl_info (without
265  * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
266  * "VACUUM". rm_desc can then be called to obtain additional detail for the
267  * record, if available (e.g. the last block).
268  *
269  * rm_mask takes as input a page modified by the resource manager and masks
270  * out bits that shouldn't be flagged by wal_consistency_checking.
271  *
272  * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h).
273  */
274 typedef struct RmgrData
275 {
276  const char *rm_name;
277  void (*rm_redo) (XLogReaderState *record);
278  void (*rm_desc) (StringInfo buf, XLogReaderState *record);
279  const char *(*rm_identify) (uint8 info);
280  void (*rm_startup) (void);
281  void (*rm_cleanup) (void);
282  void (*rm_mask) (char *pagedata, BlockNumber blkno);
283 } RmgrData;
284 
285 extern const RmgrData RmgrTable[];
286 
287 /*
288  * Exported to support xlog switching from checkpointer
289  */
290 extern pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN);
291 extern XLogRecPtr RequestXLogSwitch(bool mark_unimportant);
292 
293 extern void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli);
294 
295 /*
296  * Exported for the functions in timeline.c and xlogarchive.c. Only valid
297  * in the startup process.
298  */
299 extern bool ArchiveRecoveryRequested;
300 extern bool InArchiveRecovery;
301 extern bool StandbyMode;
302 extern char *recoveryRestoreCommand;
303 
304 /*
305  * Prototypes for functions in xlogarchive.c
306  */
307 extern bool RestoreArchivedFile(char *path, const char *xlogfname,
308  const char *recovername, off_t expectedSize,
309  bool cleanupEnabled);
310 extern void ExecuteRecoveryCommand(char *command, char *commandName,
311  bool failOnerror);
312 extern void KeepFileRestoredFromArchive(char *path, char *xlogfname);
313 extern void XLogArchiveNotify(const char *xlog);
314 extern void XLogArchiveNotifySeg(XLogSegNo segno);
315 extern void XLogArchiveForceDone(const char *xlog);
316 extern bool XLogArchiveCheckDone(const char *xlog);
317 extern bool XLogArchiveIsBusy(const char *xlog);
318 extern bool XLogArchiveIsReady(const char *xlog);
319 extern bool XLogArchiveIsReadyOrDone(const char *xlog);
320 extern void XLogArchiveCleanup(const char *xlog);
321 
322 #endif /* XLOG_INTERNAL_H */
struct XLogLongPageHeaderData XLogLongPageHeaderData
void XLogArchiveCleanup(const char *xlog)
Definition: xlogarchive.c:750
bool XLogArchiveIsReadyOrDone(const char *xlog)
Definition: xlogarchive.c:702
void XLogArchiveNotifySeg(XLogSegNo segno)
Definition: xlogarchive.c:546
uint32 TimeLineID
Definition: xlogdefs.h:45
int64 pg_time_t
Definition: pgtime.h:23
void(* rm_mask)(char *pagedata, BlockNumber blkno)
struct xl_end_of_recovery xl_end_of_recovery
bool XLogArchiveCheckDone(const char *xlog)
Definition: xlogarchive.c:617
TimeLineID PrevTimeLineID
struct xl_parameter_change xl_parameter_change
int64 TimestampTz
Definition: timestamp.h:39
XLogRecPtr RequestXLogSwitch(bool mark_unimportant)
Definition: xlog.c:9405
void ExecuteRecoveryCommand(char *command, char *commandName, bool failOnerror)
Definition: xlogarchive.c:329
unsigned char uint8
Definition: c.h:266
void(* rm_redo)(XLogReaderState *record)
pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN)
Definition: xlog.c:8268
bool StandbyMode
Definition: xlog.c:277
XLogPageHeaderData * XLogPageHeader
Definition: xlog_internal.h:57
uint32 BlockNumber
Definition: block.h:31
void XLogArchiveNotify(const char *xlog)
Definition: xlogarchive.c:512
XLogLongPageHeaderData * XLogLongPageHeader
Definition: xlog_internal.h:74
RecoveryTargetAction
char rp_name[MAXFNAMELEN]
unsigned short uint16
Definition: c.h:267
char * recoveryRestoreCommand
Definition: xlog.c:257
void(* rm_desc)(StringInfo buf, XLogReaderState *record)
static char * buf
Definition: pg_test_fsync.c:66
uint64 XLogSegNo
Definition: xlogdefs.h:34
struct XLogRecData XLogRecData
bool ArchiveRecoveryRequested
Definition: xlog.c:246
bool XLogArchiveIsBusy(const char *xlog)
Definition: xlogarchive.c:657
unsigned int uint32
Definition: c.h:268
TimeLineID xlp_tli
Definition: xlog_internal.h:40
XLogRecPtr xlp_pageaddr
Definition: xlog_internal.h:41
struct xl_restore_point xl_restore_point
void XLogArchiveForceDone(const char *xlog)
Definition: xlogarchive.c:562
#define MAXFNAMELEN
bool InArchiveRecovery
Definition: xlog.c:247
void(* rm_cleanup)(void)
bool XLogArchiveIsReady(const char *xlog)
Definition: xlogarchive.c:732
TimestampTz end_time
uint64 XLogRecPtr
Definition: xlogdefs.h:21
const RmgrData RmgrTable[]
Definition: rmgr.c:36
const char * rm_name
struct XLogRecData * next
bool RestoreArchivedFile(char *path, const char *xlogfname, const char *recovername, off_t expectedSize, bool cleanupEnabled)
Definition: xlogarchive.c:51
TimestampTz rp_time
TimeLineID ThisTimeLineID
XLogPageHeaderData std
Definition: xlog_internal.h:66
void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli)
Definition: xlog.c:11137
void KeepFileRestoredFromArchive(char *path, char *xlogfname)
Definition: xlogarchive.c:426
struct XLogPageHeaderData XLogPageHeaderData
struct RmgrData RmgrData
void(* rm_startup)(void)