CSPTR(3)

✨ CSPTR(3) — smart pointers for C, bestie edition ✨

Okay so this is the CSPTR(3) manual page, and we are about to make smart pointers in C make sense. No cap, it’s giving “tiny library, big main character energy.” 💅

---

💖 NAME 💖

csptr — smart pointers for the C programming language 🫶

---

🌸 SYNOPSIS 🌸

Bestie, the includes and signatures are literally exactly this:

#include <csptr/smart_ptr.h>

void *unique_ptr(Type, Value, ... );
void *shared_ptr(Type, Value, ... );

#include <csptr/smart_ptr.h>
#include <csptr/smalloc.h>
void *smalloc(size_t size, size_t nmemb, int kind);
void *smalloc(size_t size, size_t nmemb, int kind, void (*dtor)(void *, void *));
void *smalloc(size_t size, size_t nmemb, int kind, void (*dtor)(void *, void *), struct { void *, size_t } meta);
void sfree(void *ptr);
void *sref(void *ptr);

---

🦋 DESCRIPTION 🦋

So the smalloc() function calls an allocator (malloc(3) by default), such that the returned pointer is a smart pointer. The memory is not initialized, and great care should be taken to initialize it before destruction if a destructor has been specified. Like, genuinely pay attention to that part, bestie. 😭

If size is 0, then smalloc() returns NULL.

If nmemb is 0, then smalloc shall return a smart pointer to a memory block of at least size bytes, and the smart pointer is a scalar. Otherwise, it shall return a memory block to at least size * nmemb bytes, and the smart pointer is an array. Slay, that’s the whole scalar-vs-array vibe check. ✨

The sfree() function calls the deallocator associated to the smalloc() allocator (free(3) by default) on ptr if the smart pointer is either unique or shared with a reference count of 0. If the smart pointer is shared, it shall decrement the reference counter by 1 before checking if the deallocator needs to be called. Order matters, okay? 👑

The sref() function creates a new reference to ptr, incrementing the internal reference counter of the smart shared pointer by 1. It shall only be called on a shared pointer. That is the rule, periodt. 💀

The unique_ptr() and shared_ptr() macros expand to a call to the smalloc() function with either UNIQUE or SHARED for the kind parameter, then sets the newly returned memory with Value. Additional parameters are passed as-is to the function.

If Type is an array type, then size shall contain the size of the compound type, and nmemb shall contain the length of the array. Otherwise, if Type is a scalar or complex type, then size shall contain the size of the type, and nmemb shall be 0. Yup, that’s the exact breakdown. 🎀

⚠️ Reminder from the page: the memory from smalloc() is not initialized. If you specified a destructor, take great care to initialize the memory before destruction. This is not a drill, bestie. 🚨

---

🌈 RETURN VALUE 🌈

The smalloc() function returns a pointer to the newly allocated memory. On error, it returns NULL. NULL may also be returned by a successful call to smalloc() with a size of zero. So yes, a successful zero-size call can still hand you NULL. That’s just how it is. 🫠

The sfree() function returns no value.

The sref() function returns ptr.

---

🍓 SEE ALSO 🍓

• malloc(3)

That’s the whole see-also list, icon. 🧚

---

Mwah 💋 — this little page is from CSPTR(3), dated 2015-03-18. Bye bestie, go forth and manage your pointers responsibly! 💖✨