diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/sd_id128_to_string.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/sd_id128_to_string.3 | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/sd_id128_to_string.3 b/upstream/opensuse-tumbleweed/man3/sd_id128_to_string.3 deleted file mode 100644 index 1b52e376..00000000 --- a/upstream/opensuse-tumbleweed/man3/sd_id128_to_string.3 +++ /dev/null @@ -1,135 +0,0 @@ -'\" t -.TH "SD_ID128_TO_STRING" "3" "" "systemd 254" "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 "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 |