From e21e91ad1f72f79a944c42cf8d7bd97ce40639e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9B=D0=B5=D0=BE=D0=BD=D0=B8=D0=B4=20=D0=AE=D1=80=D1=8C?= =?UTF-8?q?=D0=B5=D0=B2=20=28Leonid=20Yuriev=29?= Date: Sun, 8 Oct 2023 11:55:30 +0300 Subject: [PATCH] =?UTF-8?q?mdbx-doc:=20=D1=83=D1=82=D0=BE=D1=87=D0=BD?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B5=20=D1=84=D0=BE=D1=80=D0=BC=D1=83=D0=BB?= =?UTF-8?q?=D0=B8=D1=80=D0=BE=D0=B2=D0=BE=D0=BA=20=D0=BE=20`SIGSEGV`=20?= =?UTF-8?q?=D0=B8=20=D0=BD=D0=B5=D0=B4=D0=BE=D0=BF=D1=83=D1=81=D1=82=D0=B8?= =?UTF-8?q?=D0=BC=D0=BE=D1=81=D1=82=D0=B8=20=D0=BF=D1=80=D1=8F=D0=BC=D0=BE?= =?UTF-8?q?=D0=B3=D0=BE=20=D0=B8=D0=B7=D0=BC=D0=B5=D0=BD=D0=B5=D0=BD=D0=B8?= =?UTF-8?q?=D1=8F=20=D0=B4=D0=B0=D0=BD=D0=BD=D1=8B=D1=85.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ChangeLog.md | 2 ++ mdbx.h | 37 +++++++++++++++++++++++++++++++------ 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/ChangeLog.md b/ChangeLog.md index 0da19fb2..b2aa1db5 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -29,6 +29,8 @@ and [by Yandex](https://translated.turbopages.org/proxy_u/ru-en.en/https/gitflic - Микрооптимизация и рефакториг `cursor_put_nochecklen()` в продолжение исправления регресса/ошибки в пути обработки `put(MDBX_MULTIPLE)`. + - Уточнение формулировок о `SIGSEGV` и недопустимости прямого изменения данных. + Мелочи: - Исправление несущественных предупреждений при `MDBX_ENABLE_PROFGC=ON`. diff --git a/mdbx.h b/mdbx.h index 65940cff..575961bf 100644 --- a/mdbx.h +++ b/mdbx.h @@ -2846,9 +2846,9 @@ LIBMDBX_INLINE_API(int, mdbx_env_get_syncperiod, * * Only a single thread may call this function. All transactions, databases, * and cursors must already be closed before calling this function. Attempts - * to use any such handles after calling this function will cause a `SIGSEGV`. - * The environment handle will be freed and must not be used again after this - * call. + * to use any such handles after calling this function is UB and would cause + * a `SIGSEGV`. The environment handle will be freed and must not be used again + * after this call. * * \param [in] env An environment handle returned by * \ref mdbx_env_create(). @@ -4398,9 +4398,14 @@ LIBMDBX_API int mdbx_drop(MDBX_txn *txn, MDBX_dbi dbi, bool del); * items requires the use of \ref mdbx_cursor_get(). * * \note The memory pointed to by the returned values is owned by the - * database. The caller need not dispose of the memory, and may not - * modify it in any way. For values returned in a read-only transaction - * any modification attempts will cause a `SIGSEGV`. + * database. The caller MUST not dispose of the memory, and MUST not modify it + * in any way regardless in a read-only nor read-write transactions! + * For case a database opened without the \ref MDBX_WRITEMAP modification + * attempts likely will cause a `SIGSEGV`. However, when a database opened with + * the \ref MDBX_WRITEMAP or in case values returned inside read-write + * transaction are located on a "dirty" (modified and pending to commit) pages, + * such modification will silently accepted and likely will lead to DB and/or + * data corruption. * * \note Values returned from the database are valid only until a * subsequent update operation, or the end of the transaction. @@ -4834,6 +4839,16 @@ LIBMDBX_API int mdbx_cursor_copy(const MDBX_cursor *src, MDBX_cursor *dest); * to which data refers. * \see mdbx_get() * + * \note The memory pointed to by the returned values is owned by the + * database. The caller MUST not dispose of the memory, and MUST not modify it + * in any way regardless in a read-only nor read-write transactions! + * For case a database opened without the \ref MDBX_WRITEMAP modification + * attempts likely will cause a `SIGSEGV`. However, when a database opened with + * the \ref MDBX_WRITEMAP or in case values returned inside read-write + * transaction are located on a "dirty" (modified and pending to commit) pages, + * such modification will silently accepted and likely will lead to DB and/or + * data corruption. + * * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). * \param [in,out] key The key for a retrieved item. * \param [in,out] data The data of a retrieved item. @@ -4860,6 +4875,16 @@ LIBMDBX_API int mdbx_cursor_get(MDBX_cursor *cursor, MDBX_val *key, * array to which `pairs` refers. * \see mdbx_cursor_get() * + * \note The memory pointed to by the returned values is owned by the + * database. The caller MUST not dispose of the memory, and MUST not modify it + * in any way regardless in a read-only nor read-write transactions! + * For case a database opened without the \ref MDBX_WRITEMAP modification + * attempts likely will cause a `SIGSEGV`. However, when a database opened with + * the \ref MDBX_WRITEMAP or in case values returned inside read-write + * transaction are located on a "dirty" (modified and pending to commit) pages, + * such modification will silently accepted and likely will lead to DB and/or + * data corruption. + * * \param [in] cursor A cursor handle returned by \ref mdbx_cursor_open(). * \param [out] count The number of key and value item returned, on success * it always be the even because the key-value