PostgreSQL Source Code  git master
datum.c
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * datum.c
4  * POSTGRES Datum (abstract data type) manipulation routines.
5  *
6  * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
7  * Portions Copyright (c) 1994, Regents of the University of California
8  *
9  *
10  * IDENTIFICATION
11  * src/backend/utils/adt/datum.c
12  *
13  *-------------------------------------------------------------------------
14  */
15 
16 /*
17  * In the implementation of these routines we assume the following:
18  *
19  * A) if a type is "byVal" then all the information is stored in the
20  * Datum itself (i.e. no pointers involved!). In this case the
21  * length of the type is always greater than zero and not more than
22  * "sizeof(Datum)"
23  *
24  * B) if a type is not "byVal" and it has a fixed length (typlen > 0),
25  * then the "Datum" always contains a pointer to a stream of bytes.
26  * The number of significant bytes are always equal to the typlen.
27  *
28  * C) if a type is not "byVal" and has typlen == -1,
29  * then the "Datum" always points to a "struct varlena".
30  * This varlena structure has information about the actual length of this
31  * particular instance of the type and about its value.
32  *
33  * D) if a type is not "byVal" and has typlen == -2,
34  * then the "Datum" always points to a null-terminated C string.
35  *
36  * Note that we do not treat "toasted" datums specially; therefore what
37  * will be copied or compared is the compressed data or toast reference.
38  * An exception is made for datumCopy() of an expanded object, however,
39  * because most callers expect to get a simple contiguous (and pfree'able)
40  * result from datumCopy(). See also datumTransfer().
41  */
42 
43 #include "postgres.h"
44 
45 #include "access/detoast.h"
46 #include "fmgr.h"
47 #include "utils/builtins.h"
48 #include "utils/datum.h"
49 #include "utils/expandeddatum.h"
50 
51 
52 /*-------------------------------------------------------------------------
53  * datumGetSize
54  *
55  * Find the "real" size of a datum, given the datum value,
56  * whether it is a "by value", and the declared type length.
57  * (For TOAST pointer datums, this is the size of the pointer datum.)
58  *
59  * This is essentially an out-of-line version of the att_addlength_datum()
60  * macro in access/tupmacs.h. We do a tad more error checking though.
61  *-------------------------------------------------------------------------
62  */
63 Size
64 datumGetSize(Datum value, bool typByVal, int typLen)
65 {
66  Size size;
67 
68  if (typByVal)
69  {
70  /* Pass-by-value types are always fixed-length */
71  Assert(typLen > 0 && typLen <= sizeof(Datum));
72  size = (Size) typLen;
73  }
74  else
75  {
76  if (typLen > 0)
77  {
78  /* Fixed-length pass-by-ref type */
79  size = (Size) typLen;
80  }
81  else if (typLen == -1)
82  {
83  /* It is a varlena datatype */
84  struct varlena *s = (struct varlena *) DatumGetPointer(value);
85 
86  if (!PointerIsValid(s))
87  ereport(ERROR,
88  (errcode(ERRCODE_DATA_EXCEPTION),
89  errmsg("invalid Datum pointer")));
90 
91  size = (Size) VARSIZE_ANY(s);
92  }
93  else if (typLen == -2)
94  {
95  /* It is a cstring datatype */
96  char *s = (char *) DatumGetPointer(value);
97 
98  if (!PointerIsValid(s))
99  ereport(ERROR,
100  (errcode(ERRCODE_DATA_EXCEPTION),
101  errmsg("invalid Datum pointer")));
102 
103  size = (Size) (strlen(s) + 1);
104  }
105  else
106  {
107  elog(ERROR, "invalid typLen: %d", typLen);
108  size = 0; /* keep compiler quiet */
109  }
110  }
111 
112  return size;
113 }
114 
115 /*-------------------------------------------------------------------------
116  * datumCopy
117  *
118  * Make a copy of a non-NULL datum.
119  *
120  * If the datatype is pass-by-reference, memory is obtained with palloc().
121  *
122  * If the value is a reference to an expanded object, we flatten into memory
123  * obtained with palloc(). We need to copy because one of the main uses of
124  * this function is to copy a datum out of a transient memory context that's
125  * about to be destroyed, and the expanded object is probably in a child
126  * context that will also go away. Moreover, many callers assume that the
127  * result is a single pfree-able chunk.
128  *-------------------------------------------------------------------------
129  */
130 Datum
131 datumCopy(Datum value, bool typByVal, int typLen)
132 {
133  Datum res;
134 
135  if (typByVal)
136  res = value;
137  else if (typLen == -1)
138  {
139  /* It is a varlena datatype */
140  struct varlena *vl = (struct varlena *) DatumGetPointer(value);
141 
143  {
144  /* Flatten into the caller's memory context */
145  ExpandedObjectHeader *eoh = DatumGetEOHP(value);
146  Size resultsize;
147  char *resultptr;
148 
149  resultsize = EOH_get_flat_size(eoh);
150  resultptr = (char *) palloc(resultsize);
151  EOH_flatten_into(eoh, (void *) resultptr, resultsize);
152  res = PointerGetDatum(resultptr);
153  }
154  else
155  {
156  /* Otherwise, just copy the varlena datum verbatim */
157  Size realSize;
158  char *resultptr;
159 
160  realSize = (Size) VARSIZE_ANY(vl);
161  resultptr = (char *) palloc(realSize);
162  memcpy(resultptr, vl, realSize);
163  res = PointerGetDatum(resultptr);
164  }
165  }
166  else
167  {
168  /* Pass by reference, but not varlena, so not toasted */
169  Size realSize;
170  char *resultptr;
171 
172  realSize = datumGetSize(value, typByVal, typLen);
173 
174  resultptr = (char *) palloc(realSize);
175  memcpy(resultptr, DatumGetPointer(value), realSize);
176  res = PointerGetDatum(resultptr);
177  }
178  return res;
179 }
180 
181 /*-------------------------------------------------------------------------
182  * datumTransfer
183  *
184  * Transfer a non-NULL datum into the current memory context.
185  *
186  * This is equivalent to datumCopy() except when the datum is a read-write
187  * pointer to an expanded object. In that case we merely reparent the object
188  * into the current context, and return its standard R/W pointer (in case the
189  * given one is a transient pointer of shorter lifespan).
190  *-------------------------------------------------------------------------
191  */
192 Datum
193 datumTransfer(Datum value, bool typByVal, int typLen)
194 {
195  if (!typByVal && typLen == -1 &&
198  else
199  value = datumCopy(value, typByVal, typLen);
200  return value;
201 }
202 
203 /*-------------------------------------------------------------------------
204  * datumIsEqual
205  *
206  * Return true if two datums are equal, false otherwise
207  *
208  * NOTE: XXX!
209  * We just compare the bytes of the two values, one by one.
210  * This routine will return false if there are 2 different
211  * representations of the same value (something along the lines
212  * of say the representation of zero in one's complement arithmetic).
213  * Also, it will probably not give the answer you want if either
214  * datum has been "toasted".
215  *
216  * Do not try to make this any smarter than it currently is with respect
217  * to "toasted" datums, because some of the callers could be working in the
218  * context of an aborted transaction.
219  *-------------------------------------------------------------------------
220  */
221 bool
222 datumIsEqual(Datum value1, Datum value2, bool typByVal, int typLen)
223 {
224  bool res;
225 
226  if (typByVal)
227  {
228  /*
229  * just compare the two datums. NOTE: just comparing "len" bytes will
230  * not do the work, because we do not know how these bytes are aligned
231  * inside the "Datum". We assume instead that any given datatype is
232  * consistent about how it fills extraneous bits in the Datum.
233  */
234  res = (value1 == value2);
235  }
236  else
237  {
238  Size size1,
239  size2;
240  char *s1,
241  *s2;
242 
243  /*
244  * Compare the bytes pointed by the pointers stored in the datums.
245  */
246  size1 = datumGetSize(value1, typByVal, typLen);
247  size2 = datumGetSize(value2, typByVal, typLen);
248  if (size1 != size2)
249  return false;
250  s1 = (char *) DatumGetPointer(value1);
251  s2 = (char *) DatumGetPointer(value2);
252  res = (memcmp(s1, s2, size1) == 0);
253  }
254  return res;
255 }
256 
257 /*-------------------------------------------------------------------------
258  * datum_image_eq
259  *
260  * Compares two datums for identical contents, based on byte images. Return
261  * true if the two datums are equal, false otherwise.
262  *-------------------------------------------------------------------------
263  */
264 bool
265 datum_image_eq(Datum value1, Datum value2, bool typByVal, int typLen)
266 {
267  Size len1,
268  len2;
269  bool result = true;
270 
271  if (typByVal)
272  {
273  result = (value1 == value2);
274  }
275  else if (typLen > 0)
276  {
277  result = (memcmp(DatumGetPointer(value1),
278  DatumGetPointer(value2),
279  typLen) == 0);
280  }
281  else if (typLen == -1)
282  {
283  len1 = toast_raw_datum_size(value1);
284  len2 = toast_raw_datum_size(value2);
285  /* No need to de-toast if lengths don't match. */
286  if (len1 != len2)
287  result = false;
288  else
289  {
290  struct varlena *arg1val;
291  struct varlena *arg2val;
292 
293  arg1val = PG_DETOAST_DATUM_PACKED(value1);
294  arg2val = PG_DETOAST_DATUM_PACKED(value2);
295 
296  result = (memcmp(VARDATA_ANY(arg1val),
297  VARDATA_ANY(arg2val),
298  len1 - VARHDRSZ) == 0);
299 
300  /* Only free memory if it's a copy made here. */
301  if ((Pointer) arg1val != (Pointer) value1)
302  pfree(arg1val);
303  if ((Pointer) arg2val != (Pointer) value2)
304  pfree(arg2val);
305  }
306  }
307  else if (typLen == -2)
308  {
309  char *s1,
310  *s2;
311 
312  /* Compare cstring datums */
313  s1 = DatumGetCString(value1);
314  s2 = DatumGetCString(value2);
315  len1 = strlen(s1) + 1;
316  len2 = strlen(s2) + 1;
317  if (len1 != len2)
318  return false;
319  result = (memcmp(s1, s2, len1) == 0);
320  }
321  else
322  elog(ERROR, "unexpected typLen: %d", typLen);
323 
324  return result;
325 }
326 
327 /*-------------------------------------------------------------------------
328  * btequalimage
329  *
330  * Generic "equalimage" support function.
331  *
332  * B-Tree operator classes whose equality function could safely be replaced by
333  * datum_image_eq() in all cases can use this as their "equalimage" support
334  * function.
335  *
336  * Currently, we unconditionally assume that any B-Tree operator class that
337  * registers btequalimage as its support function 4 must be able to safely use
338  * optimizations like deduplication (i.e. we return true unconditionally). If
339  * it ever proved necessary to rescind support for an operator class, we could
340  * do that in a targeted fashion by doing something with the opcintype
341  * argument.
342  *-------------------------------------------------------------------------
343  */
344 Datum
346 {
347  /* Oid opcintype = PG_GETARG_OID(0); */
348 
349  PG_RETURN_BOOL(true);
350 }
351 
352 /*-------------------------------------------------------------------------
353  * datumEstimateSpace
354  *
355  * Compute the amount of space that datumSerialize will require for a
356  * particular Datum.
357  *-------------------------------------------------------------------------
358  */
359 Size
360 datumEstimateSpace(Datum value, bool isnull, bool typByVal, int typLen)
361 {
362  Size sz = sizeof(int);
363 
364  if (!isnull)
365  {
366  /* no need to use add_size, can't overflow */
367  if (typByVal)
368  sz += sizeof(Datum);
369  else if (typLen == -1 &&
371  {
372  /* Expanded objects need to be flattened, see comment below */
373  sz += EOH_get_flat_size(DatumGetEOHP(value));
374  }
375  else
376  sz += datumGetSize(value, typByVal, typLen);
377  }
378 
379  return sz;
380 }
381 
382 /*-------------------------------------------------------------------------
383  * datumSerialize
384  *
385  * Serialize a possibly-NULL datum into caller-provided storage.
386  *
387  * Note: "expanded" objects are flattened so as to produce a self-contained
388  * representation, but other sorts of toast pointers are transferred as-is.
389  * This is because the intended use of this function is to pass the value
390  * to another process within the same database server. The other process
391  * could not access an "expanded" object within this process's memory, but
392  * we assume it can dereference the same TOAST pointers this one can.
393  *
394  * The format is as follows: first, we write a 4-byte header word, which
395  * is either the length of a pass-by-reference datum, -1 for a
396  * pass-by-value datum, or -2 for a NULL. If the value is NULL, nothing
397  * further is written. If it is pass-by-value, sizeof(Datum) bytes
398  * follow. Otherwise, the number of bytes indicated by the header word
399  * follow. The caller is responsible for ensuring that there is enough
400  * storage to store the number of bytes that will be written; use
401  * datumEstimateSpace() to find out how many will be needed.
402  * *start_address is updated to point to the byte immediately following
403  * those written.
404  *-------------------------------------------------------------------------
405  */
406 void
407 datumSerialize(Datum value, bool isnull, bool typByVal, int typLen,
408  char **start_address)
409 {
410  ExpandedObjectHeader *eoh = NULL;
411  int header;
412 
413  /* Write header word. */
414  if (isnull)
415  header = -2;
416  else if (typByVal)
417  header = -1;
418  else if (typLen == -1 &&
420  {
421  eoh = DatumGetEOHP(value);
422  header = EOH_get_flat_size(eoh);
423  }
424  else
425  header = datumGetSize(value, typByVal, typLen);
426  memcpy(*start_address, &header, sizeof(int));
427  *start_address += sizeof(int);
428 
429  /* If not null, write payload bytes. */
430  if (!isnull)
431  {
432  if (typByVal)
433  {
434  memcpy(*start_address, &value, sizeof(Datum));
435  *start_address += sizeof(Datum);
436  }
437  else if (eoh)
438  {
439  char *tmp;
440 
441  /*
442  * EOH_flatten_into expects the target address to be maxaligned,
443  * so we can't store directly to *start_address.
444  */
445  tmp = (char *) palloc(header);
446  EOH_flatten_into(eoh, (void *) tmp, header);
447  memcpy(*start_address, tmp, header);
448  *start_address += header;
449 
450  /* be tidy. */
451  pfree(tmp);
452  }
453  else
454  {
455  memcpy(*start_address, DatumGetPointer(value), header);
456  *start_address += header;
457  }
458  }
459 }
460 
461 /*-------------------------------------------------------------------------
462  * datumRestore
463  *
464  * Restore a possibly-NULL datum previously serialized by datumSerialize.
465  * *start_address is updated according to the number of bytes consumed.
466  *-------------------------------------------------------------------------
467  */
468 Datum
469 datumRestore(char **start_address, bool *isnull)
470 {
471  int header;
472  void *d;
473 
474  /* Read header word. */
475  memcpy(&header, *start_address, sizeof(int));
476  *start_address += sizeof(int);
477 
478  /* If this datum is NULL, we can stop here. */
479  if (header == -2)
480  {
481  *isnull = true;
482  return (Datum) 0;
483  }
484 
485  /* OK, datum is not null. */
486  *isnull = false;
487 
488  /* If this datum is pass-by-value, sizeof(Datum) bytes follow. */
489  if (header == -1)
490  {
491  Datum val;
492 
493  memcpy(&val, *start_address, sizeof(Datum));
494  *start_address += sizeof(Datum);
495  return val;
496  }
497 
498  /* Pass-by-reference case; copy indicated number of bytes. */
499  Assert(header > 0);
500  d = palloc(header);
501  memcpy(d, *start_address, header);
502  *start_address += header;
503  return PointerGetDatum(d);
504 }
Datum btequalimage(PG_FUNCTION_ARGS)
Definition: datum.c:345
#define VARDATA_ANY(PTR)
Definition: postgres.h:348
#define VARATT_IS_EXTERNAL_EXPANDED(PTR)
Definition: postgres.h:322
#define PointerGetDatum(X)
Definition: postgres.h:556
#define VARHDRSZ
Definition: c.h:561
bool datumIsEqual(Datum value1, Datum value2, bool typByVal, int typLen)
Definition: datum.c:222
int errcode(int sqlerrcode)
Definition: elog.c:610
Datum TransferExpandedObject(Datum d, MemoryContext new_parent)
void pfree(void *pointer)
Definition: mcxt.c:1056
char * Pointer
Definition: c.h:344
#define ERROR
Definition: elog.h:43
char * s1
#define DatumGetCString(X)
Definition: postgres.h:566
#define PG_DETOAST_DATUM_PACKED(datum)
Definition: fmgr.h:248
MemoryContext CurrentMemoryContext
Definition: mcxt.c:38
Size EOH_get_flat_size(ExpandedObjectHeader *eohptr)
Definition: expandeddatum.c:75
Size toast_raw_datum_size(Datum value)
Definition: detoast.c:502
Datum datumCopy(Datum value, bool typByVal, int typLen)
Definition: datum.c:131
Size datumEstimateSpace(Datum value, bool isnull, bool typByVal, int typLen)
Definition: datum.c:360
ExpandedObjectHeader * DatumGetEOHP(Datum d)
Definition: expandeddatum.c:29
char * s2
#define PG_RETURN_BOOL(x)
Definition: fmgr.h:358
uintptr_t Datum
Definition: postgres.h:367
Datum datumRestore(char **start_address, bool *isnull)
Definition: datum.c:469
void EOH_flatten_into(ExpandedObjectHeader *eohptr, void *result, Size allocated_size)
Definition: expandeddatum.c:81
#define VARSIZE_ANY(PTR)
Definition: postgres.h:335
static struct @143 value
#define ereport(elevel,...)
Definition: elog.h:144
Datum datumTransfer(Datum value, bool typByVal, int typLen)
Definition: datum.c:193
#define Assert(condition)
Definition: c.h:738
size_t Size
Definition: c.h:466
static void header(const char *fmt,...) pg_attribute_printf(1
Definition: pg_regress.c:208
#define DatumGetPointer(X)
Definition: postgres.h:549
void * palloc(Size size)
Definition: mcxt.c:949
int errmsg(const char *fmt,...)
Definition: elog.c:824
#define elog(elevel,...)
Definition: elog.h:214
void datumSerialize(Datum value, bool isnull, bool typByVal, int typLen, char **start_address)
Definition: datum.c:407
#define VARATT_IS_EXTERNAL_EXPANDED_RW(PTR)
Definition: postgres.h:320
bool datum_image_eq(Datum value1, Datum value2, bool typByVal, int typLen)
Definition: datum.c:265
Definition: c.h:555
#define PG_FUNCTION_ARGS
Definition: fmgr.h:193
Size datumGetSize(Datum value, bool typByVal, int typLen)
Definition: datum.c:64
#define PointerIsValid(pointer)
Definition: c.h:632
long val
Definition: informix.c:664