crypto/heimdal-0.6.3/lib/krb5/krb5_data.3

   1 .\" Copyright (c) 2003 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 .\" $Id: krb5_data.3,v 1.4 2003/04/16 13:58:13 lha Exp $
  33 .\"
  34 .Dd March 20, 2003
  35 .Dt KRB5_DATA 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_data
  39 .Nm krb5_data_zero
  40 .Nm krb5_data_free
  41 .Nm krb5_free_data_contents
  42 .Nm krb5_free_data
  43 .Nm krb5_data_alloc
  44 .Nm krb5_data_realloc
  45 .Nm krb5_data_copy
  46 .Nm krb5_copy_data
  47 .Nd operates on the Kerberos datatype krb5_data.
  48 .Sh LIBRARY
  49 Kerberos 5 Library (libkrb5, -lkrb5)
  50 .Sh SYNOPSIS
  51 .In krb5.h
  52 .Pp
  53 .Li "struct krb5_data;"
  54 .Ft void
  55 .Fn krb5_data_zero "krb5_data *p"
  56 .Ft void
  57 .Fn krb5_data_free "krb5_data *p"
  58 .Ft void
  59 .Fn krb5_free_data_contents "krb5_context context" "krb5_data *p"
  60 .Ft void
  61 .Fn krb5_free_data "krb5_context context" "krb5_data *p"
  62 .Ft krb5_error_code
  63 .Fn krb5_data_alloc "krb5_data *p" "int len"
  64 .Ft krb5_error_code
  65 .Fn krb5_data_realloc "krb5_data *p" "int len"
  66 .Ft krb5_error_code
  67 .Fn krb5_data_copy "krb5_data *p" "const void *data" "size_t len"
  68 .Ft krb5_error_code
  69 .Fn krb5_copy_data "krb5_context context" "const krb5_data *indata" "krb5_data **outdata"
  70 .Sh DESCRIPTION
  71 The
  72 .Li krb5_data
  73 structure holds a data element.
  74 The structure contains two public accessible elements
  75 .Fa length
  76 (the length of data)
  77 and
  78 .Fa data
  79 (the data itself).
  80 The structure must always be initiated and freed by the functions
  81 documented in this manual.
  82 .Pp
  83 .Fn krb5_data_zero
  84 resets the content of
  85 .Fa p .
  86 .Pp
  87 .Fn krb5_data_free
  88 free the data in
  89 .Fa p .
  90 .Pp
  91 .Fn krb5_free_data_contents
  92 works the same way as
  93 .Fa krb5_data_free .
  94 The diffrence is that krb5_free_data_contents is more portable (exists
  95 in MIT api).
  96 .Pp
  97 .Fn krb5_free_data
  98 frees the data in
  99 .Fa p
 100 and
 101 .Fa p
 102 itself .
 103 .Pp
 104 .Fn krb5_data_alloc
 105 allocates
 106 .Fa len
 107 bytes in
 108 .Fa p
 109 Returns 0 or an error.
 110 .Pp
 111 .Fn  krb5_data_realloc
 112 reallocates the length of
 113 .Fa p
 114 to the length in
 115 .Fa len .
 116 Returns 0 or an error.
 117 .Pp
 118 .Fn krb5_data_copy
 119 copies the
 120 .Fa data
 121 that have the length
 122 .Fa len
 123 into
 124 .Fa p .
 125 .Fa p
 126 is not freed so the calling function should make sure the
 127 .Fa p
 128 doesn't contain anything needs to be freed.
 129 Returns 0 or an error.
 130 .Pp
 131 .Fn krb5_copy_data
 132 copies the
 133 .Li krb5_data
 134 in
 135 .Fa indata
 136 to
 137 .Fa outdata .
 138 .Fa outdata
 139 is not freed so the calling function should make sure the
 140 .Fa outdata
 141 doesn't contain anything needs to be freed.
 142 .Fa outdata
 143 should be freed using
 144 .Fn krb5_free_data .
 145 Returns 0 or an error.
 146 .Sh SEE ALSO
 147 .Xr krb5 3 ,
 148 .Xr krb5_storage 3 ,
 149 .Xr kerberos 8