'\" te

.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

.TH gss_display_status 3GSS "22 Aug 2011" "SunOS 5.12" "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