PMEM2_SOURCE_FROM_HANDLE(3)

💖 pmem2_source_from_fd(3) — PMDK Programmer's Manual 💖

okay bestie, so this is a manual page from the PMDK (Persistent Memory Development Kit) Programmer's Manual, and it's literally all about creating and deleting instances of a persistent memory data source. yes. that's the vibe. let's get into it 🫶

---

✨ NAME ✨

pmem2_source_from_fd(), pmem2_source_from_handle(), pmem2_source_delete() — creates or deletes an instance of persistent memory data source

like. the whole squad. one makes a source from a file descriptor, one makes it from a handle, one deletes it. iconic behavior ngl 💅

---

✨ SYNOPSIS ✨

#include <libpmem2.h>

int pmem2_source_from_fd(struct pmem2_source *src, int fd);
int pmem2_source_from_handle(struct pmem2_source *src, HANDLE handle); /* Windows only */
int pmem2_source_delete(struct pmem2_source **src);

notice that pmem2_source_from_handle() is Windows only, bestie — don't come for her on Linux, she doesn't live there 🪟

---

🌸 DESCRIPTION 🌸

so on Linux, pmem2_source_from_fd() validates the file descriptor and instantiates a new struct pmem2_source object describing the data source. it's giving "vibe check the fd, then build the thing" ✨

on Windows, pmem2_source_from_fd() converts a file descriptor to a file handle (using _get_osfhandle()), and then passes it over to pmem2_source_from_handle(). by default, _get_osfhandle() calls abort() in case of an invalid file descriptor — like, it does NOT play around 😭 — but this behavior can be suppressed by _set_abort_behavior() and SetErrorMode() functions. please check MSDN documentation for more information about Windows CRT error handling. (that's their homework, not mine 🍓)

fd must be opened with O_RDONLY or O_RDWR mode, but on Windows it is not validated. so like, Windows is out here trusting you fr fr.

if fd is invalid, then the function fails. periodt.

the pmem2_source_from_handle() function validates the handle and instantiates a new struct pmem2_source object describing the data source. if handle is INVALID_HANDLE_VALUE, then the function fails. the handle has to be created with an access mode of GENERIC_READ or (GENERIC_READ | GENERIC_WRITE). for details please see the CreateFile() documentation. 📄

and then pmem2_source_delete() — the closer, the cleanup queen 👑 — frees *src returned by pmem2_source_from_fd() or pmem2_source_from_handle() and sets *src to NULL. if *src is NULL, no operation is performed. so it's safe to just vibe and call it, no cap.

---

✨ RETURN VALUE ✨

pmem2_source_from_fd() and pmem2_source_from_handle() return 0 on success or a negative error code on failure. classic.

pmem2_source_delete() always returns 0. she never fails, she's just built different 💅

---

🔥 ERRORS 🔥

pmem2_source_from_fd() / pmem2_source_from_handle() can fail with the following errors:

• PMEM2_E_INVALID_FILE_HANDLE — fd is not an open and valid file descriptor. on Windows the function can abort() on this failure based on CRT's abort() behavior. 💀
• PMEM2_E_INVALID_FILE_HANDLE — fd is opened in O_WRONLY mode.

on Linux:

• PMEM2_E_INVALID_FILE_TYPE — fd points to a directory, block device, pipe, or socket.
• PMEM2_E_INVALID_FILE_TYPE — fd points to a character device other than Device DAX.

on Windows:

• PMEM2_E_INVALID_FILE_TYPE — handle points to a resource that is not a regular file.

on Windows, pmem2_source_from_fd() can return all errors from the underlying pmem2_source_from_handle() function. she's just relaying the message, bestie 🫶

the pmem2_source_from_handle() can return the following errors:

• PMEM2_E_INVALID_FILE_HANDLE — handle points to a resource that is not a file.
• PMEM2_E_INVALID_FILE_TYPE — handle points to a directory.

and pmem2_source_from_fd() and pmem2_source_from_handle() can also return -ENOMEM in case of insufficient memory to allocate an instance of struct pmem2_source. like, out of memory? she's not gonna make it up, she's gonna tell you. 💀

---

🎀 CAVEATS 🎀

on non-DAX Windows volumes, fd/handle must remain open while the mapping is in use. do NOT close it early bestie, that's the whole plot twist 😭

---

🌈 SEE ALSO 🌈

errno(3), pmem2_map_new(3), libpmem2(7) and <https://pmem.io>

---

and that's the whole page, no crumbs left behind ✨ this one's from the PMDK crew, dated 2023-05-31 — so go forth, make your sources, delete your sources, and stay hydrated 🦋💜