Provided by: manpages-pl-dev_4.23.1-1_all 
NAZWA
getrandom - pozyskuje serię losowych bajtów
BIBLIOTEKA
Standardowa biblioteka C (libc, -lc)
SKŁADNIA
#include <sys/random.h>
ssize_t getrandom(void buf[.buflen], size_t buflen, unsigned int flags);
OPIS
Wywołanie systemowe getrandom() wypełnia bufor wskazywany przez buf do wielkości buflen losowych bajtów.
Bajtów tych można użyć jako ziarna dla generatorów liczb losowych w przestrzeni użytkownika, do celów
kryptograficznych.
Domyślnie, getrandom() pozyskuje entropię ze źródła urandom (tj. tego samego źródła, co urządzenie
/dev/urandom). To zachowanie można zmienić argumentem flags.
Jeśli źródło urandom zostało zainicjowane, odczyt do 256 bajtów zawsze zwróci tak dużo bajtów, jak
zażądano i nie będzie przerywany sygnałami. Gwarancji takiej nie ma dla większych buforów. Na przykład,
jeśli wywołanie zostanie przerwane przez procedurę obsługi sygnału, może zwrócić częściowo wypełniony
bufor lub zawieść z błędem EINTR.
Jeśli źródło urandom nie zostało zainicjowane, getrandom() zablokuje, chyba że we flags podano
GRND_NONBLOCK.
Argument flags jest maską bitową, która może zawierać sumę (OR) zera lub więcej poniższych wartości:
GRND_RANDOM
Jeśli ten bit jest ustawiony, to losowe bajty są pozyskiwane ze źródła random (tj. tego samego
źródła, co urządzenie /dev/random), zamiast ze źródła urandom. Źródło random jest ograniczone, w
zależności od entropii, jaka może zostać pozyskana z szumu środowiskowego. Jeśli liczba dostępnym
bajtów w źródle random jest mniejsza, niż żądana w buflen, to wywołanie zwróci jedynie dostępne
bajty losowe. Jeśli w ogóle brak jest dostępnych losowych bajtów, zachowanie zależy od obecności
GRND_NONBLOCK w argumencie flags.
GRND_NONBLOCK
Domyślnie, przy odczycie ze źródła random, getrandom() blokuje, gdy brak jest dostępnych losowych
bajtów, a przy odczycie ze źródła urandom blokuje, gdy pula entropii nie została jeszcze
zainicjowana. Jeśli ustawiony jest znacznik GRND_NONBLOCK, to getrandom() w tych przypadkach nie
blokuje, lecz natychmiast zwraca -1, z errno ustawionym na EAGAIN.
WARTOŚĆ ZWRACANA
Przy powodzeniu, getrandom() zwraca liczbę bajtów skopiowanych do bufora buf. Może być ona mniejsza, niż
liczba bajtów żądanych za pomocą buflen, jeśli we flags podano GRND_RANDOM i w źródle random była obecna
niewystarczająca entropia, albo jeśli wywołanie systemowe zostało przerwane sygnałem.
W razie wystąpienia błędu zwracane jest -1 i ustawiane errno wskazując błąd.
BŁĘDY
EAGAIN Żądana entropia nie była dostępna i getrandom() zablokowałoby, gdyby nie był ustawiony znacznik
GRND_NONBLOCK.
EFAULT Adres, do którego odnosi się buf był poza dostępną przestrzenią adresową.
EINTR Wywołanie systemowe zostało przerwane procedurą obsługi sygnału; zob. opis w podręczniku
signal(7), jak obsługiwane jest przerwane wywołanie read(2) na „powolnych” urządzeniach z, oraz
bez, znacznika SA_RESTART.
EINVAL We flags podano nieprawidłowy znacznik.
ENOSYS Funkcja opakowująca getrandom() z glibc ustaliła, że bieżące jądro nie implementuje tego wywołania
systemowego.
STANDARDY
Linux.
HISTORIA
Linux 3.17, glibc 2.25.
UWAGI
Przegląd i porównanie różnych interfejsów do pozyskiwania losowości znajduje się w podręczniku random(7). W przeciwieństwie do /dev/random i /dev/urandom, getrandom() nie angażuje ścieżek, ani deskryptorów plików. Z tego powodu getrandom() może być użyteczne w przypadkach, gdy chroot(2) czyni ścieżki /dev niewidocznymi oraz gdy aplikacja (np. demon w trakcie rozruchu) zamyka deskryptor pliku jednego z tych plików, który był otwarty przez bibliotekę. Maksymalna liczba zwracanych bajtów Według stanu na Linuksa 3.19 istnieją następujące limity: • Przy odczycie ze źródła urandom, w systemach gdzie int ma rozmiar 32 bitów, pojedynczym wywołaniem do getrandom zwracanych jest maksymalnie 32Mi-1 bajtów. • Przy odczycie ze źródła random, zwracanych jest co najwyżej 512 bajtów. Przerwanie procedurą obsługi sygnału Przy odczycie ze źródła urandom (nie jest ustawiony GRND_RANDOM), getrandom() zablokuje, dopóki nie zostanie zainicjowana pula entropii (chyba, że podano znacznik GRND_NONBLOCK). Jeśli żądano odczytu dużej liczby bajtów (powyżej 256), getrandom() zablokuje, dopóki bajty te nie zostaną wygenerowane i przeniesione z pamięci jądro do buf. Przy odczycie ze źródła random (jest ustawiony GRND_RANDOM), getrandom() zablokuje, dopóki jakieś losowe bajty nie staną się dostępne (chyba, że podano znacznik GRND_NONBLOCK). Zachowanie, gdy wywołanie do zablokowanego w trakcie odczytu ze źródła urandom getrandom(), zostanie przerwane procedurą obsługi sygnału, zależy od stanu zainicjowania bufora entropii oraz od żądanego rozmiaru w buflen. Jeśli entropia nie została jeszcze zainicjowana, to wywołanie zawiedzie z błędem EINTR. Jeśli pula entropii została zainicjowana, a żądany rozmiar jest duży (buflen > 256), to wywołanie albo powiedzie się, zwracając częściowo wypełniony bufor, albo zawiedzie z błędem EINTR. Jeśli pula entropii została zainicjowana, a żądany rozmiar jest mały (buflen <= 256), to getrandom() nie zawiedzie z EINTR, lecz zwróci wszystkie żądane bajty. Przy odczycie ze źródła random, blokujące żądania o dowolnym rozmiarze mogą być przerwane procedurą obsługi sygnału (wywołanie zawiedzie z błędem EINTR). Preferowaną metodą korzystania z getrandom(), jest odczyt małych buforów (<= 256 bajtów) ze źródła urandom. Specjalny sposób traktowania małych wartości buflen został zaprojektowany w celu zachowania kompatybilności z getentropy(3) z OpenBSD, które jest obecnie obsługiwane w glibc. Użytkownik getrandom() zawsze musi sprawdzać zwracaną wartość, aby określić, czy wystąpił błąd, czy też zwrócono mniej bajtów niż żądano. W przypadku gdy nie poda się GRND_RANDOM, a buflen jest mniejsze lub równe 256, nigdy nie powinna wystąpić sytuacja zwrócenia mniejszej liczby bajtów niż żądano, lecz ostrożny programista i tak powinien to sprawdzić!
USTERKI
Według stanu na Linuksa 3.19, występuje poniższy błąd:
• W zależności od obciążenia procesora, getrandom() nie reaguje na przerwania, przed odczytem wszystkich
żądanych bajtów.
ZOBACZ TAKŻE
getentropy(3), random(4), urandom(4), random(7), signal(7)
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Michał Kułach <michal.kulach@gmail.com> Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI. Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej ⟨manpages-pl- list@lists.sourceforge.net⟩.