lib/libgssapi/gss_display_status.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2005 Doug Rabson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" The following commands are required for all man pages.
  28 .Dd January 26, 2010
  29 .Dt GSS_DISPLAY_STATUS 3 PRM
  30 .Os
  31 .Sh NAME
  32 .Nm gss_display_status
  33 .Nd Convert a GSS-API status code to text
  34 .\" This next command is for sections 2 and 3 only.
  35 .\" .Sh LIBRARY
  36 .Sh SYNOPSIS
  37 .In "gssapi/gssapi.h"
  38 .Ft OM_uint32
  39 .Fo gss_display_status
  40 .Fa "OM_uint32 *minor_status"
  41 .Fa "OM_uint32 status_value"
  42 .Fa "int status_type"
  43 .Fa "const gss_OID mech_type"
  44 .Fa "OM_uint32 *message_context"
  45 .Fa "gss_buffer_t status_string"
  46 .Fc
  47 .Sh DESCRIPTION
  48 Allows an application to obtain a textual representation of a GSS-API
  49 status code,
  50 for display to the user or for logging purposes.
  51 Since some status values may indicate multiple conditions,
  52 applications may need to call
  53 .Fn gss_display_status
  54 multiple times,
  55 each call generating a single text string.
  56 The
  57 .Fa message_context
  58 parameter is used by
  59 .Fn gss_display_status
  60 to store state information about which error messages have already
  61 been extracted from a given
  62 .Fa status_value ;
  63 .Fa message_context
  64 must be initialized to zero by the application prior to the first call,
  65 and
  66 .Fn gss_display_status
  67 will return a non-zero value in this parameter if there are further
  68 messages to extract.
  69 .Pp
  70 The
  71 .Fa message_context
  72 parameter contains all state information required by
  73 .Fn gss_display_status
  74 in order to extract further messages from the
  75 .Fa status_value ;
  76 even when a non-zero value is returned in this parameter,
  77 the application is not required to call
  78 .Fn gss_display_status
  79 again unless subsequent messages are desired.
  80 The following code extracts all messages from a given status code and prints them to stderr:
  81 .Bd -literal
  82 OM_uint32 message_context;
  83 OM_uint32 status_code;
  84 OM_uint32 maj_status;
  85 OM_uint32 min_status;
  86 gss_buffer_desc status_string;
  87
  88        ...
  89
  90 message_context = 0;
  91
  92 do {
  93
  94   maj_status = gss_display_status (
  95                   &min_status,
  96                   status_code,
  97                   GSS_C_GSS_CODE,
  98                   GSS_C_NO_OID,
  99                   &message_context,
 100                   &status_string)
 101
 102   fprintf(stderr,
 103           "%.*s\\n",
 104          (int)status_string.length,
 105          (char *)status_string.value);
 106
 107   gss_release_buffer(&min_status, &status_string);
 108
 109 } while (message_context != 0);
 110 .Ed
 111 .Sh PARAMETERS
 112 .Bl -tag -width ".It minor_status"
 113 .It minor_status
 114 Mechanism specific status code.
 115 .It status_value
 116 Status value to be converted
 117 .It status_type
 118 .Bl -tag -width ".It GSS_C_MECH_CODE"
 119 .It GSS_C_GSS_CODE
 120 .Fa status_value
 121 is a GSS status code
 122 .It GSS_C_MECH_CODE
 123 .Fa status_value
 124 is a mechanism status code
 125 .El
 126 .It mech_type
 127 Underlying mechanism (used to interpret a minor status value).
 128 Supply
 129 .Dv GSS_C_NO_OID
 130 to obtain the system default.
 131 .It message_context
 132 Should be initialized to zero by the application prior to the first
 133 call.
 134 On return from
 135 .Fn gss_display_status ,
 136 a non-zero status_value parameter indicates that additional messages
 137 may be extracted from the status code via subsequent calls to
 138 .Fn gss_display_status ,
 139 passing the same
 140 .Fa status_value ,
 141 .Fa status_type ,
 142 .Fa mech_type ,
 143 and
 144 .Fa message_context
 145 parameters.
 146 .It status_string
 147 Textual interpretation of the
 148 .Fa status_value .
 149 Storage associated with this parameter must be freed by the
 150 application after use with a call to
 151 .Fn gss_release_buffer .
 152 .El
 153 .Sh RETURN VALUES
 154 .Bl -tag -width ".It GSS_S_BAD_STATUS"
 155 .It GSS_S_COMPLETE
 156 Successful completion
 157 .It GSS_S_BAD_MECH
 158 Indicates that translation in accordance with an unsupported mechanism
 159 type was requested
 160 .It GSS_S_BAD_STATUS
 161 The status value was not recognized, or the status type was neither
 162 .Dv GSS_C_GSS_CODE
 163 nor
 164 .Dv GSS_C_MECH_CODE .
 165 .El
 166 .Sh SEE ALSO
 167 .Xr gss_release_buffer 3
 168 .Sh STANDARDS
 169 .Bl -tag -width ".It RFC 2743"
 170 .It RFC 2743
 171 Generic Security Service Application Program Interface Version 2, Update 1
 172 .It RFC 2744
 173 Generic Security Service API Version 2 : C-bindings
 174 .El
 175 .Sh HISTORY
 176 The
 177 .Nm
 178 function first appeared in
 179 .Fx 7.0 .
 180 .Sh AUTHORS
 181 John Wray, Iris Associates
 182 .Sh COPYRIGHT
 183 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 184 .Pp
 185 This document and translations of it may be copied and furnished to
 186 others, and derivative works that comment on or otherwise explain it
 187 or assist in its implementation may be prepared, copied, published
 188 and distributed, in whole or in part, without restriction of any
 189 kind, provided that the above copyright notice and this paragraph are
 190 included on all such copies and derivative works.  However, this
 191 document itself may not be modified in any way, such as by removing
 192 the copyright notice or references to the Internet Society or other
 193 Internet organizations, except as needed for the purpose of
 194 developing Internet standards in which case the procedures for
 195 copyrights defined in the Internet Standards process must be
 196 followed, or as required to translate it into languages other than
 197 English.
 198 .Pp
 199 The limited permissions granted above are perpetual and will not be
 200 revoked by the Internet Society or its successors or assigns.
 201 .Pp
 202 This document and the information contained herein is provided on an
 203 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 204 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 205 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 206 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 207 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.