getrandom(2)

NUME
getrandom - obține o serie de octeți aleatorii

BIBLIOTECA
Biblioteca C standard (libc, -lc)

SINOPSIS
#include <sys/random.h>

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

DESCRIERE
Apelul de sistem getrandom() umple memoria tampon indicată de buf cu până la buflen octeți aleatorii. Acești octeți pot fi utilizați pentru însămânțarea generatoarelor de numere aleatorii din spațiul utilizatorului sau în scopuri criptografice.

În mod implicit, getrandom() extrage entropia din sursa urandom (adică aceeași sursă ca dispozitivul /dev/urandom). Acest comportament poate fi modificat prin intermediul argumentului flags.

Dacă sursa urandom a fost inițializată, citirile de până la 256 de octeți vor returna întotdeauna numărul de octeți solicitat și nu vor fi întrerupte de semnale. Nu se aplică astfel de garanții pentru dimensiuni mai mari ale memoriei tampon. De exemplu, dacă apelul este întrerupt de un gestionar de semnal, acesta poate returna un tampon parțial umplut sau poate eșua cu eroarea EINTR.

Dacă sursa urandom nu a fost încă inițializată, atunci getrandom() se va bloca, cu excepția cazului în care GRND_NONBLOCK este specificat în flags.

Argumentul flags este o mască de biți care poate conține zero sau mai multe dintre următoarele valori unite împreună printr-un operator SAU logic:

GRND_RANDOM
    Dacă acest bit este activat, atunci octeții aleatorii sunt extrași din sursa random (adică aceeași sursă ca dispozitivul /dev/random) în locul sursei urandom. Sursa random este limitată pe baza entropiei care poate fi obținută din zgomotul ambiental. Dacă numărul de octeți disponibili în sursa random este mai mic decât cel solicitat în buflen, apelul returnează doar octeții aleatori disponibili. Dacă nu sunt disponibili octeți aleatorii, comportamentul depinde de prezența GRND_NONBLOCK în argumentul flags.

GRND_NONBLOCK
    În mod implicit, atunci când citește din sursa random, getrandom() se blochează dacă nu sunt disponibili octeți aleatori, iar atunci când citește din sursa urandom, se blochează dacă fondul de entropie nu a fost încă inițializat. Dacă fanionul GRND_NONBLOCK este activat, atunci getrandom() nu se blochează în aceste cazuri, ci returnează imediat -1 cu errno configurată la EAGAIN.

VALOAREA RETURNATĂ
În caz de succes, getrandom() returnează numărul de octeți care au fost copiați în memoria tampon buf. Acesta poate fi mai mic decât numărul de octeți solicitat prin buflen dacă fie GRND_RANDOM a fost specificat în flags și entropia a fost insuficientă în sursa random, fie apelul sistemului a fost întrerupt de un semnal.

În caz de eroare, se returnează -1, iar errno este configurată pentru a indica eroarea.

ERORI-IEȘIRE

EAGAIN
    Entropia solicitată nu a fost disponibilă, iar getrandom() s-ar fi blocat dacă flagul GRND_NONBLOCK nu era activat.

EFAULT
    Adresa menționată de buf se află în afara spațiului de adrese accesibil.

EINTR
    Apelul a fost întrerupt de un gestionar de semnal; consultați descrierea modului în care apelurile read(2) întrerupte pe dispozitive „lente” sunt gestionate cu și fără fanionul SA_RESTART în pagina de manual signal(7).

EINVAL
    În flags a fost specificat un fanion nevalid.

ENOSYS
    Funcția de învăluire a glibc pentru getrandom() a determinat că nucleul subiacent nu implementează acest apel de sistem.

STANDARDE
Linux.

ISTORIC
Linux 3.17, glibc 2.25.

NOTE
Pentru o prezentare generală și o comparație a diverselor interfețe care pot fi utilizate pentru a obține caracterul aleatoriu, a se vedea random(7).

tătăSpre deosebire de /dev/random și /dev/urandom, getrandom() nu implică utilizarea numelor de rută sau a descriptorilor de fișiere. Astfel, getrandom() poate fi util în cazurile în care chroot(2) face invizibile numele de rută /dev și în care o aplicație (de exemplu, un demon în timpul lansării) închide un descriptor de fișier pentru unul dintre aceste fișiere care a fost deschis de o bibliotecă.

  Numărul maxim de octeți returnați
Începând cu Linux 3.19 se aplică următoarele limite:

•   La citirea din sursa urandom, un singur apel la getrandom() returnează maximum 32Mi-1 octeți pe sistemele în care int are o dimensiune de 32 de biți.

•   La citirea din sursa random, se returnează un maxim de 512 octeți.

  Întreruperea de către un gestionar de semnal
La citirea din sursa urandom (GRND_RANDOM nu este activat), getrandom() se va bloca până când fondul de entropie a fost inițializat (cu excepția cazului în care a fost specificat fanionul GRND_NONBLOCK). Dacă se solicită citirea unui număr mare de octeți (mai mult de 256), getrandom() se va bloca până când acești octeți au fost generați și transferați din memoria nucleului în buf. Atunci când se citește din sursa random (GRND_RANDOM este activat), getrandom() se va bloca până când unii octeți aleatori devin disponibili (cu excepția cazului în care a fost specificat fanionul GRND_NONBLOCK).

Comportamentul atunci când un apel la getrandom() care este blocat în timp ce citește din sursa urandom este întrerupt de un gestionar de semnal depinde de starea de inițializare a tamponului de entropie și de dimensiunea cererii, buflen. Dacă entropia nu este încă inițializată, atunci apelul eșuează cu eroarea EINTR. Dacă fondul de entropie a fost inițializat și dimensiunea cererii este mare (buflen > 256), apelul fie reușește, returnând un tampon parțial umplut, fie eșuează cu eroarea EINTR. Dacă fondul de entropie a fost inițializat și dimensiunea cererii este mică (buflen <= 256), atunci getrandom() nu va eșua cu EINTR. În schimb, va returna toți octeții care au fost solicitați.

La citirea din sursa random, cererile de blocare de orice dimensiune pot fi întrerupte de un gestionar de semnal (apelul eșuează cu eroarea EINTR).

Utilizarea getrandom() pentru a citi tampoane mici (<= 256 bytes) din sursa urandom este modul preferat de utilizare.

Tratamentul special al valorilor mici ale buflen a fost conceput pentru compatibilitate cu getentropy(3) de la OpenBSD, care este în prezent acceptat de glibc.

Utilizatorul aplicației getrandom() trebuie să verifice întotdeauna valoarea returnată, pentru a determina dacă s-a produs o eroare sau dacă s-au returnat mai puțini octeți decât s-a solicitat. În cazul în care GRND_RANDOM nu este specificat și buflen este mai mic sau egal cu 256, o returnare de mai puțini octeți decât s-a solicitat nu ar trebui să se întâmple niciodată, dar programatorul atent va verifica acest lucru oricum!

ERORI
Începând cu Linux 3.19, există următoarea eroare:

•   În funcție de sarcina CPU, getrandom() nu reacționează la întreruperi înainte de a citi toți octeții solicitați.

CONSULTAȚI ȘI
getentropy(3), random(4), urandom(4), random(7), signal(7)

TRADUCERE
Traducerea în limba română a acestui manual a fost făcută de Remus-Gabriel Chelu <remusgabriel.chelu@disroot.org>

Această traducere este documentație gratuită; citiți Licența publică generală GNU Versiunea 3 (https://www.gnu.org/licenses/gpl-3.0.html) sau o versiune ulterioară cu privire la condiții privind drepturile de autor. NU se asumă NICIO RESPONSABILITATE.

Dacă găsiți erori în traducerea acestui manual, vă rugăm să trimiteți un e-mail la translation-team-ro@lists.sourceforge.net.