Function Status
Evaluate return values that most GSS-API functions use to indicate the outcome of an operation.
Overview
The functions of the GSS-API return two status codes. The major status code, delivered as the function’s return value, provides a mechanism-independent status output. A value of GSS_S_COMPLETE typically indicates success, but the code is actually composed of several fields that enable communicating a more nuanced result. Always check the major status code to determine if an operation succeeds.
The minor status code provides additional information, often mechanism-specific, when an operation fails. This result returns using the OM_uint32 pointer given as the function’s first argument. Examine this value to further debug a problem. For example, many functions allocate memory as a side effect of their main task. If memory allocation fails, the entire operation fails. But while the major status indicates a generic problem, a minor status of ENOMEM indicates that failed memory allocation is the exact culprit.
Three bitfields bundled together make up major status codes in a single OM_uint32 value. These fields are:
- The calling error
A generic GSS-API error in the most significant 8 bits.
- The routine error
An error specific to the routine in the next 8 bits.
- Supplementary Information
Additional information about the error in the lower 16 bits.
When a function successfully runs to completion, it returns zero for all of these fields. As a convenience, you can compare the result directly with the status code GSS_S_COMPLETE to test for this condition.
[Image]
For any other result, use one of the available extraction macros (such as GSS_CALLING_ERROR) to obtain a value that you compare against one of the known error codes. For example, you can test for a failure to read one of the function inputs as follows:
OM_uint32 major = <# Some GSS call #>
if (GSS_CALLING_ERROR(major) == GSS_S_CALL_INACCESSIBLE_READ) {
// Handle the error
}Use the gss_display_status(_:_:_:_:_:_:) function to retrieve a human readable string corresponding to a given status result.
Topics
Status and Error Creation
OM_uint32OM_uint64gss_uint32gss_status_id_tGSS_C_MECH_CODEGSS_C_GSS_CODEGSS_S_COMPLETEgss_display_status(_:_:_:_:_:_:)GSSCreateError(_:_:_:)
Calling Errors
Routine Errors
GSS_S_BAD_MECHGSS_S_BAD_NAMEGSS_S_BAD_NAMETYPEGSS_S_BAD_MICGSS_S_BAD_SIGGSS_S_BAD_STATUSGSS_S_BAD_BINDINGSGSS_S_NO_CREDGSS_S_NO_CONTEXTGSS_S_DEFECTIVE_TOKENGSS_S_DEFECTIVE_CREDENTIALGSS_S_CREDENTIALS_EXPIREDGSS_S_CONTEXT_EXPIREDGSS_S_FAILUREGSS_S_BAD_QOPGSS_S_UNAUTHORIZEDGSS_S_UNAVAILABLEGSS_S_DUPLICATE_ELEMENTGSS_S_NAME_NOT_MNGSS_S_BAD_MECH_ATTRGSS_S_CRED_UNAVAIL