xref: /illumos-gate/usr/src/man/man3gss/gss_display_status.3gss (revision 5a469116729183a46e77dc0620955bbde58d93f7)
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]
GSS_DISPLAY_STATUS 3GSS "June 20, 2021"
NAME
gss_display_status - convert a GSS-API status code to text
SYNOPSIS
cc [ flag... ] file... -lgss [ library... ]
#include <gssapi/gssapi.h>

OM_uint32 gss_display_status(OM_uint32 *minor_status,
 OM_uint32 status value,int status type,
 const gss_OID mech_type, OM_uint32 *message_context,
 gss_buffer_t status string);
DESCRIPTION
The gss_display_status() function enables an application to obtain a textual representation of a GSS-API status code for display to the user or for logging purposes. Because some status values may indicate multiple conditions, applications may need to call gss_display_status() multiple times, with each call generating a single text string.

The message_context parameter is used by gss_acquire_cred() to store state information on error messages that are extracted from a given status_value. The message_context parameter must be initialized to 0 by the application prior to the first call, and gss_display_status() will return a non-zero value in this parameter if there are further messages to extract.

The message_context parameter contains all state information required by gss_display_status() to extract further messages from the status_value. If a non-zero value is returned in this parameter, the application is not required to call gss_display_status() again unless subsequent messages are desired.

PARAMETERS
The parameter descriptions for gss_display_status() follow: minor_status

Status code returned by the underlying mechanism.

status_value

Status value to be converted.

status_type

If the value is GSS_C_GSS_CODE, status_value is a GSS-API status code. If the value is GSS_C_MECH_CODE, then status_value is a mechanism status code.

mech_type

Underlying mechanism that is used to interpret a minor status value. Supply GSS_C_NO_OID to obtain the system default.

message_context

Should be initialized to zero prior to the first call. On return from gss_display_status(), a non-zero status_value parameter indicates that additional messages may be extracted from the status code by means of subsequent calls to gss_display_status(), passing the same status_value, status_type, mech_type, and message_context parameters.

status_string

Textual representation of the status_value. Storage associated with this parameter must be freed by the application after use with a call to gss_release_buffer(3GSS).

ERRORS
The gss_display_status() function may return the following status codes: GSS_S_COMPLETE

Successful completion.

GSS_S_BAD_MECH

Indicates that translation in accordance with an unsupported mechanism type was requested.

GSS_S_BAD_STATUS

The status value was not recognized, or the status type was neither GSS_C_GSS_CODE nor GSS_C_MECH_CODE.

GSS_S_FAILURE

The underlying mechanism detected an error for which no specific GSS status code is defined. The mechanism-specific status code reported by means of the minor_status parameter details the error condition.

ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE ATTRIBUTE VALUE
MT-Level Safe
SEE ALSO
gss_acquire_cred(3GSS), gss_release_buffer(3GSS), attributes(5)

Solaris Security for Developers Guide