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: src/lib/libc/uuid/uuid.3,v 1.6 2005/11/24 07:04:20 ru Exp $
  27 .\" $DragonFly: src/lib/libc/uuid/uuid.3,v 1.8 2008/08/21 21:41:55 swildner Exp $
  28 .\"
  29 .Dd June 17, 2007
  30 .Dt UUID 3
  31 .Os
  32 .Sh NAME
  33 .Nm uuid_addr_lookup ,
  34 .Nm uuid_compare ,
  35 .Nm uuid_create ,
  36 .Nm uuid_create_nil ,
  37 .Nm uuid_equal ,
  38 .Nm uuid_from_string ,
  39 .Nm uuid_hash ,
  40 .Nm uuid_is_nil ,
  41 .Nm uuid_name_lookup ,
  42 .Nm uuid_reset_lookup ,
  43 .Nm uuid_to_string
  44 .Nd DCE 1.1 compliant UUID functions
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In uuid.h
  49 .Ft void
  50 .Fn uuid_addr_lookup "const uuid_t *u" "char **strp" "uint32_t *status"
  51 .Ft int32_t
  52 .Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
  53 .Ft void
  54 .Fn uuid_create "uuid_t *uuid" "uint32_t *status"
  55 .Ft void
  56 .Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status"
  57 .Ft int32_t
  58 .Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
  59 .Ft void
  60 .Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status"
  61 .Ft uint16_t
  62 .Fn uuid_hash "const uuid_t *uuid" "uint32_t *status"
  63 .Ft int32_t
  64 .Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status"
  65 .Ft void
  66 .Fn uuid_name_lookup "uuid_t *u" "const char *str" "uint32_t *status"
  67 .Ft void
  68 .Fn uuid_reset_lookup "void"
  69 .Ft void
  70 .Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status"
  71 .Sh DESCRIPTION
  72 The family of DCE 1.1 compliant UUID functions allow applications to operate
  73 on universally unique identifiers, or UUIDs.
  74 The
  75 .Fn uuid_create
  76 and
  77 .Fn uuid_create_nil
  78 functions create UUIDs.
  79 The
  80 .Fn uuid_compare ,
  81 .Fn uuid_equal
  82 and
  83 .Fn uuid_is_nil
  84 functions can be used to test UUIDs.
  85 To convert from the binary representation to the string representation or
  86 vice versa, use
  87 .Fn uuid_to_string
  88 or
  89 .Fn uuid_from_string
  90 respectively.
  91 A 16-bit hash value can be obtained by calling
  92 .Fn uuid_hash .
  93 .Pp
  94 String equivalents to UUIDs may be available.
  95 The
  96 .Fn uuid_addr_lookup
  97 function will lookup the symbolic name given a UUID.
  98 The variable
  99 .Fa *strp
 100 should be initialized to
 101 .Dv NULL .
 102 Successive calls to
 103 .Fn uuid_addr_lookup
 104 will free the previous contents prior to doing the lookup.
 105 The last string may be freed by calling the function with a
 106 .Dv NULL
 107 UUID.
 108 If a lookup fails,
 109 .Fa *strp
 110 will be set to
 111 .Dv NULL
 112 and
 113 .Fa *status
 114 (if
 115 .Fa status
 116 is not
 117 .Dv NULL )
 118 will be set to
 119 .Dv uuid_s_not_found .
 120 Otherwise
 121 .Fa *strp
 122 will be assigned to the symbolic name and
 123 .Fa *status
 124 will be set to
 125 .Dv uuid_s_ok .
 126 .Pp
 127 The
 128 .Fn uuid_name_lookup
 129 function will lookup a UUID given a symbolic name.
 130 The contents of the uuid will be zeroed out if a lookup fails.
 131 .Pp
 132 The
 133 .Fn uuid_reset_lookup
 134 function will clear its in-memory cache of UUID<->NAME conversions.
 135 The next lookup will reload the cache.
 136 .Sh FILES
 137 .Bl -tag -width ".Pa /etc/defaults/uuids"
 138 .It Pa /etc/defaults/uuids
 139 A list of UUIDs and their symbolic names provided by the OS vendor.
 140 .It Pa /etc/uuids
 141 A list of UUIDs and their symbolic names provided by the system administrator.
 142 .El
 143 .Sh RETURN VALUES
 144 The successful or unsuccessful completion of the function is returned in the
 145 .Fa status
 146 argument.
 147 Possible values are:
 148 .Bl -tag -width ".Dv uuid_s_invalid_string_uuid"
 149 .It Dv uuid_s_ok
 150 The function completed successfully.
 151 .It Dv uuid_s_bad_version
 152 The UUID does not have a known version.
 153 .It Dv uuid_s_invalid_string_uuid
 154 The string representation of an UUID is not valid.
 155 .It Dv uuid_s_no_memory
 156 The meaning of the code escaped the writers mind.
 157 .It Dv uuid_s_not_found
 158 A UUID lookup failed.
 159 .El
 160 .Sh SEE ALSO
 161 .Xr uuidgen 1 ,
 162 .Xr uuidgen 2 ,
 163 .Xr uuids 5
 164 .Sh STANDARDS
 165 The UUID functions conform to the DCE 1.1 RPC specification.