Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 144 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3/sd_id128_to_string.3 b/upstream/mageia-cauldron/man3/sd_id128_to_string.3
new file mode 100644
index 00000000..33161959
--- /dev/null
+++ b/upstream/mageia-cauldron/man3/sd_id128_to_string.3
@@ -0,0 +1,144 @@
+'\" t
+.TH "SD_ID128_TO_STRING" "3" "" "systemd 255" "sd_id128_to_string"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+sd_id128_to_string, SD_ID128_TO_STRING, SD_ID128_STRING_MAX, sd_id128_to_uuid_string, SD_ID128_TO_UUID_STRING, SD_ID128_UUID_STRING_MAX, sd_id128_from_string \- Format or parse 128\-bit IDs as strings
+.SH "SYNOPSIS"
+.sp
+.ft B
+.nf
+#include <systemd/sd\-id128\&.h>
+.fi
+.ft
+.sp
+.ft B
+.nf
+#define SD_ID128_STRING_MAX 33U
+.fi
+.ft
+.sp
+.ft B
+.nf
+#define SD_ID128_UUID_STRING_MAX 37U
+.fi
+.ft
+.sp
+.ft B
+.nf
+#define SD_ID128_TO_STRING(id) \&...
+.fi
+.ft
+.sp
+.ft B
+.nf
+#define SD_ID128_TO_UUID_STRING(id) \&...
+.fi
+.ft
+.HP \w'char\ *sd_id128_to_string('u
+.BI "char *sd_id128_to_string(sd_id128_t\ " "id" ",\ char\ " "s" "[static\ SD_ID128_STRING_MAX]);"
+.HP \w'char\ *sd_id128_uuid_string('u
+.BI "char *sd_id128_uuid_string(sd_id128_t\ " "id" ",\ char\ " "s" "[static\ SD_ID128_UUID_STRING_MAX]);"
+.HP \w'int\ sd_id128_from_string('u
+.BI "int sd_id128_from_string(const\ char\ *" "s" ",\ sd_id128_t\ *" "ret" ");"
+.SH "DESCRIPTION"
+.PP
+\fBsd_id128_to_string()\fR
+formats a 128\-bit ID as a character string\&. It expects the ID and a string array capable of storing 33 characters (\fBSD_ID128_STRING_MAX\fR)\&. The ID will be formatted as 32 lowercase hexadecimal digits and be terminated by a
+\fBNUL\fR
+byte\&.
+.PP
+\fBSD_ID128_TO_STRING()\fR
+is a macro that wraps
+\fBsd_id128_to_string()\fR
+and passes an appropriately sized buffer as second argument, allocated as C99 compound literal\&. Each use will thus implicitly acquire a suitable buffer on the stack which remains valid until the end of the current code block\&. This is usually the simplest way to acquire a string representation of a 128\-bit ID in a buffer that is valid in the current code block\&.
+.PP
+\fBsd_id128_to_uuid_string()\fR
+and
+\fBSD_ID128_TO_UUID_STRING()\fR
+are similar to these two functions/macros, but format the 128\-bit values as RFC4122 UUIDs, i\&.e\&. a series of 36 lowercase hexadeciaml digits and dashes, terminated by a
+\fBNUL\fR
+byte\&.
+.PP
+\fBsd_id128_from_string()\fR
+implements the reverse operation: it takes a 33 character string with 32 hexadecimal digits (either lowercase or uppercase, terminated by
+\fBNUL\fR) and parses them back into a 128\-bit ID returned in
+\fIret\fR\&. Alternatively, this call can also parse a 37\-character string with a 128\-bit ID formatted as RFC UUID\&. If
+\fIret\fR
+is passed as
+\fBNULL\fR
+the function will validate the passed ID string, but not actually return it in parsed form\&.
+.PP
+Note that when formatting and parsing 36 character UUIDs this is done strictly in Big Endian byte order, i\&.e\&. according to
+\m[blue]\fBRFC4122\fR\m[]\&\s-2\u[1]\d\s+2
+Variant 1 rules, even if the UUID encodes a different variant\&. This matches behaviour in various other Linux userspace tools\&. It\*(Aqs probably wise to avoid UUIDs of other variant types\&.
+.PP
+For more information about the
+"sd_id128_t"
+type see
+\fBsd-id128\fR(3)\&. Note that these calls operate the same way on all architectures, i\&.e\&. the results do not depend on endianness\&.
+.PP
+When formatting a 128\-bit ID into a string, it is often easier to use a format string for
+\fBprintf\fR(3)\&. This is easily done using the
+\fBSD_ID128_FORMAT_STR\fR
+and
+\fBSD_ID128_FORMAT_VAL()\fR
+macros\&. For more information see
+\fBsd-id128\fR(3)\&.
+.SH "RETURN VALUE"
+.PP
+\fBsd_id128_to_string()\fR
+always succeeds and returns a pointer to the string array passed in\&.
+\fBsd_id128_from_string()\fR
+returns 0 on success, in which case
+\fIret\fR
+is filled in, or a negative errno\-style error code\&.
+.SH "NOTES"
+.PP
+Functions described here are available as a shared library, which can be compiled against and linked to with the
+\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
+file\&.
+.PP
+The code described here uses
+\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
+\fBsetenv\fR(3)
+from a parallel thread\&. It is recommended to only do calls to
+\fBsetenv()\fR
+from an early phase of the program when no other threads have been started\&.
+.SH "HISTORY"
+.PP
+\fBsd_id128_to_string()\fR
+and
+\fBsd_id128_from_string()\fR
+were added in version 187\&.
+.PP
+\fBsd_id128_uuid_string()\fR
+was added in version 251\&.
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsd-id128\fR(3),
+\fBprintf\fR(3)
+.SH "NOTES"
+.IP " 1." 4
+RFC4122
+.RS 4
+\%https://tools.ietf.org/html/rfc4122
+.RE