1 /*------------------------------------------------------------------------- 2 * 3 * datum.c 4 * POSTGRES Datum (abstract data type) manipulation routines. 5 * 6 * Portions Copyright (c) 1996-2021, 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 142 if (VARATT_IS_EXTERNAL_EXPANDED(vl)) 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 && 196 VARATT_IS_EXTERNAL_EXPANDED_RW(DatumGetPointer(value))) 197 value = TransferExpandedObject(value, CurrentMemoryContext); 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 345 btequalimage(PG_FUNCTION_ARGS) 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 && 370 VARATT_IS_EXTERNAL_EXPANDED(DatumGetPointer(value))) 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 && 419 VARATT_IS_EXTERNAL_EXPANDED(DatumGetPointer(value))) 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 } 505