usr/src/man/man3c/vpfmt.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 VPFMT 3C "Dec 29, 1996"
   7 .SH NAME
   8 vpfmt \- 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 \fBvpfmt\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 \fBvpfmt()\fR function is identical to \fBpfmt\fR(3C), except that it is
  23 called with an argument list as defined by <\fBstdarg.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 \fBvpfmt()\fR.
  32 .SH RETURN VALUES
  33 .sp
  34 .LP
  35 Upon successful completion, \fBvpfmt()\fR returns the number of bytes
  36 transmitted.  Otherwise, \fB\(mi1\fR is returned if there was a write error to
  37 \fIstream\fR.
  38 .SH EXAMPLES
  39 .LP
  40 \fBExample 1 \fRUse of \fBvpfmt()\fR to write an error routine.
  41 .sp
  42 .LP
  43 The following example demonstrates how \fBvpfmt()\fR could be used to write an
  44 \fBerror()\fR routine. The \fBva_alist()\fR macro is used as the parameter list
  45 in a function definition. The \fBva_start(\fR\fIap\fR, .\|.\|.) call, where
  46 \fIap\fR is of type \fBva_list\fR, must be invoked before any attempt to
  47 traverse and access unnamed arguments. Calls to \fBva_arg(\fR\fIap\fR\fB,
  48 \fR\fIatype\fR\fB)\fR traverse the argument list. Each execution of
  49 \fBva_arg()\fR expands to an expression with the value and type of the next
  50 argument in the list \fIap\fR, which is the same object initialized by
  51 \fBva_start()\fR. The \fIatype\fR argument is the type that the returned
  52 argument is expected to be. The \fBva_end(\fR\fIap\fR\fB)\fR macro must be
  53 invoked when all desired arguments have been accessed. The argument list in
  54 \fIap\fR can be traversed again if \fBva_start()\fR is called again after
  55 \fBva_end()\fR. In the example below, \fBva_arg()\fR is executed first to
  56 retrieve the format string passed to \fBerror()\fR. The remaining \fBerror()\fR
  57 arguments (\fIarg1\fR, \fIarg2\fR, ...) are passed to \fBvpfmt()\fR in the
  58 argument \fIap\fR.
  59
  60 .sp
  61 .in +2
  62 .nf
  63 #include <pfmt.h>
  64 #include <stdarg.h>
  65 /*
  66  *   error should be called like
  67  *         error(format, arg1, ...);
  68  */
  69 void error(...)
  70 {
  71         va_list ap;
  72         char *format;
  73         va_start(ap, );
  74         format = va_arg(ap, char *);
  75         (void) vpfmt(stderr, MM_ERROR, format, ap);
  76         va_end(ap);
  77         (void) abort();
  78 }
  79 .fi
  80 .in -2
  81
  82 .SH USAGE
  83 .sp
  84 .LP
  85 Since \fBvpfmt()\fR uses \fBgettxt\fR(3C), it is recommended that \fBvpfmt()\fR
  86 not be used.
  87 .SH ATTRIBUTES
  88 .sp
  89 .LP
  90 See \fBattributes\fR(5) for descriptions of the following attributes:
  91 .sp
  92
  93 .sp
  94 .TS
  95 box;
  96 c | c
  97 l | l .
  98 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  99 _
 100 MT-Level        MT-Safe
 101 .TE
 102
 103 .SH SEE ALSO
 104 .sp
 105 .LP
 106 \fBgettxt\fR(3C), \fBpfmt\fR(3C), \fBattributes\fR(5), \fBstdarg\fR(3EXT)