POSIX_MEMALIGN(3POSIX)

💖 POSIX_MEMALIGN 💖

okay bestie, so this one lives in the POSIX Programmer's Manual — section 3POSIX, if you're keeping track. quick lil heads up before we even start:

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details on Linux behavior), or the interface may not be implemented on Linux.

like, she might not even show up on your machine. rude, but okay. 💀

---

✨ NAME ✨

posix_memalign — aligned memory allocation (ADVANCED REALTIME)

no cap, that "(ADVANCED REALTIME)" is part of the name, it's giving fancy.

---

🌸 SYNOPSIS 🌸

#include <stdlib.h>

int posix_memalign(void **memptr, size_t alignment, size_t size);

that's the whole vibe. three args, one int back. slay.

---

🎀 DESCRIPTION 🎀

so here's the tea, bestie. posix_memalign() shall allocate size bytes aligned on a boundary specified by alignment, and shall return a pointer to the allocated memory in memptr. it's literally handing you memory that sits just right on the grid. ✨

the value of alignment shall be a power of two multiple of sizeof(void *). that part is not a suggestion, it's the law.

upon successful completion, the value pointed to by memptr shall be a multiple of alignment. periodt.

now, plot twist 👀 — if the size of the space requested is 0, the behavior is implementation-defined. meaning either a null pointer shall be returned in memptr, or the behavior shall be as if the size were some non-zero value, except that the behavior is undefined if the value returned in memptr is used to access an object. so like… don't touch it. i'm so serious. 🙈

and for cleanup? the free() function shall deallocate memory that has previously been allocated by posix_memalign(). that's it, that's the pair. they're a duo. 💅

---

💅 RETURN VALUE 💅

upon successful completion, posix_memalign() shall return zero. iconic. otherwise, an error number shall be returned to indicate the error and the contents of memptr shall either be left unmodified or be set to a null pointer. so your pointer is either untouched or nulled — never something cursed in between.

if size is 0, either:

• posix_memalign() shall not attempt to allocate any space, in which case either an implementation-defined error number shall be returned, or zero shall be returned with a null pointer returned in memptr, or
• posix_memalign() shall attempt to allocate some space and, if the allocation succeeds, zero shall be returned and a pointer to the allocated space shall be returned in memptr. the application shall ensure that the pointer is not used to access an object.

that last bit is the important one, bestie — you get a pointer but you absolutely cannot dereference it. it's decorative. it's for the aesthetic. don't use it to access an object. 🫶

---

🔥 ERRORS 🔥

the posix_memalign() function shall fail if:

• EINVAL — the value of the alignment parameter is not a power of two multiple of sizeof(void *). you did the math wrong, queen, and she noticed.
• ENOMEM — there is insufficient memory available with the requested alignment. she's broke. it happens.

the following sections are informative. (so like, chill, these are the bonus tracks 🎵)

---

🌈 EXAMPLES 🌈

here's how you get consistent behavior on error, by setting *memptr to be a null pointer before calling posix_memalign(). chef's kiss, honestly:

void *ptr = NULL;
...
//do some work, which might goto error
if (posix_memalign(&ptr, align, size))
    goto error;

//do some more work, which might goto error
...
error:
    free(ptr);
    //more cleanup;

see how ptr starts as NULL? that's the trick. then even if everything goes sideways, free(ptr) is safe. lowkey genius. 🧚

---

🦋 APPLICATION USAGE 🦋

the posix_memalign() function is part of the Advisory Information option and need not be provided on all implementations. so like, not every system ships her. check before you commit. 💜

---

⭐ RATIONALE ⭐

None.

literally nothing. the rationale said "no thoughts, head empty." 💀

---

🌸 FUTURE DIRECTIONS 🌸

None.

she's not going anywhere and she's not becoming anything else. stable queen behavior. 👑

---

🎀 SEE ALSO 🎀

• free()
• malloc()

and also the Base Definitions volume of POSIX.1‐2017, <stdlib.h> — the header that started it all. iykyk.

---

💖 COPYRIGHT 💖

okay this is the legal bit, but i'm keeping every word because bestie we do NOT play with licensing:

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page, bestie!! 🫶 this one came to you courtesy of IEEE/The Open Group, 2017 — yeah, the POSIX_MEMALIGN(3POSIX) era, she's been around. go forth and align your memory, and remember: power of two multiple of sizeof(void *) or it's a EINVAL situation. love u, bye!! 💖✨🎀🦋🌸💅