getrandom(2)

НАИМЕНОВАНИЕ
getrandom - возвращает серию произвольных байт

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

СИНТАКСИС
#include <sys/random.h>

ssize_t getrandom(size_t size;
                  void buf[size], size_t size, unsigned int flags);

ОПИСАНИЕ
The getrandom() system call fills the buffer pointed to by buf with up to size random bytes. These bytes can be used to seed user-space random number generators or for cryptographic purposes.

По умолчанию, getrandom() забирает энтропию из источника urandom (т. е., того же источника что и устройство /dev/urandom). Это поведение можно изменить через параметр flags.

Если источник urandom инициализирован, то из него можно прочитать не более 256 байт, но всегда возвращается столько байт, сколько запрошено и это не будет прерываться сигналами. Для буферов большего размера это не гарантируется. Например, если вызов прерывается обработчиком сигнала, то он может вернуть частично заполненный буфер или завершиться с ошибкой EINTR.

Если источник urandom ещё не инициализирован, то вызов getrandom() блокируется, если в flags не указано значение GRND_NONBLOCK.

Аргумент flags является битовой маской, которая может содержать ноль или более следующих флагов:

GRND_RANDOM
    If this bit is set, then random bytes are drawn from the random source (i.e., the same source as the /dev/random device) instead of the urandom source. The random source is limited based on the entropy that can be obtained from environmental noise. If the number of available bytes in the random source is less than requested in size, the call returns just the available random bytes. If no random bytes are available, the behavior depends on the presence of GRND_NONBLOCK in the flags argument.

GRND_NONBLOCK
    По умолчанию, при чтении из источника random вызов getrandom() блокируется, если произвольные байты недоступны, и а при чтении из источника urandom блокируется, если ещё не инициализирован пул энтропии. Если указан флаг GRND_NONBLOCK, то в этих случаях getrandom() не блокируется, а сразу возвращает -1 и присваивает errno значение EAGAIN.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
On success, getrandom() returns the number of bytes that were copied to the buffer buf. This may be less than the number of bytes requested via size if either GRND_RANDOM was specified in flags and insufficient entropy was present in the random source or the system call was interrupted by a signal.

В случае ошибки возвращается -1, а errno устанавливается в значение ошибки.

ОШИБКИ

EAGAIN
    Запрошенное количество энтропии недоступно, и getrandom() заблокировался бы, если бы отсутствовал флаг GRND_NONBLOCK.

EFAULT
    Адрес, указанный в buf, лежит вне доступного адресного пространства.

EINTR
    Вызов был прерван обработчиком сигнала; смотрите описание о прерывании вызовов read(2) при работе с «медленными» устройствами и при отсутствии флага SA_RESTART в справочной странице signal(7).

EINVAL
    В flags указан неверный флаг.

ENOSYS
    Обёрточная функция в glibc для getrandom() определила, что используемое ядро не поддерживает данный системный вызов.

СТАНДАРТЫ
Linux.

ИСТОРИЯ
Linux 3.17, glibc 2.25.

ПРИМЕЧАНИЯ
Обзор и сравнение возможных интерфейсов, через которые можно получать случайные данные, смотрите в random(7).

В отличие от /dev/random и /dev/urandom, в вызове getrandom() не используются пути или файловые дескрипторы. Таким образом, getrandom() полезен в случаях, когда chroot(2) делает пути /dev невидимыми и приложение (например, служба во время загрузки) закрывает файловый дескриптор одного из этих файлов, которые были открыты библиотекой.

  Возвращается максимальное количество байтов
На момент Linux 3.19 существуют следующие ограничения:

•   When reading from the urandom source, a maximum of 32Mi-1 bytes is returned by a single call to getrandom() on systems where int has a size of 32 bits.

•   При чтении из источника random возвращается максимум 512 байт.

  Прерывание обработчиком сигнала
При чтении из источника urandom (GRND_RANDOM не указан), getrandom() блокируется до тех пор, пока не специализируется пул энтропии (если не указан флаг GRND_NONBLOCK). Если запрос требует большого количества байт (больше 256), getrandom() будет заблокирован до тех пор, пока байты не будут сгенерированы и переданы из памяти ядра в buf. При чтении из random (указан GRND_RANDOM), getrandom() будет заблокирован до тех пор, пока какое-то количество произвольных байт не станет доступно (если не указан флаг GRND_NONBLOCK).

The behavior when a call to getrandom() that is blocked while reading from the urandom source is interrupted by a signal handler depends on the initialization state of the entropy buffer and on the request size, size. If the entropy is not yet initialized, then the call fails with the EINTR error. If the entropy pool has been initialized and the request size is large (size > 256), the call either succeeds, returning a partially filled buffer, or fails with the error EINTR. If the entropy pool has been initialized and the request size is small (size <= 256), then getrandom() will not fail with EINTR. Instead, it will return all of the bytes that have been requested.

При чтении из источника random блокирующие запросы на любой объём могут быть прерваны обработчиком сигналом (вызов завершается с ошибкой EINTR).

Использование getrandom() для чтения маленьких буферов (<= 256 байт) из источника urandom — предпочтительный способ использования.

The special treatment of small values of size was designed for compatibility with OpenBSD's getentropy(3), which is nowadays supported by glibc.

The user of getrandom() must always check the return value, to determine whether either an error occurred or fewer bytes than requested were returned. In the case where GRND_RANDOM is not specified and size is less than or equal to 256, a return of fewer bytes than requested should never happen, but the careful programmer will check for this anyway!

ОШИБКИ
В Linux 3.19 существуют следующие дефекты:

•   В зависимости от загруженности ЦП, getrandom() не реагирует на прерывания, пока не прочитает все запрашиваемые байты.

СМОТРИТЕ ТАКЖЕ
getentropy(3), random(4), urandom(4), random(7), signal(7)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (debian-l10n-russian@lists.debian.org).