'\" te
.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
.TH gss_display_status 3GSS "22 Aug 2011" "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
\fIDeveloper\&'s Guide to Oracle Solaris 11 Security\fR