182 lines
5.0 KiB
Groff
182 lines
5.0 KiB
Groff
.\" Copyright (c) 2002 Marcel Moolenaar
|
|
.\" Copyright (c) 2002 Hiten Mahesh Pandya
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
|
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
|
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 19, 2021
|
|
.Dt UUID 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm uuid_compare , uuid_create , uuid_create_nil , uuid_equal ,
|
|
.Nm uuid_from_string , uuid_hash , uuid_is_nil , uuid_to_string
|
|
.Nd DCE 1.1 compliant UUID functions
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In uuid.h
|
|
.Ft int32_t
|
|
.Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
|
|
.Ft void
|
|
.Fn uuid_create "uuid_t *uuid" "uint32_t *status"
|
|
.Ft void
|
|
.Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status"
|
|
.Ft int32_t
|
|
.Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
|
|
.Ft void
|
|
.Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status"
|
|
.Ft uint16_t
|
|
.Fn uuid_hash "const uuid_t *uuid" "uint32_t *status"
|
|
.Ft int32_t
|
|
.Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status"
|
|
.Ft void
|
|
.Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status"
|
|
.Ft void
|
|
.Fn uuid_enc_le "void *buf" "const uuid_t *uuid"
|
|
.Ft void
|
|
.Fn uuid_dec_le "const void *buf" "uuid_t *"
|
|
.Ft void
|
|
.Fn uuid_enc_be "void *buf" "const uuid_t *uuid"
|
|
.Ft void
|
|
.Fn uuid_dec_be "const void *buf" "uuid_t *"
|
|
.Sh DESCRIPTION
|
|
The family of DCE 1.1 compliant UUID functions allow applications to operate
|
|
on universally unique identifiers, or UUIDs.
|
|
The
|
|
.Fn uuid_create
|
|
and
|
|
.Fn uuid_create_nil
|
|
functions create UUIDs.
|
|
To convert from the binary representation to the string representation or
|
|
vice versa, use
|
|
.Fn uuid_to_string
|
|
or
|
|
.Fn uuid_from_string
|
|
respectively.
|
|
.Pp
|
|
The
|
|
.Fn uuid_to_string
|
|
function set
|
|
.Fa *str
|
|
to be a pointer to a buffer sufficiently large to hold the string.
|
|
This pointer should be passed to
|
|
.Xr free 3
|
|
to release the allocated storage when it is no longer needed.
|
|
.Pp
|
|
The
|
|
.Fn uuid_enc_le
|
|
and
|
|
.Fn uuid_enc_be
|
|
functions encode a binary representation of a UUID into an octet stream
|
|
in little-endian and big-endian byte-order, respectively.
|
|
The destination buffer must be pre-allocated by the caller, and must be
|
|
large enough to hold the 16-octet binary UUID.
|
|
These routines are not part of the DCE RPC API.
|
|
They are provided for convenience.
|
|
.Pp
|
|
The
|
|
.Fn uuid_dec_le
|
|
and
|
|
.Fn uuid_dec_be
|
|
functions decode a UUID from an octet stream in little-endian and
|
|
big-endian byte-order, respectively.
|
|
These routines are not part of the DCE RPC API.
|
|
They are provided for convenience.
|
|
.Pp
|
|
The
|
|
.Fn uuid_compare
|
|
and
|
|
.Fn uuid_equal
|
|
functions compare two UUIDs for equality.
|
|
UUIDs are equal if pointers
|
|
.Fa a
|
|
and
|
|
.Fa b
|
|
are equal or both
|
|
.Dv NULL ,
|
|
or if the structures
|
|
.Fa a
|
|
and
|
|
.Fa b
|
|
point to are equal.
|
|
.Fn uuid_compare
|
|
returns 0 if the UUIDs are equal, -1 if
|
|
.Fa a
|
|
is less than
|
|
.Fa b ,
|
|
and 1 if
|
|
.Fa a
|
|
is greater than
|
|
.Fa b .
|
|
.Fn uuid_equal
|
|
returns 1 if the UUIDs are equal, 0 if they are
|
|
not equal.
|
|
.Pp
|
|
The
|
|
.Fn uuid_is_nil
|
|
function compares a UUID to
|
|
.Dv NULL .
|
|
The function returns 1 if
|
|
.Fa u
|
|
is
|
|
.Dv NULL
|
|
or if the UUID consists of all zeros, and zero otherwise.
|
|
.Pp
|
|
The
|
|
.Fn uuid_hash
|
|
function returns a 16-bit hash value for the specified UUID.
|
|
.Sh RETURN VALUES
|
|
The successful or unsuccessful completion of the function is returned in
|
|
the
|
|
.Fa status
|
|
argument.
|
|
Possible values are:
|
|
.Bl -tag -width ".Dv uuid_s_invalid_string_uuid"
|
|
.It Dv uuid_s_ok
|
|
The function completed successfully.
|
|
.It Dv uuid_s_bad_version
|
|
The UUID does not have a known version.
|
|
.It Dv uuid_s_invalid_string_uuid
|
|
The string representation of an UUID is not valid.
|
|
.It Dv uuid_s_no_memory
|
|
The function can not allocate memory to store an UUID representation.
|
|
.El
|
|
.Pp
|
|
.Fn uuid_compare ,
|
|
.Fn uuid_equal ,
|
|
.Fn uuid_is_nil ,
|
|
and
|
|
.Fn uuid_hash
|
|
always set
|
|
.Fa status
|
|
to
|
|
.Dv uuid_s_ok .
|
|
.Sh SEE ALSO
|
|
.Xr uuidgen 1 ,
|
|
.Xr uuidgen 2
|
|
.Sh STANDARDS
|
|
The UUID functions conform to the DCE 1.1 RPC specification.
|
|
.Sh BUGS
|
|
This manpage can be improved.
|