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