lib/libc/uuid/uuid.3

   1 .\" Copyright (c) 2002 Marcel Moolenaar
   2 .\" Copyright (c) 2002 Hiten Mahesh Pandya
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  19 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  20 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  21 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  22 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd March 1, 2012
  29 .Dt UUID 3
  30 .Os
  31 .Sh NAME
  32 .Nm uuid_compare , uuid_create , uuid_create_nil , uuid_equal ,
  33 .Nm uuid_from_string , uuid_hash , uuid_is_nil , uuid_to_string
  34 .Nd DCE 1.1 compliant UUID functions
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In uuid.h
  39 .Ft int32_t
  40 .Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
  41 .Ft void
  42 .Fn uuid_create "uuid_t *uuid" "uint32_t *status"
  43 .Ft void
  44 .Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status"
  45 .Ft int32_t
  46 .Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
  47 .Ft void
  48 .Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status"
  49 .Ft uint16_t
  50 .Fn uuid_hash "const uuid_t *uuid" "uint32_t *status"
  51 .Ft int32_t
  52 .Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status"
  53 .Ft void
  54 .Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status"
  55 .Ft void
  56 .Fn uuid_enc_le "void *buf" "const uuid_t *uuid"
  57 .Ft void
  58 .Fn uuid_dec_le "const void *buf" "uuid_t *"
  59 .Ft void
  60 .Fn uuid_enc_be "void *buf" "const uuid_t *uuid"
  61 .Ft void
  62 .Fn uuid_dec_be "const void *buf" "uuid_t *"
  63 .Sh DESCRIPTION
  64 The family of DCE 1.1 compliant UUID functions allow applications to operate
  65 on universally unique identifiers, or UUIDs.
  66 The
  67 .Fn uuid_create
  68 and
  69 .Fn uuid_create_nil
  70 functions create UUIDs.
  71 The
  72 .Fn uuid_compare ,
  73 .Fn uuid_equal
  74 and
  75 .Fn uuid_is_nil
  76 functions can be used to test UUIDs.
  77 To convert from the binary representation to the string representation or
  78 vice versa, use
  79 .Fn uuid_to_string
  80 or
  81 .Fn uuid_from_string
  82 respectively.
  83 A 16-bit hash value can be obtained by calling
  84 .Fn uuid_hash .
  85 .Pp
  86 The
  87 .Fn uuid_to_string
  88 function set
  89 .Fa *str
  90 to be a pointer to a buffer sufficiently large to hold the string.
  91 This pointer should be passed to
  92 .Xr free 3
  93 to release the allocated storage when it is no longer needed.
  94 .Pp
  95 The
  96 .Fn uuid_enc_le
  97 and
  98 .Fn uuid_enc_be
  99 functions encode a binary representation of a UUID into an octet stream
 100 in little-endian and big-endian byte-order, respectively.
 101 The destination buffer must be pre-allocated by the caller, and must be
 102 large enough to hold the 16-octet binary UUID.
 103 These routines are not part of the DCE RPC API.
 104 They are provided for convenience.
 105 .Pp
 106 The
 107 .Fn uuid_dec_le
 108 and
 109 .Fn uuid_dec_be
 110 functions decode a UUID from an octet stream in little-endian and
 111 big-endian byte-order, respectively.
 112 These routines are not part of the DCE RPC API.
 113 They are provided for convenience.
 114 .Sh RETURN VALUES
 115 The successful or unsuccessful completion of the function is returned in
 116 the
 117 .Fa status
 118 argument.
 119 Possible values are:
 120 .Bl -tag -width ".Dv uuid_s_invalid_string_uuid"
 121 .It Dv uuid_s_ok
 122 The function completed successfully.
 123 .It Dv uuid_s_bad_version
 124 The UUID does not have a known version.
 125 .It Dv uuid_s_invalid_string_uuid
 126 The string representation of an UUID is not valid.
 127 .It Dv uuid_s_no_memory
 128 The function can not allocate memory to store an UUID representation.
 129 .El
 130 .Sh SEE ALSO
 131 .Xr uuidgen 1 ,
 132 .Xr uuidgen 2
 133 .Sh STANDARDS
 134 The UUID functions conform to the DCE 1.1 RPC specification.
 135 .Sh BUGS
 136 This manpage can be improved.