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 August 13, 2008
  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_enc_le
  88 and
  89 .Fn uuid_enc_be
  90 functions encode a binary representation of a UUID into an octet stream
  91 in little-endian and big-endian byte-order, respectively.
  92 The destination buffer must be pre-allocated by the caller, and must be
  93 large enough to hold the 16-octet binary UUID.
  94 These routines are not part of the DCE RPC API.
  95 They are provided for convenience.
  96 .Pp
  97 The
  98 .Fn uuid_dec_le
  99 and
 100 .Fn uuid_dec_be
 101 functions decode a UUID from an octet stream in little-endian and
 102 big-endian byte-order, respectively.
 103 These routines are not part of the DCE RPC API.
 104 They are provided for convenience.
 105 .Sh RETURN VALUES
 106 The successful or unsuccessful completion of the function is returned in
 107 the
 108 .Fa status
 109 argument.
 110 Possible values are:
 111 .Pp
 112 .Bl -tag -width ".Dv uuid_s_invalid_string_uuid"
 113 .It Dv uuid_s_ok
 114 The function completed successfully.
 115 .It Dv uuid_s_bad_version
 116 The UUID does not have a known version.
 117 .It Dv uuid_s_invalid_string_uuid
 118 The string representation of an UUID is not valid.
 119 .It Dv uuid_s_no_memory
 120 The meaning of the code escaped the writers mind.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr uuidgen 1 ,
 124 .Xr uuidgen 2
 125 .Sh STANDARDS
 126 The UUID functions conform to the DCE 1.1 RPC specification.
 127 .Sh BUGS
 128 This manpage can be improved.