Provided by: manpages-fr-dev_4.19.0-7_all 
NOM
getrandom - obtenir une série d'octets aléatoires
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <sys/random.h>
ssize_t getrandom(void buf[.buflen], size_t buflen, unsigned int flags);
DESCRIPTION
L'appel système getrandom() remplit le tampon vers lequel pointe buf avec jusqu'à buflen
octets aléatoires. Ces octets peuvent être utilisés pour alimenter des générateurs de
nombre aléatoire dans l'espace utilisateur ou à des fins de chiffrement.
Par défaut, getrandom() dessine une entropie à partir d'une source urandom (soit la même
source que le périphérique /dev/urandom). Ce comportement peut être modifié avec le
paramètre flags.
Si la source urandom a été initialisée, les lectures jusqu'à 256 octets renverront
toujours autant d'octets que demandé et ne seront pas interrompues par des signaux. Il n'y
a pas une telle garantie pour les tampons plus gros. Par exemple, si l'appel est
interrompu par un gestionnaire de signal, il peut renvoyer un tampon partiellement rempli
ou échouer avec l'erreur EINTR.
Si la source urandom n'a pas encore été initialisée, getrandom() se bloquera, sauf si
GRND_NONBLOCK est indiqué dans flags.
Le paramètre flags est un masque de bit qui peut contenir aucune ou plusieurs des valeurs
suivantes unies (OU logique) ensemble :
GRND_RANDOM
Si ce bit est positionné, les octets aléatoires seront dessinés à partir de la
source random (soit la même que le périphérique /dev/random) au lieu de la source
urandom. La source random est limitée par l'entropie qui peut être récupérée à
partir du bruit de l'environnement. Si le nombre d'octets disponibles dans la
source random est inférieur à celui demandé dans buflen, l'appel ne renvoie que les
octets aléatoires disponibles. S'il n'y pas d'octets aléatoires disponibles, le
comportement dépend de la présence de GRND_NONBLOCK dans le paramètre flags.
GRND_NONBLOCK
Par défaut, pendant une lecture depuis la source random, getrandom() se bloque si
aucun octet aléatoire n'est disponible, tandis que pendant une lecture à partir de
la source urandom, il se bloque si la réserve (pool) d'entropie n'a pas encore été
initialisée. Si le paramètre GRND_NONBLOCK est positionné, getrandom() ne se bloque
pas dans ces cas, mais il renvoie immédiatement -1 et il positionne errno sur
EAGAIN.
VALEUR RENVOYÉE
En cas de succès, getrandom() renvoie le nombre d'octets copiés dans le tampon buf. Il
peut être inférieur au nombre d'octets demandé par buflen si GRND_RANDOM a été indiqué
dans flags et qu'il n'y avait pas assez d'entropie dans la source random, ou si l'appel
système a été interrompu par un signal.
En cas d'erreur, la valeur de retour est -1 et errno est définie pour préciser l'erreur.
ERREURS
EAGAIN L'entropie demandée n'était pas disponible et getrandom() se serait bloqué si le
paramètre GRND_NONBLOCK n'avait pas été positionné.
EFAULT L'adresse à laquelle renvoie buf est en dehors de l'espace d'adressage accessible.
EINTR L'appel a été interrompu par un gestionnaire de signal ; voir la description sur la
manière dont sont gérés les appels read(2) interrompus sur des périphériques
« lents » avec et sans l'attribut SA_RESTART dans la page de manuel de signal(7).
EINVAL Un paramètre non valable a été indiqué dans flags.
ENOSYS La fonction enveloppe de la glibc pour getrandom() a déterminé que le noyau
sous-jacent n'implémente pas cet appel système.
VERSIONS
getrandom() a été introduit dans Linux 3.17. La prise en charge a été ajoutée dans la
glibc 2.25.
STANDARDS
Cet appel système est spécifique à Linux.
NOTES
Pour un aperçu et une comparaison des interfaces utilisables pour produire de l'aléatoire,
voir random(7).
Contrairement à /dev/random et à /dev/urandom, getrandom() n'implique pas d'utiliser des
noms de chemin ou des descripteurs de fichier. Ainsi, getrandom() peut être utile dans les
cas où chroot(2) rend invisibles les noms de chemin /dev, et où une application (comme un
démon qui démarre) ferme un descripteur de fichier pour un de ces fichiers ouverts par une
bibliothèque.
Nombre maximal d'octets renvoyés
À partir de Linux 3.19, les limites suivantes s'appliquent :
• Pendant une lecture à partir d'une source urandom, un maximum de 32Mi-1 octets est
renvoyé par un appel getrandom() sur des systèmes où int a une taille de 32 bits.
• Lors d'une lecture à partir d'une source random, un maximum de 512 octets est renvoyé.
Interruption par un gestionnaire de signal
Lors de la lecture à partir d'une source urandom (GRND_RANDOM n'est pas positionné),
getrandom() se bloquera jusqu'à ce que la réserve (pool) d'entropie soit initialisée (sauf
si l'attribut GRND_NONBLOCK a été indiqué). Si une demande est faite pour lire un grand
nombre d'octets (plus de 256), getrandom() se bloquera jusqu'à ce que ces octets soient
générés et transférés de la mémoire du noyau vers buf. Lors d'une lecture à partir d'une
source random (GRND_RANDOM est positionné), getrandom() se bloquera jusqu'à ce que des
octets aléatoires soient disponibles (sauf si l'attribut GRND_NONBLOCK a été indiqué).
Quand un appel getrandom() se bloque pendant la lecture à partir d'une source urandom du
fait d'une interruption par un gestionnaire de signal, le comportement dépend de l'état
d'initialisation du tampon d'entropie et de la taille de la requête, buflen. Si la réserve
d'entropie n'est pas encore initialisée, l'appel échoue avec l'erreur EINTR. Si cette
réserve d'entropie a été initialisée et si la taille de la requête est importante
(buflen > 256), soit l'appel réussit, en renvoyant un tampon partiellement rempli, soit il
échoue avec l'erreur EINTR. Si la réserve d'entropie a été initialisée et si la taille
demandée est petite (buflen <= 256), getrandom() n'échouera pas avec EINTR. Il renverra
plutôt tous les octets demandés.
Pendant une lecture avec une source random, les requêtes bloquantes de n'importe quelle
taille peuvent être interrompues par un gestionnaire de signal (l'appel échoue avec
l'erreur EINTR).
L'utilisation de getrandom() pour lire de petits tampons (<= 256 octets) à partir d'une
source urandom est le cas d'utilisation privilégié.
Le traitement particulier des petites valeurs de buflen a été conçu à des fins de
compatibilité avec le getentropy(3) d'OpenBSD, qui est aujourd'hui géré par la glibc.
L'utilisateur de getrandom() doit toujours vérifier la valeur renvoyée, pour savoir si une
erreur s'est produite ou si moins d'octets que le nombre demandé ont été renvoyés. Au cas
où GRND_RANDOM n'est pas indiqué et où buflen est inférieur ou égal à 256, il ne devrait
jamais y avoir de renvoi d'un nombre d'octets inférieur à celui demandé, mais un
programmeur prudent le vérifiera quand même.
BOGUES
À partir de Linux 3.19, le bogue suivant existe :
• Selon la charge du processeur, getrandom() ne réagit pas aux interruptions avant de
lire tous les octets demandés.
VOIR AUSSI
getentropy(3), random(4), urandom(4), random(7), signal(7)
TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess
<https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry
Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>,
Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-
luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis
Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Jean-Philippe MENGUAL
<jpmengual@debian.org>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ concernant les
conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
message à ⟨debian-l10n-french@lists.debian.org⟩.