ИМЯ

posix_memalign, aligned_alloc, memalign, valloc, pvalloc - выделяет выровненную область памяти

ОБЗОР

#include <stdlib.h>

int posix_memalign(void **memptr, size_t alignment, size_t size);
void *aligned_alloc(size_t alignment, size_t size);
void *valloc(size_t size);
#include <malloc.h>

void *memalign(size_t alignment, size_t size);
void *pvalloc(size_t size);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

posix_memalign(): _POSIX_C_SOURCE >= 200112L

aligned_alloc(): _ISOC11_SOURCE

valloc():

Начиная с glibc 2.12:

(_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)

    || /* начиная с glibc 2.19: */ _DEFAULT_SOURCE

    || /* в версии glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE

До glibc 2.12:

_BSD_SOURCE || _XOPEN_SOURCE >= 500 (Заголовочный файл <malloc.h> (нестандартный) также содержит объявление valloc(); макросов тестирования свойств не требуется)

ОПИСАНИЕ

Функция posix_memalign() выделяет size байт и помещает адрес выделенной памяти в *memptr. Этот адрес будет кратен значению alignment, которое должно быть степенью двойки и кратно sizeof(void *). Если size равно 0, то значение, помещаемое в *memptr, равно NULL, или является уникальным значением указателя, который позднее можно передавать в free(3).

Устаревшая функция memalign() выделяет size байт и возвращает указатель на выделенную память. Адрес памяти будет кратен значению alignment, которое должны быть степенью двойки.

Функция aligned_alloc() подобна memalign(), но добавляет ограничение для значения size, которое должно быть кратно alignment.

Устаревшая функция valloc() выделяет size байт и возвращает указатель на выделенную память. Адрес памяти будет кратен размеру страницы. Она эквивалентна вызову memalign(sysconf(_SC_PAGESIZE),size).

Устаревшая функция pvalloc() подобна valloc(), но округляет выделяемый размер до следующего кратного значения системной страницы.

Эти функции не обнуляют выделяемую память.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функции aligned_alloc(), memalign(), valloc() и pvalloc() возвращают указатель на выделенную память и NULL при ошибках.

При успешном выполнении функция posix_memalign() возвращает ноль и одно из значений, перечисленных в далее, при ошибке. Значение errno не изменяется. В Linux (и других системах) posix_memalign() при ошибке не изменяет memptr. Требование стандартизации такого поведения было добавлено в POSIX.1-2016.

ОШИБКИ

EINVAL: Аргумент alignment не является степенью двойки или не кратен sizeof(void *).
ENOMEM: Недостаточно памяти для выполнения запроса о выделении.

ВЕРСИИ

Функции memalign(), valloc() и pvalloc() доступны во всех библиотеках Linux libc.

Функция aligned_alloc() впервые появилась в glibc 2.16.

Функция posix_memalign() доступна в glibc начиная с версии 2.1.91.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
aligned_alloc(), memalign(), posix_memalign()	Безвредность в нитях	MT-Safe
valloc(), pvalloc()	Безвредность в нитях	MT-Unsafe init

СООТВЕТСТВИЕ СТАНДАРТАМ

Функция valloc() появилась из 3.0BSD. Она описана как устаревшая в 4.3BSD и в SUSv2. Отсутствует в POSIX.1.

Функция pvalloc() является расширением GNU.

Функция memalign() появилась из SunOS 4.1.3, но отсутствует в 4.4BSD.

Функция posix_memalign() появилась из POSIX.1d и описана в POSIX.1-2001 и POSIX.1-2008.

Функция aligned_alloc() описана в стандарте C11.

Заголовки

Функция posix_memalign() везде объявлена в <stdlib.h>.

В некоторых системах memalign() объявлена в <stdlib.h>, а не в <malloc.h>.

В SUSv2 функция valloc() объявлена в <stdlib.h>. В Libc4,5 и glibc она объявлена в <malloc.h>, а также в <stdlib.h>, если определены соответствующие макросы тестирования свойств (смотрите выше).

ЗАМЕЧАНИЯ

Во многих системах накладываются ограничения по выравниванию, например, на буферы, используемые для прямого ввода-вывода в блочные устройства. В POSIX определён вызов pathconf(path,_PC_REC_XFER_ALIGN), показывающий необходимость выравнивания. В настоящее время можно использовать posix_memalign() для удовлетворения этого требования.

Функция posix_memalign() проверяет, что alignment удовлетворяет требованиям, описанным выше. Функция memalign() может не проверять корректность аргумента alignment.

В POSIX требуется, чтобы память, полученная через posix_memalign(), могла освобождаться с помощью free(3). В некоторых системах отсутствует механизм освобождения памяти, выделенной memalign() или valloc() (так как в них во free(3) передаётся только указатель, полученный из malloc(3), но, например, memalign() выполняет вызов malloc(3) и затем выравнивает полученное значение). Реализация glibc позволяет освобождать память, полученную через эти функции, с помощью free(3).

Функция glibc malloc(3) всегда возвращает адреса памяти, выровненные по 8-байтовой границе, поэтому данные функции требуются только, если нужны значения с большим выравниванием.

ИМЯ