sds_misc(3)

🌸 NAME 🌸

sds_misc - SDS Miscelaneous

Okay bestie, this is sds_misc(3) from the Library Functions Manual — the misc-y little corner of SDS. Yes, the page says “Miscelaneous,” and I’m not gonna fight it. 💅

---

✨ SYNOPSIS ✨

   Enumerations
       enum sds_result { SDS_SUCCESS = 0, SDS_UNKNOWN_ERROR = 1,
           SDS_NULL_POINTER = 2, SDS_TEST_FAILED = 3, SDS_DUPLICATE_KEY = 4,
           SDS_CHECKSUM_FAILURE = 5, SDS_INVALID_NODE_ID = 6, SDS_INVALID_KEY =
           7, SDS_INVALID_VALUE_SIZE = 8, SDS_INVALID_POINTER = 9,
           SDS_INVALID_NODE = 10, SDS_INVALID_KEY_ORDER = 11, SDS_RETRY = 12,
           SDS_KEY_PRESENT = 13, SDS_KEY_NOT_PRESENT = 14,
           SDS_INCOMPATIBLE_INSTANCE = 15, SDS_LIST_EXHAUSTED = 16,
           SDS_INVALID_TXN = 17 }

   Functions
       void * sds_malloc (size_t size)
       void * sds_calloc (size_t size)
       void * sds_memalign (size_t size, size_t alignment)
       void sds_free (void *ptr)
       uint32_t sds_crc32c (uint32_t crc, const unsigned char *data, size_t
           length)
       uint64_t sds_siphash13 (const void *src, size_t src_sz, const char
           key[16])
       int64_t sds_uint64_t_compare (void *a, void *b)
       void sds_uint64_t_free (void *key)
       void * sds_uint64_t_dup (void *key)
       int64_t sds_strcmp (void *a, void *b)
       void * sds_strdup (void *key)

---

🦋 Detailed Description 🦋

Miscelaneous functions for SDS. This may be replaced by a PAL from ns-slapd soon.

So like… it’s giving “temporary era,” bestie. 🫶

---

🎀 Enumeration Type Documentation 🎀

💖 enum sds_result 💖

sds_result encapsulates the set of possible success or failures an operation may have during processing. You must always check this value from function calls.

Fr fr, always check it. No vibes-based error handling. 💀

• SDS_SUCCESS (0) — represents that the operation had no errors in processing.
• SDS_UNKNOWN_ERROR (1) — represents that an unexpected issue was encountered; you should raise a bug about this if you encounter it!
• SDS_NULL_POINTER (2) — represents that a NULL pointer was provided to a function that expects a true pointer to valid data. It may also represent that the internals of a datastructure have been corrupted with an unexpected NULL pointer, and the operation can not proceed.
• SDS_TEST_FAILED (3) — represents that a test case has failed. You may need to go back to the test case to see the originating error.
• SDS_DUPLICATE_KEY (4) — represents that the key value already exists in the datastructure. This is generally seen during insertion operations.
• SDS_CHECKSUM_FAILURE (5) — represents that the in memory data does not pass checksum validation. This may be due to the fault of the application or hardware errors.
• SDS_INVALID_NODE_ID (6) — represents that the internal data of a datastructure node contains invalid identifying information.
• SDS_INVALID_KEY (7) — represents that a key is invalid in the state of this node. Generally this is due to a bug in the datastructure code where keys are out of order, or incorrectly nulled.
• SDS_INVALID_VALUE_SIZE (8) — represents that the size of the value provided does not hold true for certain assumptions. For example, a null pointer with a non zero size, or a pointer with a zero size.
• SDS_INVALID_POINTER (9) — represents that within the datastructure an invalid pointer structure has been created that may cause further dataloss or corruption. This could be due to error in the datastructure code, or memory issues.
• SDS_INVALID_NODE (10) — represents that certain datastructure properties of this node have not been upheld. For example, branches should never contain data in a b+tree, or that the capacity of the node is incorrect and a split or merge should have occured.
• SDS_INVALID_KEY_ORDER (11) — indicates that the ordering of keys within a structure is incorrect, and may cause data loss.
• SDS_RETRY (12) — represents that the previous operation should be attempted again. This is only for INTERNAL use. You will never see this returned.
• SDS_KEY_PRESENT (13) — is a SUCCESS condition, similar to SDS_SUCCESS. This differs from SDS_SUCCESS in that it shows that a key value exists within some datastructure, and you must explicitly check for this case (vs SDS_KEY_NOT_PRESENT).
• SDS_KEY_NOT_PRESENT (14) — is a SUCCESS condition, similar to SDS_SUCCESS. This differs from SDS_SUCCESS in that it shows that a key value does not exist within some datastructure, but the operation was still a SUCCESS in completion. You must explicitly check for this case to ensure you know the true result of a function.
• SDS_INCOMPATIBLE_INSTANCE (15) — represents that during a set operation, you are attempting to manipulate datastructures with potentially different key and value types. This would result in datacorruption or undefined behaviour so instead, we return a pre-emptive error.
• SDS_LIST_EXHAUSTED (16) — represents that there are no more elements in this datastructure to be consumed during an iteration.
• SDS_INVALID_TXN (17) — represents that a transaction identifier is invalid for the requested operation. IE using a read only transaction to attempt a write.

---

🌈 Function Documentation 🌈

🍓 void * sds_calloc (size_t size) 🍓

sds_calloc wraps the system calloc call with an OOM check. This call, like calloc, guarantees the returned memory is zeroed before usage.

Parameters

• size — the amount of memory to allocate in bytes.

Return values

• pointer to the allocated memory.

---

💜 uint32_t sds_crc32c (uint32_t crc, const unsigned char * data, size_t length) 💜

sds_crc32c uses the crc32c algorithm to create a verification checksum of data. This checksum is for data verification, not cryptographic purposes. It is used largely in debugging to find cases when bytes in structures are updated incorrectly, or to find memory bit flips during operation. If available, this will use the intel sse4 crc32c hardware acceleration.

Parameters

• crc — The running CRC value. Initially should be 0. If in doubt, use 0.
• data — Pointer to the data to checksum.
• length — number of bytes to validate.

Return values

• rcrc — The crc of this data. May be re-used in subsequent sds_crc32c calls for certain datatypes.

---

🧚 void sds_free (void * ptr) 🧚

sds_free wraps the system free call with a null check.

Parameters

• ptr — the memory to free.

---

⭐ void * sds_malloc (size_t size) ⭐

sds_malloc wraps the system memory allocator with an OOM check. During debugging this call guarantees that memory is zeroed before use.

Parameters

• size — the amount of memory to allocate in bytes.

Return values

• pointer to the allocated memory.

---

🌸 void * sds_memalign (size_t size, size_t alignment) 🌸

sds_memalign wraps the posix_memalign function with an OOM and alignment check. During debugging this call guarantees that memory is zeroed before use.

Parameters

• size — the amount of memory to allocate in bytes.
• alignment — the size to align to in bytes. Must be a power of 2.

Return values

• pointer to the allocated memory.

---

🔥 uint64_t sds_siphash13 (const void * src, size_t src_sz, const char key[16]) 🔥

sds_siphash13 provides an implementation of the siphash algorithm for use in hash based datastructures. It is chosen due to its resilience against hash attacks, such that it makes it highly secure as a choice for a hashmap.

Parameters

• src — The data to hash.
• src_sz — The size of the data to hash.
• key — The security key to mix with the hash. This should be randomised once at startup and stored for use with further operations.

Return values

• The uint64_t representing the hash of the data.

---

👑 int64_t sds_strcmp (void * a, void * b) 👑

sds_strcmp exists to wrap the system strcmp call with the correct types needed for libsds datastructures to operate correctly.

Parameters

• a — Pointer to the first string.
• b — Pointer to the second string.

Return values

• Difference between the values. 0 indicates they are the same.

---

🎀 void * sds_strdup (void * key) 🎀

sds_strdup exists to wrap the system strdup call with the correct types needed for libsds datastructures to operate correctly.

Parameters

• key — Pointer to the string to duplicate.

Return values

• Pointer to the newly allocated string.

---

🦋 int64_t sds_uint64_t_compare (void * a, void * b) 🦋

sds_uint64_t_compare takes two void *, and treats them as uint64_t *.

Parameters

• a — The first uint64_t *.
• b — The second uint64_t *.

Return values

• result of the comparison.

---

💖 void * sds_uint64_t_dup (void * key) 💖

sds_uint64_t_dup Returns a copy of the uint64_t * to the caller.

Parameters

• key — The uint64_t * to copy.

Return values

• result the copy of the value.

---

🌈 void sds_uint64_t_free (void * key) 🌈

Free the allocated uint64_t * from sds_uint64_t_alloc.

Parameters

• key — Do nothing to the key.

---

🫶 Author 🫶

Generated automatically by Doxygen for dirsrv from the source code.

---

That’s the whole cute little sds_misc(3) page, bestie: source dirsrv, Version 3.3.0, and the footer didn’t give me a date so I’m not making one up. Mwah! 💖✨