DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

pfmt(S)


pfmt, vpfmt -- display error message in standard format

Syntax

cc ...-lc

#include <pfmt.h>

int pfmt(FILE *stream, long flags, const char *format, . . . /* args */);

#include <pfmt.h>

int vpfmt(FILE *stream, long flags, const char *format, va_list ap);

Description

pfmt- display an error message in standard format; called with a variable number of arguments

vpfmt- display an error message in standard format; called with an argument list

pfmt

pfmt(S) uses a format string, from a message database, for printf(S) style formatting of args. The message database is generated by the mkmsgs(CP) utility. The output is displayed on stream. pfmt( ) places the output in the standard error message format.

To retrieve the printf( ) format string from the message database, the format argument must have the following structure:

[[catalog]:[msgnum]:]defmsg.


catalog
indicates the message database that contains the localized version of the format string. catalog is limited to 255 characters. They are selected from a set of all characters' values, excluding nbsp; (null) and the ASCII codes for ``/'' (slash) and ``:'' (colon).


msgnum
is a positive number that indicates the index of the string into the message database.


defmsg
can appear alone only if flags include MM_NOGET.

If archivename is specified, then pfmt( ) accesses the message database in an archive directory. The environment variable NLSPATH specifies the pathname for the message database, substituting filename for %N and archivename for %A. (See the explanation of NLSPATH, below.)

If you use the special syntax for catalog,

catalogname@archivename

then pfmt( ) accesses only archives. The environment variable NLSPATH is used with the archivename part of catalog substituted for %A (See environ(M)) Only the parts of the paths that contain %A are recognized.

If the message number is out of bounds, or if catalog does not exist in the locale (specified by the last call to setlocale(S) using the LC_ALL or LC_MESSAGES categories), pfmt( ) tries to retrieve the message from the C locale. If this second retrieval fails, pfmt( ) uses the defmsg part of the format argument.

The syntax for msgfilename is

filename[@archivename]

If NLSPATH does not exist in the environment, or if a message catalog can not be opened in any of the paths specified by NLSPATH, then the following default paths are used:


/usr/lib/nls/msg/%L/%A/%N

/usr/lib/nls/msg/%l_%t/%A/%N

/usr/lib/nls/msg/%l/%A/%N

/etc/nls/msg/%L/%A/%N

/etc/nls/msg/%l_%t/%A/%N

/etc/nls/msg/%l/%A/%N
where

%L
is the value of the LC_MESSAGES category

%l
is the language component from the LC_MESSAGES category

%t
is the territory component from the LC_MESSAGES category

%A
is the optional archive component of the message catalog name

%N
is the file component of the message catalog name
If the optional archive component is not in the message catalog name, %A is omitted from the NLSPATH definition.

If catalog is omitted, pfmt( ) tries to retrieve the string from the default catalog specified by the last call to setcat(S). In this case, the format argument has the following structure:

msgnum:defmsg.

pfmt( ) outputs:

   Message not found!!
as the format string if: The flags determine the type of output (that is, whether to interpret the format as is or placed in the standard message format). They also determine access to message catalogs to retrieve a localized version of format.

The flags are composed of several groups, and can take the following values, one from each group:


Output format control

MM_NOSTD
do not use the standard message format, but interpret format as a printf( ) format. If you use MM_NOSTD, specify only catalog access control flags; all other flags are ignored.

MM_STD
output using the standard message format (default, value 0).

Catalog access control

MM_NOGET
do not retrieve a localized version of format. In this case, only the defmsg part of the format is specified.

MM_GET
retrieve a localized version of format, from the catalog, using msgnum as the index and defmsg as the default message (default, value 0).

Severity (standard message format only)

MM_HALT
generates a localized version of HALT.

MM_ERROR
generates a localized version of ERROR (default, value 0).

MM_WARNING
generates a localized version of WARNING.

MM_INFO
generates a localized version of INFO.

Additional severities can be defined. Add-on severities can be defined with number-string pairs with numeric values from the range [5-255], using addsev(S). The numeric value ORed with other flags will generate the specified severity.

If the severity is not defined, pfmt( ) uses the string SEV=N where N is replaced by the integer severity value passed in flags.

Multiple severities passed in flags are not detected as an error. Any combination of severities is summed and the numeric value causes the display of either a severity string (if defined) or the string SEV=N (if undefined).


Action

MM_ACTION
specifies an action message. Any severity value is superseded and replaced by a localized version of the string TO FIX.

Standard error message format

pfmt( ) displays error messages in the following format:
   label: severity: text
If no label was defined by a call to setlabel(S), the message is displayed in the format:
   severity: text
If pfmt( ) is called twice to display an error message and a helpful action or recovery message, the output can look like:
   label: severity: text
   label: TO FIX: text

vpfmt

vpfmt(S) is the same as pfmt( ) except that instead of being called with a variable number of arguments, it is called with an argument list as defined by the header file stdarg.h.

The file stdarg.h defines the type va_list and a set of macros for advancing through a list of arguments whose number and types may vary. The argument ap to vpfmt( ) is of type va_list. This argument is used with the stdarg.h header file macros va_start, va_arg and va_end (see varargs(S)). The examples below show their use.

The macro va_alist is used as the parameter list in a function definition as in the function called error in the example shown in the ``Examples'' section that follows. You must call the macro va_start(ap), where ap is of type va_list, before trying to traverse and access unnamed arguments. Calls to va_arg(ap atype) traverse the argument list. Each execution of va_arg expands to an expression with the value and type of the next argument in the list ap, which is the same object initialized by va_start. The argument atype is the type that the returned argument is expected to be.

The va_end(ap) macro is invoked when all desired arguments have been accessed. (The argument list in ap can be traversed again if va_start is called again after va_end.) In the example below, va_arg is executed first to retrieve the format string passed to error. The remaining error arguments, arg1, arg2, ..., are given to vpfmt( ) in the argument ap.

Return values

On success, pfmt( ) and vpfmt( ) return the number of bytes transmitted. On failure, they return a negative value. A value of -1 means`` cannot write to stream''.

Diagnostics

Diagnostic codes for this function are described below.

[ERANGE]
The message is too large to be represented in the available space.

Examples

pfmt example 1

The example below,
   setlabel("SCO:test");
   pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\n",
     strerror(errno));
displays the message:
   SCO:test: ERROR: Cannot open file: No such file or directory

pfmt example 2

The example below,
   setlabel("SCO:test");
   setcat("test");
   pfmt(stderr, MM_ERROR, ":10:Syntax error\n");
   pfmt(stderr, MM_ACTION, ":55:Usage ...\n");
displays the message
   SCO:test: ERROR: Syntax error
   SCO:test: TO FIX: Usage ...

vpfmt example

The following demonstrates how vpfmt( ) could be used to write an error routine:
   #include <pfmt.h>
   #include <stdarg.h>
    . . .
   /*
    *   error should be called like
    *         error(format, arg1, ...);
    */
   void error(const char *format, ...)
   

{ va_list ap;

va_start(ap, ); (void) vpfmt(stderr, MM_ERROR, format, ap); va_end(ap); (void) abort(); }

See also

addsev(S), environ(M), gettxt(S), mkmsgs(CP), pfmt(S), printf(S), setcat(S), setlabel(S), setlocale(S), varargs(S)

Standards conformance

pfmt(S) and vpfmt(S) are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003