usr/src/man/man3tsol/label_to_str.3tsol

   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 LABEL_TO_STR 3TSOL "Jul 20, 2007"
   7 .SH NAME
   8 label_to_str \- convert labels to human readable strings
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [\fIflag\fR...] \fIfile\fR... \fB-ltsol\fR [\fIlibrary\fR...]
  13 .fi
  14
  15 .LP
  16 .nf
  17 #include <tsol/label.h>
  18
  19 \fBint\fR \fBlabel_to_str\fR(\fBconst m_label_t *\fR\fIlabel\fR, \fBchar **\fR\fIstring\fR,
  20     \fBconst m_label_str_t\fR \fIconversion_type\fR, \fBuint_t\fR \fIflags\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 \fBlabel_to_str()\fR is a simple function to convert various mandatory label
  27 types to human readable strings.
  28 .sp
  29 .LP
  30 \fIlabel\fR is the mandatory label to convert. \fIstring\fR points to memory
  31 that is allocated by \fBlabel_to_str()\fR that contains the converted string.
  32 The caller is responsible for calling \fBfree\fR(3C) to free allocated memory.
  33 .sp
  34 .LP
  35 The calling process must have mandatory read access to the resulting human
  36 readable string. Or the calling process must have the \fBsys_trans_label\fR
  37 privilege.
  38 .sp
  39 .LP
  40 The \fIconversion_type\fR parameter controls the type of label conversion. Not
  41 all types of conversion are valid for all types of label:
  42 .sp
  43 .ne 2
  44 .na
  45 \fB\fBM_LABEL\fR\fR
  46 .ad
  47 .RS 22n
  48 Converts \fIlabel\fR to a human readable string based on its type.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fBM_INTERNAL\fR\fR
  55 .ad
  56 .RS 22n
  57 Converts \fIlabel\fR to an internal text representation that is safe for
  58 storing in a public object. Internal conversions can later be parsed to their
  59 same value.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBM_COLOR\fR\fR
  66 .ad
  67 .RS 22n
  68 Converts \fIlabel\fR to a string that represents the color name that the
  69 administrator has associated with the label.
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBPRINTER_TOP_BOTTOM\fR\fR
  76 .ad
  77 .RS 22n
  78 Converts \fIlabel\fR to a human readable string that is appropriate for use as
  79 the top and bottom label of banner and trailer pages in the Defense
  80 Intelligence Agency (DIA) encodings printed output schema.
  81 .RE
  82
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBPRINTER_LABEL\fR\fR
  87 .ad
  88 .RS 22n
  89 Converts \fIlabel\fR to a human readable string that is appropriate for use as
  90 the banner page downgrade warning in the DIA encodings printed output schema.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fBPRINTER_CAVEATS\fR\fR
  97 .ad
  98 .RS 22n
  99 Converts \fIlabel\fR to a human readable string that is appropriate for use as
 100 the banner page caveats section in the DIA encodings printed output schema.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBPRINTER_CHANNELS\fR\fR
 107 .ad
 108 .RS 22n
 109 Converts \fIlabel\fR to a human readable string that is appropriate for use as
 110 the banner page handling channels in the DIA encodings printed output schema.
 111 .RE
 112
 113 .sp
 114 .LP
 115 The \fIflags\fR parameter provides a hint to the label conversion:
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBDEF_NAMES\fR\fR
 120 .ad
 121 .RS 15n
 122 The default names are preferred.
 123 .RE
 124
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBSHORT_NAMES\fR\fR
 129 .ad
 130 .RS 15n
 131 Short names are preferred where defined.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBLONG_NAMES\fR\fR
 138 .ad
 139 .RS 15n
 140 Long names are preferred.
 141 .RE
 142
 143 .SH RETURN VALUES
 144 .sp
 145 .LP
 146 Upon successful completion, the \fBlabel_to_str()\fR function returns 0.
 147 Otherwise, -1 is returned, \fIerrno\fR is set to indicate the error and the
 148 string pointer is set to \fINULL\fR.
 149 .SH ERRORS
 150 .sp
 151 .LP
 152 The \fBlabel_to_str()\fR function will fail if:
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBEINVAL\fR\fR
 157 .ad
 158 .RS 11n
 159 Invalid parameter.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBENOTSUP\fR\fR
 166 .ad
 167 .RS 11n
 168 The system does not support label translations.
 169 .RE
 170
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBENOMEM\fR\fR
 175 .ad
 176 .RS 11n
 177 The physical limits of the system are exceeded by size bytes of memory which
 178 cannot be allocated.
 179 .RE
 180
 181 .SH ATTRIBUTES
 182 .sp
 183 .LP
 184 See \fBattributes\fR(5) for descriptions of the following attributes:
 185 .sp
 186
 187 .sp
 188 .TS
 189 box;
 190 c | c
 191 l | l .
 192 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 193 _
 194 Interface Stability     See below.
 195 _
 196 MT-Level        MT-Safe
 197 _
 198 Standard        See below.
 199 .TE
 200
 201 .sp
 202 .LP
 203 The \fBlabel_to_str()\fR function is Committed. The returned string is
 204 Not-an-Interface and is dependent on the specific \fBlabel_encodings\fR file.
 205 The conversion type \fBINTERNAL\fR is Uncommitted, but is always accepted as
 206 input to \fBstr_to_label\fR(3TSOL).
 207 .sp
 208 .LP
 209 Conversion types that are relative to the DIA encodings schema are Standard.
 210 Standard is specified in \fBlabel_encodings\fR(4).
 211 .SH SEE ALSO
 212 .sp
 213 .LP
 214 \fBfree\fR(3C), \fBlibtsol\fR(3LIB), \fBstr_to_label\fR(3TSOL),
 215 \fBlabel_encodings\fR(4), \fBattributes\fR(5), \fBlabels\fR(5)
 216 .sp
 217 .LP
 218 \fIUsing the label_to_str Function\fR in \fISolaris Trusted Extensions
 219 Developer\&'s Guide\fR
 220 .SH WARNINGS
 221 .sp
 222 .LP
 223 A number of these conversions rely on the DIA label encodings schema. They
 224 might not be valid for other label schemata.
 225 .SH NOTES
 226 .sp
 227 .LP
 228 The functionality described on this manual page is available only if the system
 229 is configured with Trusted Extensions.