usr/src/man/man3gss/gss_display_status.3gss

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GSS_DISPLAY_STATUS 3GSS "Jan 14, 2003"
   7 .SH NAME
   8 gss_display_status \- convert a GSS-API status code to text
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_display_status\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBOM_uint32\fR \fIstatus value\fR,\fBint\fR \fIstatus type\fR,
  17      \fBconst gss_OID\fR \fImech_type\fR, \fBOM_uint32 *\fR\fImessage_context\fR,
  18      \fBgss_buffer_t\fR \fIstatus string\fR);
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBgss_display_status()\fR function enables an application to obtain a
  25 textual representation of a \fBGSS-API\fR status code for display to the user
  26 or for logging purposes.  Because some status values may indicate multiple
  27 conditions, applications may need to call \fBgss_display_status()\fR multiple
  28 times, with each call generating a single text string.
  29 .sp
  30 .LP
  31 The \fImessage_context\fR parameter is used by \fBgss_acquire_cred()\fR to
  32 store state information on error messages that are extracted from a given
  33 \fIstatus_value\fR. The \fImessage_context\fR parameter must be initialized to
  34 0 by the application prior to the first call, and \fBgss_display_status()\fR
  35 will return a non-zero value in this parameter if there are further messages to
  36 extract.
  37 .sp
  38 .LP
  39 The \fImessage_context\fR parameter contains all state information required  by
  40 \fBgss_display_status()\fR to extract further messages from the
  41 \fIstatus_value\fR.  If a non-zero value is returned in this parameter, the
  42 application is not required to call \fBgss_display_status()\fR again unless
  43 subsequent messages are desired.
  44 .SH PARAMETERS
  45 .sp
  46 .LP
  47 The parameter descriptions for \fBgss_display_status()\fR follow:
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIminor_status\fR\fR
  52 .ad
  53 .RS 19n
  54 Status code returned by the underlying mechanism.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fIstatus_value\fR\fR
  61 .ad
  62 .RS 19n
  63 Status value to be converted.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIstatus_type\fR\fR
  70 .ad
  71 .RS 19n
  72 If the value is \fBGSS_C_GSS_CODE\fR, \fIstatus_value\fR is a \fBGSS-API\fR
  73 status code. If the value is \fBGSS_C_MECH_CODE\fR, then \fIstatus_value\fR is
  74 a mechanism status code.
  75 .RE
  76
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fImech_type\fR\fR
  81 .ad
  82 .RS 19n
  83 Underlying mechanism that is used to interpret a minor status value. Supply
  84 \fBGSS_C_NO_OID\fR to obtain the system default.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fImessage_context\fR\fR
  91 .ad
  92 .RS 19n
  93 Should be initialized to zero prior to the first call. On return from
  94 \fBgss_display_status()\fR, a non-zero \fIstatus_value\fR parameter indicates
  95 that additional messages may be extracted from the status code by means of
  96 subsequent calls to \fBgss_display_status()\fR, passing the same
  97 \fIstatus_value\fR, \fIstatus_type\fR, \fImech_type\fR, and
  98 \fImessage_context\fRparameters.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fIstatus_string\fR\fR
 105 .ad
 106 .RS 19n
 107 Textual representation of the \fIstatus_value\fR. Storage associated with this
 108 parameter must be freed by the application after use with a call to
 109 \fBgss_release_buffer\fR(3GSS).
 110 .RE
 111
 112 .SH ERRORS
 113 .sp
 114 .LP
 115 The \fBgss_display_status()\fR function may return the following status codes:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBGSS_S_COMPLETE\fR\fR
 120 .ad
 121 .RS 20n
 122 Successful completion.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBGSS_S_BAD_MECH\fR\fR
 129 .ad
 130 .RS 20n
 131 Indicates that translation in accordance with an unsupported mechanism type was
 132 requested.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBGSS_S_BAD_STATUS\fR\fR
 139 .ad
 140 .RS 20n
 141 The status value was not recognized, or the status type was neither
 142 \fBGSS_C_GSS_CODE\fR nor \fBGSS_C_MECH_CODE\fR.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBGSS_S_FAILURE\fR\fR
 149 .ad
 150 .RS 20n
 151 The underlying mechanism detected an error for which no specific \fBGSS\fR
 152 status code is defined.  The mechanism-specific status code reported by means
 153 of the \fIminor_status\fR parameter details the error condition.
 154 .RE
 155
 156 .SH ATTRIBUTES
 157 .sp
 158 .LP
 159 See \fBattributes\fR(5)  for descriptions of the following attributes:
 160 .sp
 161
 162 .sp
 163 .TS
 164 box;
 165 c | c
 166 l | l .
 167 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 168 _
 169 MT-Level        Safe
 170 .TE
 171
 172 .SH SEE ALSO
 173 .sp
 174 .LP
 175 \fBgss_acquire_cred\fR(3GSS), \fBgss_release_buffer\fR(3GSS),
 176 \fBattributes\fR(5)
 177 .sp
 178 .LP
 179 \fISolaris Security for Developers Guide\fR