The routine documentation also uses the name GSS_S_COMPLETE, which is a zero value, to indicate an absence of any API errors or supplementary information bits.

The following table lists the supplementary information values returned by GSS-API functions.

Table B-4 Supplementary Information Codes

For more on status codes, see "Status Codes".

Displaying Status Codes

The function gss_display_status() translates GSS-API status codes into text format, allowing them to be displayed to a user or put in a text log. Because gss_display_status() only displays one status code at a time, and some functions can return multiple status conditions, it should be invoked as part of a loop. As long as gss_display_status() indicates a non-zero status code (in Example B-1, the value returned in the message_context parameter), another status code is available for the function to fetch.

Example B-1 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() are provided, each of which takes a GSS status code and removes all but the relevant field. For example, the value obtained by applying GSS_ROUTINE_ERROR() to a status code removes the calling errors and supplementary information fields, leaving only the routine errors field. The values delivered by these macros can be directly compared with a GSS_S_xxx symbol of the appropriate type. The macro GSS_ERROR() is also provided, which when applied to a GSS-API status code returns a non-zero value if the status code indicated a calling or routine error, and a zero value otherwise. All macros defined by the GSS-API evaluate their argument(s) exactly once.

GSS-API Data Types and Values

This section covers various types of GSS-API data types and values. Certain data types that are opaque to the user, such as gss_cred_id_t or gss_name_t, are not covered here, since there is no advantage to knowing their structure. This section explains the following:

• "Basic GSS-API Data Types" -- Shows the definitions of the OM_uint32, gss_buffer_desc, gss_OID_desc, gss_OID_set_desc_struct, and gss_channel_bindings_struct data types.

• "Name Types" -- Shows the various name formats recognized by the GSS-API for specifying names.

• "Address Types for Channel Bindings" -- Shows the various values that may be used as the initiator_addrtype and acceptor_addrtype fields of the gss_channel_bindings_t structure.

Basic GSS-API Data Types

These are some of the data types used by the GSS-API.

OM_uint32

The OM_uint32 is a platform-independent 32-bit unsigned integer.

gss_buffer_desc

This is the definition of the gss_buffer_desc and the gss_buffer_t pointer:

typedef struct gss_buffer_desc_struct { size_t length; void *value; } gss_buffer_desc, *gss_buffer_t;

gss_OID_desc

This is the definition of the gss_OID_desc and the gss_OID pointer:

typedef struct gss_OID_desc_struct { OM_uint32 length; void*elements; } gss_OID_desc, *gss_OID;

gss_OID_set_desc

This is the definition of the gss_OID_set_desc and the gss_OID_set pointer:

typedef struct gss_OID_set_desc_struct { size_t count; gss_OID elements; } gss_OID_set_desc, *gss_OID_set;

gss_channel_bindings_struct

This is the definition of the gss_channel_bindings_struct structure and the gss_channel_bindings_t pointer:

typedef struct gss_channel_bindings_struct { OM_uint32 initiator_addrtype; gss_buffer_desc initiator_address; OM_uint32 acceptor_addrtype; gss_buffer_desc acceptor_address; gss_buffer_desc application_data; } *gss_channel_bindings_t;

Name Types

A name type indicates the format of the name with which it is associated. (See "Names" and "OIDs" for more on names and name types.) The GSS-API supports the following name types, which are all gss_OID types:

Table B-5 Name Types

Address Types for Channel Bindings

Table B-6 shows the possible values for the initiator_addrtype and acceptor_addrtype fields of the gss_channel_bindings_struct structure. These fields indicate the format that a name can take (for example, ARPAnet IMP address format or AppleTalk address format). Channel bindings are discussed in "Channel Bindings".

Table B-6 Channel Binding Address Types