[PATCH] Clarify the comments about varlena header encoding

From: Aleksander Alekseev <aleksander(at)timescale(dot)com>
To: PostgreSQL Hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Subject: [PATCH] Clarify the comments about varlena header encoding
Date: 2022-08-17 18:06:38
Message-ID: CAJ7c6TOY_-mew61g4okz7H6+09JrwmTZEn3JnwVyeWhRXNzZGA@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

Hi hackers,

I noticed that the comments regarding bit layouts for varlena headers
in postgres.h are somewhat misleading. For instance, when reading:

```
00xxxxxx 4-byte length word, aligned, uncompressed data (up to 1G)
```

... one can assume this is a 00xxxxxx byte followed by another 4 bytes
(which is wrong). Also one can read this as "aligned, uncompressed
data" (which again is wrong).

```
10000000 1-byte length word, unaligned, TOAST pointer
```

This is misleading too. The comments above this line say that `struct
varatt_external` is a TOAST pointer. sizeof(varatt_external) = 16,
plus 1 byte equals 17, right? However the documentation [1] claims the
result should be 18:

"""
Allowing for the varlena header bytes, the total size of an on-disk
TOAST pointer datum is therefore 18 bytes regardless of the actual
size of the represented value.
"""

I did my best to get rid of any ambiguity. The patch is attached.

[1]: https://www.postgresql.org/docs/current/storage-toast.html

--
Best regards,
Aleksander Alekseev

Attachment Content-Type Size
v1-0001-Clarify-the-comments-about-varlena-header-encodin.patch application/octet-stream 3.3 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Alvaro Herrera 2022-08-17 18:12:49 cataloguing NOT NULL constraints
Previous Message Robert Haas 2022-08-17 17:44:23 Re: pg_walinspect: ReadNextXLogRecord's first_record argument