|
1 '\" te |
|
2 .\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved. |
|
3 .TH gss_display_status 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions" |
|
4 .SH NAME |
|
5 gss_display_status \- convert a GSS-API status code to text |
|
6 .SH SYNOPSIS |
|
7 .LP |
|
8 .nf |
|
9 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR [ \fIlibrary\fR... ] |
|
10 #include <gssapi/gssapi.h> |
|
11 |
|
12 \fBOM_uint32\fR \fBgss_display_status\fR(\fBOM_uint32 *\fR\fIminor_status\fR, |
|
13 \fBOM_uint32\fR \fIstatus value\fR,\fBint\fR \fIstatus type\fR, |
|
14 \fBconst gss_OID\fR \fImech_type\fR, \fBOM_uint32 *\fR\fImessage_context\fR, |
|
15 \fBgss_buffer_t\fR \fIstatus string\fR); |
|
16 .fi |
|
17 |
|
18 .SH DESCRIPTION |
|
19 .sp |
|
20 .LP |
|
21 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. |
|
22 .sp |
|
23 .LP |
|
24 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. |
|
25 .sp |
|
26 .LP |
|
27 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. |
|
28 .SH PARAMETERS |
|
29 .sp |
|
30 .LP |
|
31 The parameter descriptions for \fBgss_display_status()\fR follow: |
|
32 .sp |
|
33 .ne 2 |
|
34 .mk |
|
35 .na |
|
36 \fB\fIminor_status\fR\fR |
|
37 .ad |
|
38 .RS 19n |
|
39 .rt |
|
40 Status code returned by the underlying mechanism. |
|
41 .RE |
|
42 |
|
43 .sp |
|
44 .ne 2 |
|
45 .mk |
|
46 .na |
|
47 \fB\fIstatus_value\fR\fR |
|
48 .ad |
|
49 .RS 19n |
|
50 .rt |
|
51 Status value to be converted. |
|
52 .RE |
|
53 |
|
54 .sp |
|
55 .ne 2 |
|
56 .mk |
|
57 .na |
|
58 \fB\fIstatus_type\fR\fR |
|
59 .ad |
|
60 .RS 19n |
|
61 .rt |
|
62 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. |
|
63 .RE |
|
64 |
|
65 .sp |
|
66 .ne 2 |
|
67 .mk |
|
68 .na |
|
69 \fB\fImech_type\fR\fR |
|
70 .ad |
|
71 .RS 19n |
|
72 .rt |
|
73 Underlying mechanism that is used to interpret a minor status value. Supply \fBGSS_C_NO_OID\fR to obtain the system default. |
|
74 .RE |
|
75 |
|
76 .sp |
|
77 .ne 2 |
|
78 .mk |
|
79 .na |
|
80 \fB\fImessage_context\fR\fR |
|
81 .ad |
|
82 .RS 19n |
|
83 .rt |
|
84 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. |
|
85 .RE |
|
86 |
|
87 .sp |
|
88 .ne 2 |
|
89 .mk |
|
90 .na |
|
91 \fB\fIstatus_string\fR\fR |
|
92 .ad |
|
93 .RS 19n |
|
94 .rt |
|
95 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). |
|
96 .RE |
|
97 |
|
98 .SH ERRORS |
|
99 .sp |
|
100 .LP |
|
101 The \fBgss_display_status()\fR function may return the following status codes: |
|
102 .sp |
|
103 .ne 2 |
|
104 .mk |
|
105 .na |
|
106 \fB\fBGSS_S_COMPLETE\fR\fR |
|
107 .ad |
|
108 .RS 20n |
|
109 .rt |
|
110 Successful completion. |
|
111 .RE |
|
112 |
|
113 .sp |
|
114 .ne 2 |
|
115 .mk |
|
116 .na |
|
117 \fB\fBGSS_S_BAD_MECH\fR\fR |
|
118 .ad |
|
119 .RS 20n |
|
120 .rt |
|
121 Indicates that translation in accordance with an unsupported mechanism type was requested. |
|
122 .RE |
|
123 |
|
124 .sp |
|
125 .ne 2 |
|
126 .mk |
|
127 .na |
|
128 \fB\fBGSS_S_BAD_STATUS\fR\fR |
|
129 .ad |
|
130 .RS 20n |
|
131 .rt |
|
132 The status value was not recognized, or the status type was neither \fBGSS_C_GSS_CODE\fR nor \fBGSS_C_MECH_CODE\fR. |
|
133 .RE |
|
134 |
|
135 .sp |
|
136 .ne 2 |
|
137 .mk |
|
138 .na |
|
139 \fB\fBGSS_S_FAILURE\fR\fR |
|
140 .ad |
|
141 .RS 20n |
|
142 .rt |
|
143 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. |
|
144 .RE |
|
145 |
|
146 .SH ATTRIBUTES |
|
147 .sp |
|
148 .LP |
|
149 See \fBattributes\fR(5) for descriptions of the following attributes: |
|
150 .sp |
|
151 |
|
152 .sp |
|
153 .TS |
|
154 tab() box; |
|
155 cw(2.75i) |cw(2.75i) |
|
156 lw(2.75i) |lw(2.75i) |
|
157 . |
|
158 ATTRIBUTE TYPEATTRIBUTE VALUE |
|
159 _ |
|
160 MT-LevelSafe |
|
161 .TE |
|
162 |
|
163 .SH SEE ALSO |
|
164 .sp |
|
165 .LP |
|
166 \fBgss_acquire_cred\fR(3GSS), \fBgss_release_buffer\fR(3GSS), \fBattributes\fR(5) |
|
167 .sp |
|
168 .LP |
|
169 |