From a4023a43d0312568f0b81b39b4bc6fd9b64880eb Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Fri, 13 Jul 2012 22:55:52 +0200 Subject: [PATCH] man: Split sd_randomize(3) from sd_id128_get_{machine,boot}(3) They have too little to do with each other... --- Makefile.am | 4 +- man/sd-id128.xml | 6 +- man/sd_id128_get_machine.xml | 138 +++++++++++++++++++++++++++++++++++ man/sd_id128_randomize.xml | 55 ++------------ 4 files changed, 152 insertions(+), 51 deletions(-) create mode 100644 man/sd_id128_get_machine.xml diff --git a/Makefile.am b/Makefile.am index 3dfe8a25e..3dda9b85f 100644 --- a/Makefile.am +++ b/Makefile.am @@ -498,6 +498,7 @@ MANPAGES = \ man/sd-id128.3 \ man/sd_id128_to_string.3 \ man/sd_id128_randomize.3 \ + man/sd_id128_get_machine.3 \ man/sd-journal.3 \ man/sd_journal_print.3 \ man/sd_journal_stream_fd.3 \ @@ -604,8 +605,7 @@ man/SD_ID128_FORMAT_STR.3: man/sd-id128.3 man/SD_ID128_FORMAT_VAL.3: man/sd-id128.3 man/sd_id128_equal.3: man/sd-id128.3 man/sd_id128_from_string.3: man/sd_id128_to_string.3 -man/sd_id128_get_machine.3: man/sd_id128_randomize.3 -man/sd_id128_get_boot.3: man/sd_id128_randomize.3 +man/sd_id128_get_boot.3: man/sd_id128_get_machine.3 man/sd_journal_printv.3: man/sd_journal_print.3 man/sd_journal_send.3: man/sd_journal_print.3 man/sd_journal_sendv.3: man/sd_journal_print.3 diff --git a/man/sd-id128.xml b/man/sd-id128.xml index d3f995e00..d45339043 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -78,8 +78,9 @@ See - sd_id128_to_string3 and - sd_id128_randomize3 + sd_id128_to_string3, + sd_id128_randomize3 and + sd_id128_get_machine3 for more information about the implemented functions. @@ -157,6 +158,7 @@ systemd1, sd_id128_to_string3, sd_id128_randomize3, + sd_id128_get_machine3, printf3, journalctl1, sd-journal7, diff --git a/man/sd_id128_get_machine.xml b/man/sd_id128_get_machine.xml new file mode 100644 index 000000000..039c1dd64 --- /dev/null +++ b/man/sd_id128_get_machine.xml @@ -0,0 +1,138 @@ + + + + + + + + + sd_id128_get_machine + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_id128_get_machine + 3 + + + + sd_id128_get_machine + sd_id128_get_boot + Retrieve 128 bit IDs + + + + + #include <systemd/sd-id128.h> + + + int sd_id128_get_machine + sd_id128_t* ret + + + + int sd_id128_get_boot + sd_id128_t* ret + + + + + + + Description + + sd_id128_get_machine() + returns the machine ID of the executing host. This + reads and parses the + machine-id5 + file. This function caches the machine ID internally + to make retrieving the machine ID a cheap + operation. + + sd_id128_get_boot() returns + the boot ID of the executing kernel. This reads and + parses the + /proc/sys/kernel/random/boot_id + file exposed by the kernel. It is randomly generated + early at boot and is unique for every running kernel + instance. See + random4 + for more information. This function also internally + caches the returned ID to make this call a cheap + operation. + + Note that + sd_id128_get_boot() always returns + a UUID v4 compatible + ID. sd_id128_get_machine() will + also return a UUID v4 compatible ID on new + installations, but might not on older. It is possible + to convert the machine ID into an UUID v4 compatible + one. For more information see + machine-id5. + + For more information about the + sd_id128_t type see + sd-id1283. + + + + Return Value + + The two calls return 0 on success (in which + case ret is filled in), or a + negative errno-style error code. + + + + Notes + + The sd_id128_get_machine() + and sd_id128_get_boot() + interfaces are available as shared library, which can + be compiled and linked to with the + libsystemd-id128 + pkg-config1 + file. + + + + See Also + + + systemd1, + sd-id1283, + machine-id5, + random4, + sd_id128_randomize3 + + + + diff --git a/man/sd_id128_randomize.xml b/man/sd_id128_randomize.xml index cb3741966..be74937dd 100644 --- a/man/sd_id128_randomize.xml +++ b/man/sd_id128_randomize.xml @@ -44,9 +44,7 @@ sd_id128_randomize - sd_id128_get_machine - sd_id128_get_boot - Generate or retrieve 128 bit IDs + Generate 128 bit IDs @@ -58,16 +56,6 @@ sd_id128_t* ret - - int sd_id128_get_machine - sd_id128_t* ret - - - - int sd_id128_get_boot - sd_id128_t* ret - - @@ -81,36 +69,10 @@ /dev/urandom kernel random number generator. - sd_id128_get_machine() - returns the machine ID of the executing host. This - reads and parses the - machine-id5 - file. This function caches the machine ID internally - to make retrieving the machine ID a cheap - operation. - - sd_id128_get_boot() returns - the boot ID of the executing kernel. This reads and - parses the - /proc/sys/kernel/random/boot_id - file exposed by the kernel. It is randomly generated - early at boot and is unique for every running kernel - instance. See - random4 - for more information. This function also internally - caches the returned ID to make this call a cheap - operation. - Note that - sd_id128_randomize() and - sd_id128_get_boot() always return + sd_id128_randomize() always returns a UUID v4 compatible - ID. sd_id128_get_machine() will - also return a UUID v4 compatible ID on new - installations, but might not on older. It is possible - to convert the machine ID into an UUID v4 compatible - one. For more information see - machine-id5. + ID. For more information about the sd_id128_t type see @@ -125,7 +87,7 @@ Return Value - The three calls return 0 on success (in which + The call returns 0 on success (in which case ret is filled in), or a negative errno-style error code. @@ -133,10 +95,8 @@ Notes - The sd_id128_randomize(), - sd_id128_get_machine() and - sd_id128_get_boot() interfaces - are available as shared library, which can be compiled + The sd_id128_randomize() interface + is available as shared library, which can be compiled and linked to with the libsystemd-id128 pkg-config1 @@ -150,7 +110,8 @@ systemd1, sd-id1283, machine-id5, - random4 + random4, + sd_id128_get_machine3