.\" -*- coding: UTF-8 -*-
.\" Copyright (C) 2014, Theodore Ts'o <tytso@mit.edu>
.\" Copyright (C) 2014,2015 Heinrich Schuchardt <xypron.glpk@gmx.de>
.\" Copyright (C) 2015, Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH getrandom 2 "2 maja 2024 r." "Linux man\-pages 6.8" 
.SH NAZWA
getrandom \- pozyskuje serię losowych bajtów
.SH BIBLIOTEKA
Standardowa biblioteka C (\fIlibc\fP, \fI\-lc\fP)
.SH SKŁADNIA
.nf
\fB#include <sys/random.h>\fP
.P
\fBssize_t getrandom(void \fP\fIbuf\fP\fB[.\fP\fIbuflen\fP\fB], size_t \fP\fIbuflen\fP\fB, unsigned int \fP\fIflags\fP\fB);\fP
.fi
.SH OPIS
Wywołanie systemowe \fBgetrandom\fP() wypełnia bufor wskazywany przez \fIbuf\fP do
wielkości \fIbuflen\fP 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.
.P
Domyślnie, \fBgetrandom\fP() pozyskuje entropię ze źródła \fIurandom\fP (tj. tego
samego źródła, co urządzenie \fI/dev/urandom\fP). To zachowanie można zmienić
argumentem \fIflags\fP.
.P
Jeśli źródło \fIurandom\fP 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 \fBEINTR\fP.
.P
Jeśli źródło \fIurandom\fP nie zostało zainicjowane, \fBgetrandom\fP() zablokuje,
chyba że we \fIflags\fP podano \fBGRND_NONBLOCK\fP.
.P
Argument \fIflags\fP jest maską bitową, która może zawierać sumę (OR) zera lub
więcej poniższych wartości:
.TP 
\fBGRND_RANDOM\fP
Jeśli ten bit jest ustawiony, to losowe bajty są pozyskiwane ze źródła
\fIrandom\fP (tj. tego samego źródła, co urządzenie \fI/dev/random\fP), zamiast ze
źródła \fIurandom\fP. Źródło \fIrandom\fP 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 \fIrandom\fP jest mniejsza, niż żądana w \fIbuflen\fP,
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 \fBGRND_NONBLOCK\fP
w argumencie \fIflags\fP.
.TP 
\fBGRND_NONBLOCK\fP
Domyślnie, przy odczycie ze źródła \fIrandom\fP, \fBgetrandom\fP() blokuje, gdy
brak jest dostępnych losowych bajtów, a przy odczycie ze źródła \fIurandom\fP
blokuje, gdy pula entropii nie została jeszcze zainicjowana. Jeśli ustawiony
jest znacznik \fBGRND_NONBLOCK\fP, to \fBgetrandom\fP() w tych przypadkach nie
blokuje, lecz natychmiast zwraca \-1, z \fIerrno\fP ustawionym na \fBEAGAIN\fP.
.SH "WARTOŚĆ ZWRACANA"
Przy powodzeniu, \fBgetrandom\fP() zwraca liczbę bajtów skopiowanych do bufora
\fIbuf\fP. Może być ona mniejsza, niż liczba bajtów żądanych za pomocą
\fIbuflen\fP, jeśli we \fIflags\fP podano \fBGRND_RANDOM\fP i w źródle \fIrandom\fP była
obecna niewystarczająca entropia, albo jeśli wywołanie systemowe zostało
przerwane sygnałem.
.P
W razie wystąpienia błędu zwracane jest \-1 i ustawiane \fIerrno\fP wskazując
błąd.
.SH BŁĘDY
.TP 
\fBEAGAIN\fP
Żądana entropia nie była dostępna i \fBgetrandom\fP() zablokowałoby, gdyby nie
był ustawiony znacznik \fBGRND_NONBLOCK\fP.
.TP 
\fBEFAULT\fP
Adres, do którego odnosi się \fIbuf\fP był poza dostępną przestrzenią adresową.
.TP 
\fBEINTR\fP
Wywołanie systemowe zostało przerwane procedurą obsługi sygnału; zob. opis w
podręczniku \fBsignal\fP(7), jak obsługiwane jest przerwane wywołanie
\fBread\fP(2) na \[Bq]powolnych\[rq] urządzeniach z, oraz bez, znacznika
\fBSA_RESTART\fP.
.TP 
\fBEINVAL\fP
We \fIflags\fP podano nieprawidłowy znacznik.
.TP 
\fBENOSYS\fP
Funkcja opakowująca \fBgetrandom\fP() z glibc ustaliła, że bieżące jądro nie
implementuje tego wywołania systemowego.
.SH STANDARDY
Linux.
.SH HISTORIA
Linux 3.17, glibc 2.25.
.SH UWAGI
Przegląd i porównanie różnych interfejsów do pozyskiwania losowości znajduje
się w podręczniku \fBrandom\fP(7).
.P
.\"
W przeciwieństwie do \fI/dev/random\fP i \fI/dev/urandom\fP, \fBgetrandom\fP() nie
angażuje ścieżek, ani deskryptorów plików. Z tego powodu \fBgetrandom\fP() może
być użyteczne w przypadkach, gdy \fBchroot\fP(2) czyni ścieżki \fI/dev\fP
niewidocznymi oraz gdy aplikacja (np. demon w trakcie rozruchu) zamyka
deskryptor pliku jednego z tych plików, który był otwarty przez bibliotekę.
.SS "Maksymalna liczba zwracanych bajtów"
Według stanu na Linuksa 3.19 istnieją następujące limity:
.IP \[bu] 3
Przy odczycie ze źródła \fIurandom\fP, w systemach gdzie \fIint\fP ma rozmiar 32
bitów, pojedynczym wywołaniem do \fBgetrandom\fP zwracanych jest maksymalnie
32Mi\-1 bajtów.
.IP \[bu]
Przy odczycie ze źródła \fIrandom\fP, zwracanych jest co najwyżej 512 bajtów.
.SS "Przerwanie procedurą obsługi sygnału"
Przy odczycie ze źródła \fIurandom\fP (nie jest ustawiony \fBGRND_RANDOM\fP),
\fBgetrandom\fP() zablokuje, dopóki nie zostanie zainicjowana pula entropii
(chyba, że podano znacznik \fBGRND_NONBLOCK\fP). Jeśli żądano odczytu dużej
liczby bajtów (powyżej 256), \fBgetrandom\fP() zablokuje, dopóki bajty te nie
zostaną wygenerowane i przeniesione z pamięci jądro do \fIbuf\fP. Przy odczycie
ze źródła \fIrandom\fP (jest ustawiony \fBGRND_RANDOM\fP), \fBgetrandom\fP()
zablokuje, dopóki jakieś losowe bajty nie staną się dostępne (chyba, że
podano znacznik \fBGRND_NONBLOCK\fP).
.P
Zachowanie, gdy wywołanie do zablokowanego w trakcie odczytu ze źródła
\fIurandom\fP \fBgetrandom\fP(), zostanie przerwane procedurą obsługi sygnału,
zależy od stanu zainicjowania bufora entropii oraz od żądanego rozmiaru w
\fIbuflen\fP. Jeśli entropia nie została jeszcze zainicjowana, to wywołanie
zawiedzie z błędem \fBEINTR\fP. Jeśli pula entropii została zainicjowana, a
żądany rozmiar jest duży (\fIbuflen\fP\ >\ 256), to wywołanie albo
powiedzie się, zwracając częściowo wypełniony bufor, albo zawiedzie z błędem
\fBEINTR\fP. Jeśli pula entropii została zainicjowana, a żądany rozmiar jest
mały (\fIbuflen\fP\ <=\ 256), to \fBgetrandom\fP() nie zawiedzie z \fBEINTR\fP,
lecz zwróci wszystkie żądane bajty.
.P
Przy odczycie ze źródła \fIrandom\fP, blokujące żądania o dowolnym rozmiarze
mogą być przerwane procedurą obsługi sygnału (wywołanie zawiedzie z błędem
\fBEINTR\fP).
.P
Preferowaną metodą korzystania z \fBgetrandom\fP(), jest odczyt małych buforów
(<=\ 256 bajtów) ze źródła \fIurandom\fP.
.P
Specjalny sposób traktowania małych wartości \fIbuflen\fP został zaprojektowany
w celu zachowania kompatybilności z \fBgetentropy\fP(3) z OpenBSD, które jest
obecnie obsługiwane w glibc.
.P
Użytkownik \fBgetrandom\fP() zawsze \fImusi\fP 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ę \fBGRND_RANDOM\fP, a \fIbuflen\fP 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ć!
.SH USTERKI
.\" FIXME patch proposed https://lkml.org/lkml/2014/11/29/16
Według stanu na Linuksa 3.19, występuje poniższy błąd:
.IP \[bu] 3
W zależności od obciążenia procesora, \fBgetrandom\fP() nie reaguje na
przerwania, przed odczytem wszystkich żądanych bajtów.
.SH "ZOBACZ TAKŻE"
\fBgetentropy\fP(3), \fBrandom\fP(4), \fBurandom\fP(4), \fBrandom\fP(7), \fBsignal\fP(7)
.PP
.SH TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są:
Michał Kułach <michal.kulach@gmail.com>
.
.PP
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach
licencji można uzyskać zapoznając się z
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License w wersji 3
.UE
lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.
.PP
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy
dyskusyjnej
.MT manpages-pl-list@lists.sourceforge.net
.ME .
