usr/src/man/man3c/pfmt.3c

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1997, 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 PFMT 3C "Dec 29, 1996"
   7 .SH NAME
   8 pfmt \- display error message in standard format
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <pfmt.h>
  13
  14 \fBint\fR \fBpfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg */\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBpfmt()\fR retrieves a format string from a locale-specific message
  21 database (unless \fBMM_NOGET\fR is specified) and uses it for \fBprintf\fR(3C)
  22 style formatting of \fIargs\fR. The output is displayed on \fIstream\fR.
  23 .sp
  24 .LP
  25 The \fBpfmt()\fR function encapsulates the output in the standard error message
  26 format (unless \fBMM_NOSTD\fR is specified, in which case the output is similar
  27 to \fBprintf()\fR).
  28 .sp
  29 .LP
  30 If the \fBprintf()\fR format string is to be retrieved from a message database,
  31 the \fBformat\fR argument must have the following structure:
  32 .sp
  33 .LP
  34 \fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
  35 .sp
  36 .LP
  37 If \fBMM_NOGET\fR is specified, only the \fIdefmsg\fR field must be specified.
  38 .sp
  39 .LP
  40 The \fIcatalog\fR field is used to indicate the message database that contains
  41 the localized version of the format string. This field must be limited to 14
  42 characters selected from the set of all characters values, excluding \fB\e0\fR
  43 (null) and the ASCII codes for \fB/\fR (slash) and \fB:\fR (colon).
  44 .sp
  45 .LP
  46 The \fImsgnum\fR field is a positive number that indicates the index of the
  47 string into the message database.
  48 .sp
  49 .LP
  50 If the catalog does not exist in the locale (specified by the last call to
  51 \fBsetlocale\fR(3C) using the \fBLC_ALL\fR or \fBLC_MESSAGES\fR categories), or
  52 if the message number is out of bound, \fBpfmt()\fR will attempt to retrieve
  53 the message from the C locale. If this second retrieval fails, \fBpfmt()\fR
  54 uses the \fIdefmsg\fR field of the \fBformat\fR argument.
  55 .sp
  56 .LP
  57 If \fIcatalog\fR is omitted, \fBpfmt()\fR will attempt to retrieve the string
  58 from the default catalog specified by the last call to \fBsetcat\fR(3C). In
  59 this case, the \fBformat\fR argument has the following structure:
  60 .sp
  61 .LP
  62 \fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
  63 .sp
  64 .LP
  65 The \fBpfmt()\fR will output \fBMessage not found!!\en\fR as format string if
  66 \fIcatalog\fR is not a valid catalog name, if no catalog is specified (either
  67 explicitely or with \fBsetcat()\fR), if \fImsgnum\fR is not a valid number, or
  68 if no message could be retrieved from the message databases and \fIdefmsg\fR
  69 was omitted.
  70 .sp
  71 .LP
  72 The \fIflags\fR argument determine the type of output (such as whether the
  73 \fBformat\fR should be interpreted as is or encapsulated in the standard
  74 message format), and the access to message catalogs to retrieve a localized
  75 version of \fBformat\fR.
  76 .sp
  77 .LP
  78 The \fIflags\fR argument is composed of several groups, and can take the
  79 following values (one from each group):
  80 .sp
  81 .LP
  82 \fIOutput format control\fR
  83 .sp
  84 .ne 2
  85 .na
  86 \fB\fBMM_NOSTD\fR\fR
  87 .ad
  88 .RS 12n
  89 Do not use the standard message format, interpret \fBformat\fR as
  90 \fBprintf()\fR \fBformat\fR. Only \fIcatalog access control flags\fR should be
  91 specified if \fBMM_NOSTD\fR is used; all other flags will be ignored.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBMM_STD\fR\fR
  98 .ad
  99 .RS 12n
 100 Output using the standard message format (default value 0).
 101 .RE
 102
 103 .sp
 104 .LP
 105 \fICatalog access control\fR
 106 .sp
 107 .ne 2
 108 .na
 109 \fB\fBMM_NOGET\fR\fR
 110 .ad
 111 .RS 12n
 112 Do not retrieve a localized version of \fBformat\fR. In this case, only the
 113 \fIdefmsg\fR field of the \fBformat\fR is specified.
 114 .RE
 115
 116 .sp
 117 .ne 2
 118 .na
 119 \fB\fBMM_GET\fR\fR
 120 .ad
 121 .RS 12n
 122 Retrieve a localized version of \fBformat\fR from the \fIcatalog\fR, using
 123 \fImsgid\fR as the index and \fIdefmsg\fR as the default message (default value
 124 0).
 125 .RE
 126
 127 .sp
 128 .LP
 129 \fISeverity (standard message format only)\fR
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBMM_HALT\fR\fR
 134 .ad
 135 .RS 14n
 136 Generate a localized version of \fBHALT,\fR but do not halt the machine.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBMM_ERROR\fR\fR
 143 .ad
 144 .RS 14n
 145 Generate a localized version of \fBERROR\fR (default value 0).
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBMM_WARNING\fR\fR
 152 .ad
 153 .RS 14n
 154 Generate a localized version of \fBWARNING.\fR
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBMM_INFO\fR\fR
 161 .ad
 162 .RS 14n
 163 Generate a localized version of \fBINFO.\fR
 164 .RE
 165
 166 .sp
 167 .LP
 168 Additional severities can be defined. Add-on severities can be defined with
 169 number-string pairs with numeric values from the range [5-255], using
 170 \fBaddsev\fR(3C). The specified severity will be generated from the bitwise
 171 \fBOR\fR operation of the numeric value and other \fIflags\fR If the severity
 172 is not defined, \fBpfmt()\fR uses the string \fBSEV=\fR\fIN\fR, where \fIN\fR
 173 is replaced by the integer severity value passed in \fIflags\fR.
 174 .sp
 175 .LP
 176 Multiple severities passed in \fIflags\fR will not be detected as an error. Any
 177 combination of severities will be summed and the numeric value will cause the
 178 display of either a severity string (if defined) or the string
 179 \fBSEV=\fR\fIN\fR (if undefined).
 180 .sp
 181 .LP
 182 \fIAction\fR
 183 .sp
 184 .ne 2
 185 .na
 186 \fB\fBMM_ACTION\fR\fR
 187 .ad
 188 .RS 13n
 189 Specify an action message. Any severity value is superseded and replaced by a
 190 localized version of \fBTO FIX\fR.
 191 .RE
 192
 193 .SH STANDARD ERROR MESSAGE FORMAT
 194 .sp
 195 .LP
 196 The \fBpfmt()\fR function displays error messages in the following format:
 197 .sp
 198 .in +2
 199 .nf
 200 \fIlabel\fR: \fIseverity\fR: \fItext\fR
 201 .fi
 202 .in -2
 203
 204 .sp
 205 .LP
 206 If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is
 207 displayed in the format:
 208 .sp
 209 .in +2
 210 .nf
 211 \fIseverity\fR: \fItext\fR
 212 .fi
 213 .in -2
 214
 215 .sp
 216 .LP
 217 If \fBpfmt()\fR is called twice to display an error message and a helpful
 218 \fIaction\fR or recovery message, the output can look like:
 219 .sp
 220 .in +2
 221 .nf
 222 \fIlabel\fR: \fIseverity\fR: \fItext\fR\fIlabel\fR: TO FIX: \fItext\fR
 223 .fi
 224 .in -2
 225
 226 .br
 227 .in +2
 228
 229 .in -2
 230 .br
 231 .in +2
 232
 233 .in -2
 234 .SH RETURN VALUES
 235 .sp
 236 .LP
 237 Upon success, \fBpfmt()\fR returns the number of bytes transmitted. Upon
 238 failure, it returns a negative value:
 239 .sp
 240 .ne 2
 241 .na
 242 \fB\fB\(mi1\fR\fR
 243 .ad
 244 .RS 9n
 245 Write error to \fIstream\fR.
 246 .RE
 247
 248 .SH EXAMPLES
 249 .LP
 250 \fBExample 1 \fRExample of \fBpfmt()\fR function.
 251 .sp
 252 .LP
 253 Example 1:
 254
 255 .sp
 256 .in +2
 257 .nf
 258 setlabel("UX:test");
 259 pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\en",
 260      strerror(errno));
 261
 262 displays the message:
 263
 264 UX:test: ERROR: Cannot open file: No such file or directory
 265 .fi
 266 .in -2
 267
 268 .sp
 269 .LP
 270 Example 2:
 271
 272 .sp
 273 .in +2
 274 .nf
 275 setlabel("UX:test");
 276 setcat("test");
 277 pfmt(stderr, MM_ERROR, ":10:Syntax error\en");
 278 pfmt(stderr, MM_ACTION, "55:Usage ...\en");
 279 .fi
 280 .in -2
 281
 282 .sp
 283 .LP
 284 displays the message
 285
 286 .sp
 287 .in +2
 288 .nf
 289 UX:test: ERROR: Syntax error
 290 UX:test: TO FIX: Usage ...
 291 .fi
 292 .in -2
 293
 294 .SH USAGE
 295 .sp
 296 .LP
 297 Since it uses \fBgettxt\fR(3C), \fBpfmt()\fR should not be used.
 298 .SH ATTRIBUTES
 299 .sp
 300 .LP
 301 See \fBattributes\fR(5) for descriptions of the following attributes:
 302 .sp
 303
 304 .sp
 305 .TS
 306 box;
 307 c | c
 308 l | l .
 309 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 310 _
 311 MT-Level        MT-safe
 312 .TE
 313
 314 .SH SEE ALSO
 315 .sp
 316 .LP
 317 \fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBprintf\fR(3C),
 318 \fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
 319 \fBenviron\fR(5)