Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ././../../../../../../usr/man/man2/getrandom.2
Real path: /usr/share/man/man2/getrandom.2
Zurück

'\" te
.\" Copyright (c) 2015, 2023, Oracle and/or its affiliates.
.TH getrandom 2 "30 Jan 2023" "Oracle Solaris 11.4" "System Calls"
.SH NAME
getrandom, getentropy \- retrieve data from the kernel random pool
.SH SYNOPSIS

.LP
.nf
#include <sys/random.h>

\fBssize_t\fR \fBgetrandom\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR, \fBunsigned int\fR \fIflags\fR);
.fi

.LP
.nf
#include <unistd.h>

\fBint\fR \fBgetentropy\fR(\fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fIbuflen\fR);
.fi
.SH DESCRIPTION
.sp
.LP
The \fBgetrandom()\fR function can be used to request \fIbuflen\fR bytes of data from the kernel random pool, which is to be placed into the buffer pointed to by \fIbuf\fR. It is recommended to use the \fBgetrandom()\fR function instead of \fBopen\fR(2) and \fBread\fR(2) functions on the \fB/dev/random\fR or \fB/dev/urandom\fR device.
.sp
.LP
The random data returned by the \fBgetrandom()\fR function is processed by a FIPS 140-2 approved deterministic random bit generator (DRBG).
.sp
.LP
If the \fBGRND_RANDOM\fR flag is set, then the implementation uses the same pool as \fB/dev/random\fR, otherwise the \fB/dev/urandom\fR pool is used.
.sp
.LP
If no entropy is available in the pool, the \fBgetrandom()\fR function will block unless the \fBGRND_NONBLOCK\fR flag is set. In this case, the function returns \fB-1\fR and \fBerrno\fR is set to \fBEAGAIN\fR. Note that the number of bytes returned can be less than requested, including \fB0\fR. Callers need to check the return value to determine if random bytes were returned. This means this is not an acceptable calling sequence:
.sp
.in +2
.nf
(void) getrandom(&buf, sizeof (buf), 0);
.fi
.in -2
.sp
.sp
.LP
The \fBgetentropy()\fR function is always a blocking call, it is expected to be used only to seed a userspace implementation of a random bit generator.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the \fBgetrandom()\fR function returns the number of bytes written to \fIbuf\fR. Otherwise, it returns \fB0\fR and sets \fBerrno\fR to indicate the error.
.sp
.LP
Upon successful completion, the \fBgetentropy()\fR function returns \fB0\fR. Otherwise, it returns \fB-1\fR and sets \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBgetrandom()\fR and \fBgetentropy()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt
Invalid flags or flag combinations
.RS +4
.TP
.ie t \(bu
.el o
\fIbufsz\fR is \fB<= 0 or > 1040\fR, when \fBGRND_RANDOM\fR is set

.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIbufsz\fR is \fB<= 0\fR or \fB> 133120\fR, when \fBGRND_RANDOM\fR is not set

.RE
.RE

.sp
.ne 2
.mk
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
.rt
\fIbuf\fR is an invalid address.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
.rt
No entropy is available and \fBGRND_NONBLOCK\fR is set.
.RE

.sp
.LP
The \fBgetentropy()\fR call also fails if:
.sp
.ne 2
.mk
.na
\fB\fBEIO\fR\fR
.ad
.RS 7n
.rt
More than 256 bytes are requested, or the returned amount of entropy does not match the request.
.RE

.SH EXAMPLES
.LP
\fBExample 1\fR Using the \fBgetrandom()\fR function

.sp
.in +2
.nf
#include <sys/random.h>
#include <stdlib.h>
\&.
size_t bufsz = 1024;
char *buf;
int ret;
\&.
\&...
buf = malloc(bufsz);
\&...
ret = getrandom(buf, bufsz, GRND_RANDOM);
if (ret != bufsz) {
        perror("getrandom failed");
        ...
}
\&...
.fi
.in -2
.sp
.LP
\fBExample 2\fR Using the \fBgetentropy()\fR function

.sp
.in +2
.nf
#include <sys/random.h>
#include <stdlib.h>
\&.
size_t entsz = 128;
char *entropy;
int err;
\&.
\&...
entropy = malloc(entsz);
\&...
err = getentropy(entropy, entsz);
if (err != 0) {
        perror("getentropy failed");
        ...
}
/* Use entropy to seed our RNG */
.fi
.in -2
.sp
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp
.TS
tab(
) box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPE
ATTRIBUTE VALUE
_
Interface Stability
Committed
_
MT-Level
MT-Safe
.TE
.sp
.SH SEE ALSO
.sp
.LP
\fBrandom\fR(4D)
.SH HISTORY
.sp
.LP
The \fBgetrandom()\fR and \fBgetentropy()\fR functions were added to Oracle Solaris in the Solaris 11.3.0 release.
.sp
.LP
The function prototype for \fBgetentropy()\fR was added to the <\fBunistd.h\fR> header in Oracle Solaris 11.4.16. Prior to that, applications needed to include <\fBsys/random.h\fR> as well.
.sp
.LP
The \fBgetentropy()\fR function first appeared in OpenBSD 5.6. The \fBgetrandom()\fR function first appeared in GNU libc 2.25.