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

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1998, 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 VLFMT 3C "Dec 29, 1996"
   7 .SH NAME
   8 vlfmt \- display error message in standard format and pass to logging and
   9 monitoring services
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <pfmt.h>
  14 #include <stdarg.h>
  15
  16 \fBint\fR \fBvlfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflag\fR, \fBconst char *\fR\fIformat\fR, \fBva_list\fR \fIap\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBvlfmt()\fR function is identical to \fBlfmt\fR(3C), except that it is
  23 called with an argument list as defined by \fB<stdarg.h>\fR\&.
  24 .sp
  25 .LP
  26 The <\fBstdarg.h\fR> header defines the type \fBva_list\fR and a set of macros
  27 for advancing through a list of arguments whose number and types may vary. The
  28 \fIap\fR argument is of type \fBva_list\fR. This argument is used with the
  29 <\fBstdarg.h\fR> macros \fBva_start()\fR, \fBva_arg()\fR, and \fBva_end()\fR.
  30 See \fBstdarg\fR(3EXT). The example in the \fBEXAMPLES\fR section below
  31 demonstrates their use with \fBvlfmt()\fR.
  32 .SH RETURN VALUES
  33 .sp
  34 .LP
  35 Upon successful completion, \fBvlfmt()\fR returns the number of bytes
  36 transmitted.  Otherwise, \fB\(mi1\fR is returned if there was a write error to
  37 \fIstream\fR, or \fB\(mi2\fR is returned if unable to log and/or display at
  38 console.
  39 .SH EXAMPLES
  40 .LP
  41 \fBExample 1 \fRUse of \fBvlfmt()\fR to write an \fBerrlog()\fRroutine.
  42 .sp
  43 .LP
  44 The following example demonstrates how \fBvlfmt()\fR could be used to write an
  45 \fBerrlog()\fR routine. The \fBva_alist()\fR macro is used as the parameter
  46 list in a function definition. The \fBva_start(\fR\fIap\fR, .\|.\|.) call,
  47 where \fIap\fR is of type \fBva_list\fR, must be invoked before any attempt to
  48 traverse and access unnamed arguments. Calls to \fBva_arg(\fR\fIap\fR\fB,
  49 \fR\fIatype\fR\fB)\fR traverse the argument list. Each execution of
  50 \fBva_arg()\fR expands to an expression with the value and type of the next
  51 argument in the list \fIap\fR, which is the same object initialized by
  52 \fBva_start()\fR. The \fIatype\fR argument is the type that the returned
  53 argument is expected to be. The \fBva_end(\fR\fIap\fR\fB)\fR macro must be
  54 invoked when all desired arguments have been accessed. The argument list in
  55 \fIap\fR can be traversed again if \fBva_start()\fR is called again after
  56 \fBva_end()\fR.) In the example below, \fBva_arg()\fR is executed first to
  57 retrieve the format string passed to \fBerrlog()\fR. The remaining
  58 \fBerrlog()\fR arguments (\fIarg1\fR, \fIarg2\fR, \fI\&...\fR) are passed to
  59 \fBvlfmt()\fR in the argument \fIap\fR.
  60
  61 .sp
  62 .in +2
  63 .nf
  64 \fB#include <pfmt.h>
  65 #include <stdarg.h>
  66 /*
  67  *   errlog should be called like
  68  *         errlog(log_info, format, arg1, ...);
  69  */
  70 void errlog(long log_info, ...)
  71 {
  72         va_list ap;
  73         char *format;
  74         va_start(ap, );
  75         format = va_arg(ap, char *);
  76         (void) vlfmt(stderr, log_info|MM_ERROR, format, ap);
  77         va_end(ap);
  78         (void) abort();
  79 }\fR
  80 .fi
  81 .in -2
  82
  83 .SH USAGE
  84 .sp
  85 .LP
  86 Since \fBvlfmt()\fR uses \fBgettxt\fR(3C), it is recommended that \fBvlfmt()\fR
  87 not be used.
  88 .SH ATTRIBUTES
  89 .sp
  90 .LP
  91 See \fBattributes\fR(5) for descriptions of the following attributes:
  92 .sp
  93
  94 .sp
  95 .TS
  96 box;
  97 c | c
  98 l | l .
  99 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 100 _
 101 MT-Level        MT-Safe
 102 .TE
 103
 104 .SH SEE ALSO
 105 .sp
 106 .LP
 107 \fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBattributes\fR(5), \fBstdarg\fR(3EXT)