The Open Group Base Specifications Issue 7
IEEE Std 1003.1-2008, 2016 Edition
Copyright © 2001-2016 The IEEE and The Open Group

#### NAME

> posix_memalign - aligned memory allocation (ADVANCED REALTIME)

#### SYNOPSIS

> ``[ADV] #include <stdlib.h>
> int posix_memalign(void **`memptr`, size_t` alignment`, size_t` size`);``
> `
> `

#### DESCRIPTION

> The posix_memalign() function shall allocate size bytes aligned on a boundary specified by alignment, and shall return a pointer to the allocated memory in memptr. The value of alignment shall be a power of two multiple of sizeof(void *).

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

> If the size of the space requested is 0, the behavior is implementation-defined: 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 the value returned in memptr is used to access an object.

> [CX] The free() function shall deallocate memory that has previously been allocated by posix_memalign().

#### RETURN VALUE

> Upon successful completion, posix_memalign() shall return zero; 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.

> 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.

#### 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 *).
> [ENOMEM]
>   There is insufficient memory available with the requested alignment.

The following sections are informative.

#### EXAMPLES

> The following example shows how applications can obtain consistent behavior on error by setting * memptr to be a null pointer before calling posix_memalign().

>     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;

#### APPLICATION USAGE

> The posix_memalign() function is part of the Advisory Information option and need not be provided on all implementations.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> free, malloc

> XBD <stdlib.h>

#### CHANGE HISTORY

> First released in Issue 6. Derived from IEEE Std 1003.1d-1999.

> In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required.

#### Issue 7

> Austin Group Interpretation 1003.1-2001 #058 is applied, clarifying the value of the alignment argument in the DESCRIPTION.

> Austin Group Interpretation 1003.1-2001 #152 is applied, clarifying the behavior when the size of the space requested is 0.

> POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0251 [526] and XSH/TC2-2008/0252 [520,526] are applied.

End of informative text.

return to top of page

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
Copyright © 2001-2016 The IEEE and The Open Group, All Rights Reserved
[ Main Index | XBD | XSH | XCU | XRAT ]