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