Debian Codegraph @

upstream/debian-unstable/man3/sd_id128_randomize.3

raw
1 '\" t
2 .TH "SD_ID128_RANDOMIZE" "3" "" "systemd 261~rc3" "sd_id128_randomize"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_id128_randomize \- Generate 128\-bit IDs
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-id128\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_id128_randomize('u
32 .BI "int sd_id128_randomize(sd_id128_t\ *" "ret" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_id128_randomize()\fR
36 generates a new randomized 128\-bit ID and returns it in
37 \fIret\fR\&. Every invocation returns a new randomly generated ID\&. This uses the
38 \fBgetrandom\fR(2)
39 kernel random number generator\&.
40 .PP
41 Note that
42 \fBsd_id128_randomize()\fR
43 always returns a UUID Variant 1 Version 4 compatible ID\&. It is hence guaranteed that this function will never return the ID consisting of all zero or all one bits (\fBSD_ID128_NULL\fR,
44 \fBSD_ID128_ALLF\fR)\&.
45 .PP
46 For more information about the
47 "sd_id128_t"
48 type, see
49 \fBsd-id128\fR(3)\&.
50 .PP
51 \fBsystemd-id128\fR(1)\*(Aqs
52 \fBnew\fR
53 command may be used as a command line front\-end for
54 \fBsd_id128_randomize()\fR\&.
55 .SH "RETURN VALUE"
56 .PP
57 The call returns 0 on success (in which case
58 \fIret\fR
59 is filled in), or a negative errno\-style error code\&.
60 .SH "NOTES"
61 .PP
62 Functions described here are available as a shared library, which can be compiled against and linked to with the
63 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
64 file\&.
65 .PP
66 The code described here uses
67 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
68 \fBsetenv\fR(3)
69 from a parallel thread\&. It is recommended to only do calls to
70 \fBsetenv()\fR
71 from an early phase of the program when no other threads have been started\&.
72 .SH "HISTORY"
73 .PP
74 \fBsd_id128_randomize()\fR
75 was added in version 187\&.
76 .SH "SEE ALSO"
77 .PP
78 \fBsystemd\fR(1), \fBsd-id128\fR(3), \fBmachine-id\fR(5), \fBgetrandom\fR(2), \fBrandom\fR(4), \fBsd_id128_get_machine\fR(3)