'\" te
.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH gss_display_status 3GSS "14 Jan 2003" "SunOS 5.11" "Generic Security Services API Library Functions"
.SH NAME
gss_display_status \- convert a GSS-API status code to text
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ] 
#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_display_status\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
     \fBOM_uint32\fR \fIstatus value\fR,\fBint\fR \fIstatus type\fR,
     \fBconst gss_OID\fR \fImech_type\fR, \fBOM_uint32 *\fR\fImessage_context\fR,
     \fBgss_buffer_t\fR \fIstatus string\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgss_display_status()\fR function enables an application to obtain a
textual representation of a \fBGSS-API\fR status code for display to the user
or for logging purposes.  Because some status values may indicate multiple
conditions, applications may need to call \fBgss_display_status()\fR multiple
times, with each call generating a single text string.
.sp
.LP
The \fImessage_context\fR parameter is used by \fBgss_acquire_cred()\fR to
store state information on error messages that are extracted from a given
\fIstatus_value\fR. The \fImessage_context\fR parameter must be initialized to
0 by the application prior to the first call, and \fBgss_display_status()\fR
will return a non-zero value in this parameter if there are further messages to
extract.
.sp
.LP
The \fImessage_context\fR parameter contains all state information required  by
\fBgss_display_status()\fR to extract further messages from the
\fIstatus_value\fR.  If a non-zero value is returned in this parameter, the
application is not required to call \fBgss_display_status()\fR again unless
subsequent messages are desired.
.SH PARAMETERS
.sp
.LP
The parameter descriptions for \fBgss_display_status()\fR follow:
.sp
.ne 2
.mk
.na
\fB\fIminor_status\fR\fR
.ad
.RS 19n
.rt  
Status code returned by the underlying mechanism.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstatus_value\fR\fR
.ad
.RS 19n
.rt  
Status value to be converted.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstatus_type\fR\fR
.ad
.RS 19n
.rt  
If the value is \fBGSS_C_GSS_CODE\fR, \fIstatus_value\fR is a \fBGSS-API\fR
status code. If the value is \fBGSS_C_MECH_CODE\fR, then \fIstatus_value\fR is
a mechanism status code.
.RE

.sp
.ne 2
.mk
.na
\fB\fImech_type\fR\fR
.ad
.RS 19n
.rt  
Underlying mechanism that is used to interpret a minor status value. Supply
\fBGSS_C_NO_OID\fR to obtain the system default.
.RE

.sp
.ne 2
.mk
.na
\fB\fImessage_context\fR\fR
.ad
.RS 19n
.rt  
Should be initialized to zero prior to the first call. On return from
\fBgss_display_status()\fR, a non-zero \fIstatus_value\fR parameter indicates
that additional messages may be extracted from the status code by means of
subsequent calls to \fBgss_display_status()\fR, passing the same
\fIstatus_value\fR, \fIstatus_type\fR, \fImech_type\fR, and
\fImessage_context\fRparameters.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstatus_string\fR\fR
.ad
.RS 19n
.rt  
Textual representation of the \fIstatus_value\fR. Storage associated with this
parameter must be freed by the application after use with a call to
\fBgss_release_buffer\fR(3GSS).
.RE

.SH ERRORS
.sp
.LP
The \fBgss_display_status()\fR function may return the following status codes:
.sp
.ne 2
.mk
.na
\fB\fBGSS_S_COMPLETE\fR\fR
.ad
.RS 20n
.rt  
Successful completion.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_MECH\fR\fR
.ad
.RS 20n
.rt  
Indicates that translation in accordance with an unsupported mechanism type was
requested.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_BAD_STATUS\fR\fR
.ad
.RS 20n
.rt  
The status value was not recognized, or the status type was neither
\fBGSS_C_GSS_CODE\fR nor \fBGSS_C_MECH_CODE\fR.
.RE

.sp
.ne 2
.mk
.na
\fB\fBGSS_S_FAILURE\fR\fR
.ad
.RS 20n
.rt  
The underlying mechanism detected an error for which no specific \fBGSS\fR
status code is defined.  The mechanism-specific status code reported by means
of the \fIminor_status\fR parameter details the error condition.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5)  for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBgss_acquire_cred\fR(3GSS), \fBgss_release_buffer\fR(3GSS),
\fBattributes\fR(5)
.sp
.LP
\fISolaris Security for Developers Guide\fR