crypto/dist/heimdal/lib/krb5/krb5_data.3

   1 .\" Copyright (c) 2003 - 2005, 2007 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   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 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Heimdal: krb5_data.3 20040 2007-01-23 20:35:12Z lha $
  33 .\" $NetBSD$
  34 .\"
  35 .Dd Jan 23, 2007
  36 .Dt KRB5_DATA 3
  37 .Os
  38 .Sh NAME
  39 .Nm krb5_data ,
  40 .Nm krb5_data_zero ,
  41 .Nm krb5_data_free ,
  42 .Nm krb5_free_data_contents ,
  43 .Nm krb5_free_data ,
  44 .Nm krb5_data_alloc ,
  45 .Nm krb5_data_realloc ,
  46 .Nm krb5_data_copy ,
  47 .Nm krb5_copy_data ,
  48 .Nm krb5_data_cmp
  49 .Nd operates on the Kerberos datatype krb5_data
  50 .Sh LIBRARY
  51 Kerberos 5 Library (libkrb5, -lkrb5)
  52 .Sh SYNOPSIS
  53 .In krb5/krb5.h
  54 .Pp
  55 .Li "struct krb5_data;"
  56 .Ft void
  57 .Fn krb5_data_zero "krb5_data *p"
  58 .Ft void
  59 .Fn krb5_data_free "krb5_data *p"
  60 .Ft void
  61 .Fn krb5_free_data_contents "krb5_context context" "krb5_data *p"
  62 .Ft void
  63 .Fn krb5_free_data "krb5_context context" "krb5_data *p"
  64 .Ft krb5_error_code
  65 .Fn krb5_data_alloc "krb5_data *p" "int len"
  66 .Ft krb5_error_code
  67 .Fn krb5_data_realloc "krb5_data *p" "int len"
  68 .Ft krb5_error_code
  69 .Fn krb5_data_copy "krb5_data *p" "const void *data" "size_t len"
  70 .Ft krb5_error_code
  71 .Fn krb5_copy_data "krb5_context context" "const krb5_data *indata" "krb5_data **outdata"
  72 .Ft krb5_error_code
  73 .Fn krb5_data_cmp "const krb5_data *data1" "const krb5_data *data2"
  74 .Sh DESCRIPTION
  75 The
  76 .Li krb5_data
  77 structure holds a data element.
  78 The structure contains two public accessible elements
  79 .Fa length
  80 (the length of data)
  81 and
  82 .Fa data
  83 (the data itself).
  84 The structure must always be initiated and freed by the functions
  85 documented in this manual.
  86 .Pp
  87 .Fn krb5_data_zero
  88 resets the content of
  89 .Fa p .
  90 .Pp
  91 .Fn krb5_data_free
  92 free the data in
  93 .Fa p
  94 and reset the content of the structure with
  95 .Fn krb5_data_zero .
  96 .Pp
  97 .Fn krb5_free_data_contents
  98 works the same way as
  99 .Fa krb5_data_free .
 100 The diffrence is that krb5_free_data_contents is more portable (exists
 101 in MIT api).
 102 .Pp
 103 .Fn krb5_free_data
 104 frees the data in
 105 .Fa p
 106 and
 107 .Fa p
 108 itself.
 109 .Pp
 110 .Fn krb5_data_alloc
 111 allocates
 112 .Fa len
 113 bytes in
 114 .Fa p .
 115 Returns 0 or an error.
 116 .Pp
 117 .Fn  krb5_data_realloc
 118 reallocates the length of
 119 .Fa p
 120 to the length in
 121 .Fa len .
 122 Returns 0 or an error.
 123 .Pp
 124 .Fn krb5_data_copy
 125 copies the
 126 .Fa data
 127 that have the length
 128 .Fa len
 129 into
 130 .Fa p .
 131 .Fa p
 132 is not freed so the calling function should make sure the
 133 .Fa p
 134 doesn't contain anything needs to be freed.
 135 Returns 0 or an error.
 136 .Pp
 137 .Fn krb5_copy_data
 138 copies the
 139 .Li krb5_data
 140 in
 141 .Fa indata
 142 to
 143 .Fa outdata .
 144 .Fa outdata
 145 is not freed so the calling function should make sure the
 146 .Fa outdata
 147 doesn't contain anything needs to be freed.
 148 .Fa outdata
 149 should be freed using
 150 .Fn krb5_free_data .
 151 Returns 0 or an error.
 152 .Pp
 153 .Fn krb5_data_cmp
 154 will compare two data object and check if they are the same in a
 155 simular way as memcmp does it.  The return value can be used for
 156 sorting.
 157 .Sh SEE ALSO
 158 .Xr krb5 3 ,
 159 .Xr krb5_storage 3 ,
 160 .Xr kerberos 8