diff -r b1373253e202 -r 3e4905241838 src/cx/buffer.h
--- a/src/cx/buffer.h	Thu Dec 19 12:00:20 2024 +0100
+++ b/src/cx/buffer.h	Thu Dec 19 21:33:45 2024 +0100
@@ -79,6 +79,15 @@
  */
 #define CX_BUFFER_COPY_ON_WRITE 0x04
 
+/**
+ * If this flag is enabled, the buffer will copy its contents to a new memory area on reallocation.
+ *
+ * After performing the copy, the flag is automatically cleared.
+ * This flag has no effect on buffers which do not have #CX_BUFFER_AUTO_EXTEND set, which is why
+ * buffers automatically admit the auto-extend flag when initialized with copy-on-extend enabled.
+ */
+#define CX_BUFFER_COPY_ON_EXTEND 0x08
+
 /** Structure for the UCX buffer data. */
 typedef struct {
     /** A pointer to the buffer contents. */
@@ -156,6 +165,11 @@
  * you will need to cast the pointer, and you should set the
  * #CX_BUFFER_COPY_ON_WRITE flag.
  *
+ * When you specify stack memory as \p space and decide to use
+ * the auto-extension feature, you \em must use the
+ * #CX_BUFFER_COPY_ON_EXTEND flag, instead of the
+ * #CX_BUFFER_AUTO_EXTEND flag.
+ *
  * \note You may provide \c NULL as argument for \p space.
  * Then this function will allocate the space and enforce
  * the #CX_BUFFER_FREE_CONTENTS flag. In that case, specifying
@@ -213,6 +227,10 @@
  * You may also provide a read-only \p space, in which case
  * you will need to cast the pointer, and you should set the
  * #CX_BUFFER_COPY_ON_WRITE flag.
+ * When you specify stack memory as \p space and decide to use
+ * the auto-extension feature, you \em must use the
+ * #CX_BUFFER_COPY_ON_EXTEND flag, instead of the
+ * #CX_BUFFER_AUTO_EXTEND flag.
  *
  * \note You may provide \c NULL as argument for \p space.
  * Then this function will allocate the space and enforce