PostgreSQL Source Code git master
itemptr.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * itemptr.h
4 * POSTGRES disk item pointer definitions.
5 *
6 *
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
9 *
10 * src/include/storage/itemptr.h
11 *
12 *-------------------------------------------------------------------------
13 */
14#ifndef ITEMPTR_H
15#define ITEMPTR_H
16
17#include "storage/block.h"
18#include "storage/off.h"
19
20/*
21 * ItemPointer:
22 *
23 * This is a pointer to an item within a disk page of a known file
24 * (for example, a cross-link from an index to its parent table).
25 * ip_blkid tells us which block, ip_posid tells us which entry in
26 * the linp (ItemIdData) array we want.
27 *
28 * Note: because there is an item pointer in each tuple header and index
29 * tuple header on disk, it's very important not to waste space with
30 * structure padding bytes. The struct is designed to be six bytes long
31 * (it contains three int16 fields) but a few compilers will pad it to
32 * eight bytes unless coerced. We apply appropriate persuasion where
33 * possible. If your compiler can't be made to play along, you'll waste
34 * lots of space.
35 */
36typedef struct ItemPointerData
37{
40}
41
42/* If compiler understands packed and aligned pragmas, use those */
43#if defined(pg_attribute_packed) && defined(pg_attribute_aligned)
44 pg_attribute_packed()
46#endif
48
50
51/* ----------------
52 * special values used in heap tuples (t_ctid)
53 * ----------------
54 */
55
56/*
57 * If a heap tuple holds a speculative insertion token rather than a real
58 * TID, ip_posid is set to SpecTokenOffsetNumber, and the token is stored in
59 * ip_blkid. SpecTokenOffsetNumber must be higher than MaxOffsetNumber, so
60 * that it can be distinguished from a valid offset number in a regular item
61 * pointer.
62 */
63#define SpecTokenOffsetNumber 0xfffe
64
65/*
66 * When a tuple is moved to a different partition by UPDATE, the t_ctid of
67 * the old tuple version is set to this magic value.
68 */
69#define MovedPartitionsOffsetNumber 0xfffd
70#define MovedPartitionsBlockNumber InvalidBlockNumber
71
72
73/* ----------------
74 * support functions
75 * ----------------
76 */
77
78/*
79 * ItemPointerIsValid
80 * True iff the disk item pointer is not NULL.
81 */
82static inline bool
84{
85 return PointerIsValid(pointer) && pointer->ip_posid != 0;
86}
87
88/*
89 * ItemPointerGetBlockNumberNoCheck
90 * Returns the block number of a disk item pointer.
91 */
92static inline BlockNumber
94{
95 return BlockIdGetBlockNumber(&pointer->ip_blkid);
96}
97
98/*
99 * ItemPointerGetBlockNumber
100 * As above, but verifies that the item pointer looks valid.
101 */
102static inline BlockNumber
104{
105 Assert(ItemPointerIsValid(pointer));
106 return ItemPointerGetBlockNumberNoCheck(pointer);
107}
108
109/*
110 * ItemPointerGetOffsetNumberNoCheck
111 * Returns the offset number of a disk item pointer.
112 */
113static inline OffsetNumber
115{
116 return pointer->ip_posid;
117}
118
119/*
120 * ItemPointerGetOffsetNumber
121 * As above, but verifies that the item pointer looks valid.
122 */
123static inline OffsetNumber
125{
126 Assert(ItemPointerIsValid(pointer));
127 return ItemPointerGetOffsetNumberNoCheck(pointer);
128}
129
130/*
131 * ItemPointerSet
132 * Sets a disk item pointer to the specified block and offset.
133 */
134static inline void
136{
137 Assert(PointerIsValid(pointer));
138 BlockIdSet(&pointer->ip_blkid, blockNumber);
139 pointer->ip_posid = offNum;
140}
141
142/*
143 * ItemPointerSetBlockNumber
144 * Sets a disk item pointer to the specified block.
145 */
146static inline void
148{
149 Assert(PointerIsValid(pointer));
150 BlockIdSet(&pointer->ip_blkid, blockNumber);
151}
152
153/*
154 * ItemPointerSetOffsetNumber
155 * Sets a disk item pointer to the specified offset.
156 */
157static inline void
159{
160 Assert(PointerIsValid(pointer));
161 pointer->ip_posid = offsetNumber;
162}
163
164/*
165 * ItemPointerCopy
166 * Copies the contents of one disk item pointer to another.
167 *
168 * Should there ever be padding in an ItemPointer this would need to be handled
169 * differently as it's used as hash key.
170 */
171static inline void
172ItemPointerCopy(const ItemPointerData *fromPointer, ItemPointerData *toPointer)
173{
174 Assert(PointerIsValid(toPointer));
175 Assert(PointerIsValid(fromPointer));
176 *toPointer = *fromPointer;
177}
178
179/*
180 * ItemPointerSetInvalid
181 * Sets a disk item pointer to be invalid.
182 */
183static inline void
185{
186 Assert(PointerIsValid(pointer));
188 pointer->ip_posid = InvalidOffsetNumber;
189}
190
191/*
192 * ItemPointerIndicatesMovedPartitions
193 * True iff the block number indicates the tuple has moved to another
194 * partition.
195 */
196static inline bool
198{
199 return
202}
203
204/*
205 * ItemPointerSetMovedPartitions
206 * Indicate that the item referenced by the itempointer has moved into a
207 * different partition.
208 */
209static inline void
211{
213}
214
215/* ----------------
216 * externs
217 * ----------------
218 */
219
220extern bool ItemPointerEquals(ItemPointer pointer1, ItemPointer pointer2);
222extern void ItemPointerInc(ItemPointer pointer);
223extern void ItemPointerDec(ItemPointer pointer);
224
225/* ----------------
226 * Datum conversion functions
227 * ----------------
228 */
229
230static inline ItemPointer
232{
233 return (ItemPointer) DatumGetPointer(X);
234}
235
236static inline Datum
238{
239 return PointerGetDatum(X);
240}
241
242#define PG_GETARG_ITEMPOINTER(n) DatumGetItemPointer(PG_GETARG_DATUM(n))
243#define PG_RETURN_ITEMPOINTER(x) return ItemPointerGetDatum(x)
244
245#endif /* ITEMPTR_H */
uint32 BlockNumber
Definition: block.h:31
#define InvalidBlockNumber
Definition: block.h:33
static void BlockIdSet(BlockIdData *blockId, BlockNumber blockNumber)
Definition: block.h:81
static BlockNumber BlockIdGetBlockNumber(const BlockIdData *blockId)
Definition: block.h:103
#define Assert(condition)
Definition: c.h:815
#define PointerIsValid(pointer)
Definition: c.h:720
int32_t int32
Definition: c.h:484
struct pg_attribute_aligned(8) pg_atomic_uint64
Definition: generic-msvc.h:40
void ItemPointerDec(ItemPointer pointer)
Definition: itemptr.c:114
static void ItemPointerSet(ItemPointerData *pointer, BlockNumber blockNumber, OffsetNumber offNum)
Definition: itemptr.h:135
static void ItemPointerSetInvalid(ItemPointerData *pointer)
Definition: itemptr.h:184
static Datum ItemPointerGetDatum(const ItemPointerData *X)
Definition: itemptr.h:237
static void ItemPointerSetOffsetNumber(ItemPointerData *pointer, OffsetNumber offsetNumber)
Definition: itemptr.h:158
static void ItemPointerSetBlockNumber(ItemPointerData *pointer, BlockNumber blockNumber)
Definition: itemptr.h:147
static OffsetNumber ItemPointerGetOffsetNumber(const ItemPointerData *pointer)
Definition: itemptr.h:124
static bool ItemPointerIndicatesMovedPartitions(const ItemPointerData *pointer)
Definition: itemptr.h:197
#define MovedPartitionsOffsetNumber
Definition: itemptr.h:69
static void ItemPointerSetMovedPartitions(ItemPointerData *pointer)
Definition: itemptr.h:210
static OffsetNumber ItemPointerGetOffsetNumberNoCheck(const ItemPointerData *pointer)
Definition: itemptr.h:114
static BlockNumber ItemPointerGetBlockNumber(const ItemPointerData *pointer)
Definition: itemptr.h:103
static BlockNumber ItemPointerGetBlockNumberNoCheck(const ItemPointerData *pointer)
Definition: itemptr.h:93
void ItemPointerInc(ItemPointer pointer)
Definition: itemptr.c:84
ItemPointerData * ItemPointer
Definition: itemptr.h:49
int32 ItemPointerCompare(ItemPointer arg1, ItemPointer arg2)
Definition: itemptr.c:51
struct ItemPointerData ItemPointerData
#define MovedPartitionsBlockNumber
Definition: itemptr.h:70
bool ItemPointerEquals(ItemPointer pointer1, ItemPointer pointer2)
Definition: itemptr.c:35
static ItemPointer DatumGetItemPointer(Datum X)
Definition: itemptr.h:231
static void ItemPointerCopy(const ItemPointerData *fromPointer, ItemPointerData *toPointer)
Definition: itemptr.h:172
static bool ItemPointerIsValid(const ItemPointerData *pointer)
Definition: itemptr.h:83
#define InvalidOffsetNumber
Definition: off.h:26
uint16 OffsetNumber
Definition: off.h:24
static Datum PointerGetDatum(const void *X)
Definition: postgres.h:327
uintptr_t Datum
Definition: postgres.h:69
static Pointer DatumGetPointer(Datum X)
Definition: postgres.h:317
OffsetNumber ip_posid
Definition: itemptr.h:39
BlockIdData ip_blkid
Definition: itemptr.h:38