usr/src/man/man3gss/gss_oid_to_str.3gss

   1 '\" te
   2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH GSS_OID_TO_STR 3GSS "Aug 15, 2007"
   7 .SH NAME
   8 gss_oid_to_str \- convert an OID to a string
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fB\fR\fBgss_oid_to_str\fR(\fBOM_uint32 *\fR\fIminor_status\fR, \fBconst gss_OID\fR \fIoid\fR,
  16      \fBgss_buffer_t\fR\fIoid_str\fR);
  17 .fi
  18
  19 .SH PARAMETERS
  20 .sp
  21 .ne 2
  22 .na
  23 \fB\fIminor_status\fR\fR
  24 .ad
  25 .RS 16n
  26 Status code returned by underlying mechanism.
  27 .RE
  28
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIoid\fR\fR
  33 .ad
  34 .RS 16n
  35 \fBGSS-API\fR \fBOID\fR structure to convert.
  36 .RE
  37
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fIoid_str\fR\fR
  42 .ad
  43 .RS 16n
  44 String to receive converted \fBOID\fR.
  45 .RE
  46
  47 .SH DESCRIPTION
  48 .sp
  49 .LP
  50 The \fBgss_oid_to_str()\fR function converts a \fBGSS-API\fR \fBOID\fR
  51 structure to a string. You can use the function to convert the name of a
  52 mechanism from an \fBOID\fR to a simple string. This function is a convenience
  53 function, as is its complementary function, \fBgss_str_to_oid\fR(3GSS).
  54 .sp
  55 .LP
  56 If an \fBOID\fR must be created, use \fBgss_create_empty_oid_set\fR(3GSS) and
  57 \fBgss_add_oid_set_member\fR(3GSS) to create it.  \fBOID\fRs created in this
  58 way must be released with \fBgss_release_oid_set\fR(3GSS). However, it is
  59 strongly suggested that applications use the default \fBGSS-API\fR mechanism
  60 instead of creating an \fBOID\fR for a specific mechanism.
  61 .SH ERRORS
  62 .sp
  63 .LP
  64 The \fBgss_oid_to_str()\fR function returns one of the following status codes:
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBGSS_S_CALL_INACCESSIBLE_READ\fR\fR
  69 .ad
  70 .sp .6
  71 .RS 4n
  72 A required input parameter could not be read.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBGSS_S_CALL_INACCESSIBLE_WRITE\fR\fR
  79 .ad
  80 .sp .6
  81 .RS 4n
  82 A required output parameter could not be written.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBGSS_S_COMPLETE\fR\fR
  89 .ad
  90 .sp .6
  91 .RS 4n
  92 Successful completion.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBGSS_S_FAILURE\fR\fR
  99 .ad
 100 .sp .6
 101 .RS 4n
 102 The underlying mechanism detected an error for which no specific \fBGSS\fR
 103 status code is defined.  The mechanism-specific status code reported by means
 104 of the \fIminor_status\fR parameter details the error condition.
 105 .RE
 106
 107 .SH ATTRIBUTES
 108 .sp
 109 .LP
 110 See \fBattributes\fR(5)  for descriptions of the following attributes:
 111 .sp
 112
 113 .sp
 114 .TS
 115 box;
 116 c | c
 117 l | l .
 118 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 119 _
 120 MT-Level        Safe
 121 .TE
 122
 123 .SH SEE ALSO
 124 .sp
 125 .LP
 126 \fBgss_add_oid_set_member\fR(3GSS), \fBgss_create_empty_oid_set\fR(3GSS),
 127 \fBgss_release_oid_set\fR(3GSS), \fBgss_str_to_oid\fR(3GSS),
 128 \fBattributes\fR(5)
 129 .sp
 130 .LP
 131 \fISolaris Security for Developers Guide\fR
 132 .SH WARNINGS
 133 .sp
 134 .LP
 135 This function is included for compatibility only with programs using earlier
 136 versions of the \fBGSS-API\fR and should not be used for new programs. Other
 137 implementations of the \fBGSS-API\fR might not support this function, so
 138 portable programs should not rely on it. Sun might not continue to support this
 139 function.