GSS-API Status Codes
Major status codes are encoded in the OM_uint32 as shown in the following figure.
Figure 18 Major-Status Encoding
If a GSS-API routine returns a GSS status code whose upper 16 bits contain a nonzero value, the call has failed. If the calling error field is nonzero, the application's call of the routine was erroneous. The calling errors are listed in Figure 3, Table 3, GSS-API Calling Errors. If the routine error field is nonzero, the routine failed because of a routine-specific error, as listed in Figure 4, Table 4, GSS-API Routine Errors. The bits in the supplementary information field of the status code can be set whether the upper 16 bits indicate a failure or a success. The meaning of individual bits is listed in Figure 5, Table 5, GSS-API Supplementary Information Codes.
GSS-API Major Status Code Values
The following tables list the calling errors that are returned by GSS-API. These errors are specific to a particular language-binding, which is C in this case.
|
The following table lists the GSS-API routine errors, generic errors that are returned by GSS-API functions.
|
The name GSS_S_COMPLETE, which is a zero value, indicates an absence of any API errors or supplementary information bits.
The following table lists the supplementary information values returned by GSS-API functions.
|
For more on status codes, see GSS-API Status Codes.
Displaying Status Codes
The function gss_display_status() translates GSS-API status codes into text format. This format allows the codes to be displayed to a user or put in a text log. gss_display_status() only displays one status code at a time, and some functions can return multiple status conditions. Accordingly, gss_display_status() should be called as part of a loop. When gss_display_status() indicates a non-zero status code, another status code is available for the function to fetch.
Example 33 Displaying Status Codes with gss_display_status()OM_uint32 message_context;
OM_uint32 status_code;
OM_uint32 maj_status;
OM_uint32 min_status;
gss_buffer_desc status_string;
...
message_context = 0;
do {
maj_status = gss_display_status(
&min_status,
status_code,
GSS_C_GSS_CODE,
GSS_C_NO_OID,
&message_context,
&status_string);
fprintf(stderr, "%.*s\n", \
(int)status_string.length, \
(char *)status_string.value);
gss_release_buffer(&min_status, &status_string,);
} while (message_context != 0);
Status Code Macros
The macros, GSS_CALLING_ERROR(), GSS_ROUTINE_ERROR() and GSS_SUPPLEMENTARY_INFO(), take a GSS status code. These macros remove all information except for the relevant field. For example, the GSS_ROUTINE_ERROR() can be applied to a status code to remove the calling errors and supplementary information fields. This operation leaves the routine errors field only. The values delivered by these macros can be directly compared with a GSS_S_xxx symbol of the appropriate type. The macro GSS_ERROR() returns a non-zero value if a status code indicates a calling or routine error, and a zero value otherwise. All macros that are defined by GSS-API evaluate the arguments exactly once.