/src/postgres/src/include/access/xlog_internal.h

Source (jump to first uncovered line)
/*
 * xlog_internal.h
 *
 * PostgreSQL write-ahead log internal declarations
 *
 * NOTE: this file is intended to contain declarations useful for
 * manipulating the XLOG files directly, but it is not supposed to be
 * needed by rmgr routines (redo support for individual record types).
 * So the XLogRecord typedef and associated stuff appear in xlogrecord.h.
 *
 * Note: This file must be includable in both frontend and backend contexts,
 * to allow stand-alone tools like pg_receivewal to deal with WAL files.
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/access/xlog_internal.h
 */
#ifndef XLOG_INTERNAL_H
#define XLOG_INTERNAL_H

#include "access/xlogdefs.h"
#include "access/xlogreader.h"
#include "datatype/timestamp.h"
#include "lib/stringinfo.h"
#include "pgtime.h"
#include "storage/block.h"
#include "storage/relfilelocator.h"


/*
 * Each page of XLOG file has a header like this:
 */
#define XLOG_PAGE_MAGIC 0xD118  /* can be used as WAL version indicator */

typedef struct XLogPageHeaderData
{
  uint16    xlp_magic;    /* magic value for correctness checks */
  uint16    xlp_info;   /* flag bits, see below */
  TimeLineID  xlp_tli;    /* TimeLineID of first record on page */
  XLogRecPtr  xlp_pageaddr; /* XLOG address of this page */

  /*
   * When there is not enough space on current page for whole record, we
   * continue on the next page.  xlp_rem_len is the number of bytes
   * remaining from a previous page; it tracks xl_tot_len in the initial
   * header.  Note that the continuation data isn't necessarily aligned.
   */
  uint32    xlp_rem_len;  /* total len of remaining data for record */
} XLogPageHeaderData;

#define SizeOfXLogShortPHD  MAXALIGN(sizeof(XLogPageHeaderData))

typedef XLogPageHeaderData *XLogPageHeader;

/*
 * When the XLP_LONG_HEADER flag is set, we store additional fields in the
 * page header.  (This is ordinarily done just in the first page of an
 * XLOG file.)  The additional fields serve to identify the file accurately.
 */
typedef struct XLogLongPageHeaderData
{
  XLogPageHeaderData std;   /* standard header fields */
  uint64    xlp_sysid;    /* system identifier from pg_control */
  uint32    xlp_seg_size; /* just as a cross-check */
  uint32    xlp_xlog_blcksz;  /* just as a cross-check */
} XLogLongPageHeaderData;

#define SizeOfXLogLongPHD MAXALIGN(sizeof(XLogLongPageHeaderData))

typedef XLogLongPageHeaderData *XLogLongPageHeader;

/* When record crosses page boundary, set this flag in new page's header */
#define XLP_FIRST_IS_CONTRECORD   0x0001
/* This flag indicates a "long" page header */
#define XLP_LONG_HEADER       0x0002
/* This flag indicates backup blocks starting in this page are optional */
#define XLP_BKP_REMOVABLE     0x0004
/* Replaces a missing contrecord; see CreateOverwriteContrecordRecord */
#define XLP_FIRST_IS_OVERWRITE_CONTRECORD 0x0008
/* All defined flag bits in xlp_info (used for validity checking of header) */
#define XLP_ALL_FLAGS       0x000F

#define XLogPageHeaderSize(hdr)   \
  (((hdr)->xlp_info & XLP_LONG_HEADER) ? SizeOfXLogLongPHD : SizeOfXLogShortPHD)

/* wal_segment_size can range from 1MB to 1GB */
#define WalSegMinSize 1024 * 1024
#define WalSegMaxSize 1024 * 1024 * 1024
/* default number of min and max wal segments */
#define DEFAULT_MIN_WAL_SEGS 5
#define DEFAULT_MAX_WAL_SEGS 64

/* check that the given size is a valid wal_segment_size */
#define IsPowerOf2(x) (x > 0 && ((x) & ((x)-1)) == 0)
#define IsValidWalSegSize(size) \
   (IsPowerOf2(size) && \
   ((size) >= WalSegMinSize && (size) <= WalSegMaxSize))

#define XLogSegmentsPerXLogId(wal_segsz_bytes)  \
  (UINT64CONST(0x100000000) / (wal_segsz_bytes))

#define XLogSegNoOffsetToRecPtr(segno, offset, wal_segsz_bytes, dest) \
    (dest) = (segno) * (wal_segsz_bytes) + (offset)

#define XLogSegmentOffset(xlogptr, wal_segsz_bytes) \
  ((xlogptr) & ((wal_segsz_bytes) - 1))

/*
 * Compute a segment number from an XLogRecPtr.
 *
 * For XLByteToSeg, do the computation at face value.  For XLByteToPrevSeg,
 * a boundary byte is taken to be in the previous segment.  This is suitable
 * for deciding which segment to write given a pointer to a record end,
 * for example.
 */
#define XLByteToSeg(xlrp, logSegNo, wal_segsz_bytes) \
  logSegNo = (xlrp) / (wal_segsz_bytes)

#define XLByteToPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
  logSegNo = ((xlrp) - 1) / (wal_segsz_bytes)

/*
 * Convert values of GUCs measured in megabytes to equiv. segment count.
 * Rounds down.
 */
#define XLogMBVarToSegs(mbvar, wal_segsz_bytes) \
  ((mbvar) / ((wal_segsz_bytes) / (1024 * 1024)))

/*
 * Is an XLogRecPtr within a particular XLOG segment?
 *
 * For XLByteInSeg, do the computation at face value.  For XLByteInPrevSeg,
 * a boundary byte is taken to be in the previous segment.
 */
#define XLByteInSeg(xlrp, logSegNo, wal_segsz_bytes) \
  (((xlrp) / (wal_segsz_bytes)) == (logSegNo))

#define XLByteInPrevSeg(xlrp, logSegNo, wal_segsz_bytes) \
  ((((xlrp) - 1) / (wal_segsz_bytes)) == (logSegNo))

/* Check if an XLogRecPtr value is in a plausible range */
#define XRecOffIsValid(xlrp) \
    ((xlrp) % XLOG_BLCKSZ >= SizeOfXLogShortPHD)

/*
 * The XLog directory and control file (relative to $PGDATA)
 */
#define XLOGDIR       "pg_wal"
#define XLOG_CONTROL_FILE "global/pg_control"

/*
 * These macros encapsulate knowledge about the exact layout of XLog file
 * names, timeline history file names, and archive-status file names.
 */
#define MAXFNAMELEN   64

/* Length of XLog file name */
#define XLOG_FNAME_LEN     24

/*
 * Generate a WAL segment file name.  Do not use this function in a helper
 * function allocating the result generated.
 */
static inline void
XLogFileName(char *fname, TimeLineID tli, XLogSegNo logSegNo, int wal_segsz_bytes)
{
  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli,
       (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
       (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)));
}

static inline void
XLogFileNameById(char *fname, TimeLineID tli, uint32 log, uint32 seg)
{
  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X", tli, log, seg);
}

static inline bool
IsXLogFileName(const char *fname)
{
  return (strlen(fname) == XLOG_FNAME_LEN && \
      strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN);
}

/*
 * XLOG segment with .partial suffix.  Used by pg_receivewal and at end of
 * archive recovery, when we want to archive a WAL segment but it might not
 * be complete yet.
 */
static inline bool
IsPartialXLogFileName(const char *fname)
{
  return (strlen(fname) == XLOG_FNAME_LEN + strlen(".partial") &&
      strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN &&
      strcmp(fname + XLOG_FNAME_LEN, ".partial") == 0);
}

static inline void
XLogFromFileName(const char *fname, TimeLineID *tli, XLogSegNo *logSegNo, int wal_segsz_bytes)
{
  uint32    log;
  uint32    seg;

  sscanf(fname, "%08X%08X%08X", tli, &log, &seg);
  *logSegNo = (uint64) log * XLogSegmentsPerXLogId(wal_segsz_bytes) + seg;
}

static inline void
XLogFilePath(char *path, TimeLineID tli, XLogSegNo logSegNo, int wal_segsz_bytes)
{
  snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X", tli,
       (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
       (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)));
}

static inline void
TLHistoryFileName(char *fname, TimeLineID tli)
{
  snprintf(fname, MAXFNAMELEN, "%08X.history", tli);
}

static inline bool
IsTLHistoryFileName(const char *fname)
{
  return (strlen(fname) == 8 + strlen(".history") &&
      strspn(fname, "0123456789ABCDEF") == 8 &&
      strcmp(fname + 8, ".history") == 0);
}

static inline void
TLHistoryFilePath(char *path, TimeLineID tli)
{
  snprintf(path, MAXPGPATH, XLOGDIR "/%08X.history", tli);
}

static inline void
StatusFilePath(char *path, const char *xlog, const char *suffix)
{
  snprintf(path, MAXPGPATH, XLOGDIR "/archive_status/%s%s", xlog, suffix);
}

static inline void
BackupHistoryFileName(char *fname, TimeLineID tli, XLogSegNo logSegNo, XLogRecPtr startpoint, int wal_segsz_bytes)
{
  snprintf(fname, MAXFNAMELEN, "%08X%08X%08X.%08X.backup", tli,
       (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
       (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)),
       (uint32) (XLogSegmentOffset(startpoint, wal_segsz_bytes)));
}

static inline bool
IsBackupHistoryFileName(const char *fname)
{
  return (strlen(fname) > XLOG_FNAME_LEN &&
      strspn(fname, "0123456789ABCDEF") == XLOG_FNAME_LEN &&
      strcmp(fname + strlen(fname) - strlen(".backup"), ".backup") == 0);
}

static inline void
BackupHistoryFilePath(char *path, TimeLineID tli, XLogSegNo logSegNo, XLogRecPtr startpoint, int wal_segsz_bytes)
{
  snprintf(path, MAXPGPATH, XLOGDIR "/%08X%08X%08X.%08X.backup", tli,
       (uint32) (logSegNo / XLogSegmentsPerXLogId(wal_segsz_bytes)),
       (uint32) (logSegNo % XLogSegmentsPerXLogId(wal_segsz_bytes)),
       (uint32) (XLogSegmentOffset((startpoint), wal_segsz_bytes)));
}

/*
 * Information logged when we detect a change in one of the parameters
 * important for Hot Standby.
 */
typedef struct xl_parameter_change
{
  int     MaxConnections;
  int     max_worker_processes;
  int     max_wal_senders;
  int     max_prepared_xacts;
  int     max_locks_per_xact;
  int     wal_level;
  bool    wal_log_hints;
  bool    track_commit_timestamp;
} xl_parameter_change;

/* logs restore point */
typedef struct xl_restore_point
{
  TimestampTz rp_time;
  char    rp_name[MAXFNAMELEN];
} xl_restore_point;

/* Overwrite of prior contrecord */
typedef struct xl_overwrite_contrecord
{
  XLogRecPtr  overwritten_lsn;
  TimestampTz overwrite_time;
} xl_overwrite_contrecord;

/* End of recovery mark, when we don't do an END_OF_RECOVERY checkpoint */
typedef struct xl_end_of_recovery
{
  TimestampTz end_time;
  TimeLineID  ThisTimeLineID; /* new TLI */
  TimeLineID  PrevTimeLineID; /* previous TLI we forked off from */
  int     wal_level;
} xl_end_of_recovery;

/*
 * The functions in xloginsert.c construct a chain of XLogRecData structs
 * to represent the final WAL record.
 */
typedef struct XLogRecData
{
  struct XLogRecData *next; /* next struct in chain, or NULL */
  const void *data;     /* start of rmgr data to include */
  uint32    len;      /* length of rmgr data to include */
} XLogRecData;

/*
 * Recovery target action.
 */
typedef enum
{
  RECOVERY_TARGET_ACTION_PAUSE,
  RECOVERY_TARGET_ACTION_PROMOTE,
  RECOVERY_TARGET_ACTION_SHUTDOWN,
}     RecoveryTargetAction;

struct LogicalDecodingContext;
struct XLogRecordBuffer;

/*
 * Method table for resource managers.
 *
 * This struct must be kept in sync with the PG_RMGR definition in
 * rmgr.c.
 *
 * rm_identify must return a name for the record based on xl_info (without
 * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
 * "VACUUM". rm_desc can then be called to obtain additional detail for the
 * record, if available (e.g. the last block).
 *
 * rm_mask takes as input a page modified by the resource manager and masks
 * out bits that shouldn't be flagged by wal_consistency_checking.
 *
 * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
 * NULL, the corresponding RmgrTable entry is considered invalid.
 */
typedef struct RmgrData
{
  const char *rm_name;
  void    (*rm_redo) (XLogReaderState *record);
  void    (*rm_desc) (StringInfo buf, XLogReaderState *record);
  const char *(*rm_identify) (uint8 info);
  void    (*rm_startup) (void);
  void    (*rm_cleanup) (void);
  void    (*rm_mask) (char *pagedata, BlockNumber blkno);
  void    (*rm_decode) (struct LogicalDecodingContext *ctx,
                struct XLogRecordBuffer *buf);
} RmgrData;

extern PGDLLIMPORT RmgrData RmgrTable[];
extern void RmgrStartup(void);
extern void RmgrCleanup(void);
extern void RmgrNotFound(RmgrId rmid);
extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);

#ifndef FRONTEND
static inline bool
RmgrIdExists(RmgrId rmid)
{
  return RmgrTable[rmid].rm_name != NULL;
}

static inline RmgrData
GetRmgr(RmgrId rmid)
{
  if (unlikely(!RmgrIdExists(rmid)))
    RmgrNotFound(rmid);
  return RmgrTable[rmid];
}
#endif

/*
 * Exported to support xlog switching from checkpointer
 */
extern pg_time_t GetLastSegSwitchData(XLogRecPtr *lastSwitchLSN);
extern XLogRecPtr RequestXLogSwitch(bool mark_unimportant);

extern void GetOldestRestartPoint(XLogRecPtr *oldrecptr, TimeLineID *oldtli);

extern void XLogRecGetBlockRefInfo(XLogReaderState *record, bool pretty,
                   bool detailed_format, StringInfo buf,
                   uint32 *fpi_len);

/*
 * Exported for the functions in timeline.c and xlogarchive.c.  Only valid
 * in the startup process.
 */
extern PGDLLIMPORT bool ArchiveRecoveryRequested;
extern PGDLLIMPORT bool InArchiveRecovery;
extern PGDLLIMPORT bool StandbyMode;
extern PGDLLIMPORT char *recoveryRestoreCommand;

#endif              /* XLOG_INTERNAL_H */

Coverage Report

Created: 2025-06-15 06:31

Line	Count	Source (jump to first uncovered line)
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-2025, 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/relfilelocator.h"
29
30
31		/*
32		* Each page of XLOG file has a header like this:
33		*/
34	0	#define XLOG_PAGE_MAGIC 0xD118 /* 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 */