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.3 2007/06/17 07:47:32 dillon Exp $
  28 .\"
  29 .Dd January 3, 2005
  30 .Dt UUID 3
  31 .Os
  32 .Sh NAME
  33 .Nm uuid_compare , uuid_create , uuid_create_nil , uuid_equal ,
  34 .Nm uuid_from_string , uuid_hash , uuid_is_nil , uuid_to_string
  35 .Nd DCE 1.1 compliant UUID functions
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In uuid.h
  40 .Ft int32_t
  41 .Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
  42 .Ft void
  43 .Fn uuid_create "uuid_t *uuid" "uint32_t *status"
  44 .Ft void
  45 .Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status"
  46 .Ft int32_t
  47 .Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status"
  48 .Ft void
  49 .Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status"
  50 .Ft uint16_t
  51 .Fn uuid_hash "const uuid_t *uuid" "uint32_t *status"
  52 .Ft int32_t
  53 .Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status"
  54 .Ft void
  55 .Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status"
  56 .Ft void
  57 .Fn uuid_addr_lookup "const uuid_t *u" "char **strp" "uint32_t *status"
  58 .Ft void
  59 .Fn uuid_name_lookup "uuid_t *u" "const char *str" "uint32_t *status"
  60 .Sh DESCRIPTION
  61 The family of DCE 1.1 compliant UUID functions allow applications to operate
  62 on universally unique identifiers, or UUIDs.
  63 The
  64 .Fn uuid_create
  65 and
  66 .Fn uuid_create_nil
  67 functions create UUIDs.
  68 The
  69 .Fn uuid_compare ,
  70 .Fn uuid_equal
  71 and
  72 .Fn uuid_is_nil
  73 functions can be used to test UUIDs.
  74 To convert from the binary representation to the string representation or
  75 vice versa, use
  76 .Fn uuid_to_string
  77 or
  78 .Fn uuid_from_string
  79 respectively.
  80 A 16-bit hash value can be obtained by calling
  81 .Fn uuid_hash .
  82 .Pp
  83 String equivalents to UUIDs may be available.  The
  84 .Fn uuid_addr_lookup
  85 function will lookup the symbolic name given a UUID.
  86 The variable *strp should be initialized to NULL.
  87 Successive calls to
  88 .Fn uuid_addr_lookup
  89 will free the previous contents prior to doing the lookup.  The last
  90 string may be freed by calling the function with a NULL UUID.
  91 If a lookup fails, *strp will be set to NULL and *status
  92 (if status is not NULL) will be set to uuid_s_not_found.  Otherwise
  93 *strp will be assigned to the symbolic name and *status will be
  94 set to uuid_s_ok.
  95 .Pp
  96 The
  97 .Fn uuid_name_lookup
  98 function will lookup a UUID given a symbolic name.
  99 The contents of the uuid will be zerod out if a lookup fails.
 100 .Pp
 101 The
 102 .Fn uuid_reset_lookup
 103 function will clear its in-memory cache of UUID<->NAME conversions.  The
 104 next lookup will reload the cache.
 105 .Sh FILES
 106 .TP 3n
 107 \fI/etc/defaults/uuids\fR
 108 A list of UUIDs and their symbolic names provided by the OS vendor
 109 .Pp
 110 .TP 3n
 111 \fI/etc/uuids\fR
 112 A list of UUIDs and their symbolic names provided by the system administrator
 113 .Sh RETURN VALUES
 114 The successful or unsuccessful completion of the function is returned in
 115 the
 116 .Fa status
 117 argument.
 118 Possible values are:
 119 .Pp
 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 meaning of the code escaped the writers mind.
 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.