usr/src/man/man3cpc/cpc_seterrfn.3cpc

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc.
   3 .\" All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH CPC_SETERRFN 3CPC "Mar 28, 2005"
   8 .SH NAME
   9 cpc_seterrfn \- control libcpc error reporting
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ]
  14 #include <libcpc.h>
  15
  16 \fBtypedef void (\fR\fBcpc_errfn_t\fR)(\fBconst char *\fR\fIfn\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBcpc_seterrfn\fR(\fBcpc_errfn_t *\fR\fIerrfn\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .sp
  26 .LP
  27 For the convenience of programmers instrumenting their code, several
  28 \fBlibcpc\fR(3LIB) functions automatically emit to \fBstderr\fR error messages
  29 that attempt to provide a more detailed explanation of their error return
  30 values.  While this can be useful for simple programs, some applications may
  31 wish to report their errors differently\(emfor example, to a window or to a log
  32 file.
  33 .sp
  34 .LP
  35 The \fBcpc_seterrfn()\fR function allows the caller to provide an alternate
  36 function for reporting errors; the type signature is shown above.  The \fIfn\fR
  37 argument is passed the library function name that detected the error, the
  38 format string \fIfmt\fR and argument pointer \fIap\fR can be passed directly to
  39 \fBvsnprintf\fR(3C) or similar \fBvarargs\fR-based routine for formatting.
  40 .sp
  41 .LP
  42 The default printing routine can be restored by calling the routine with an
  43 \fIerrfn\fR argument of \fINULL\fR.
  44 .SH EXAMPLES
  45 .LP
  46 \fBExample 1 \fRDebugging example.
  47 .sp
  48 .LP
  49 This example produces error messages only when debugging the program containing
  50 it, or when the  \fBcpc_strtoevent()\fR function is reporting an error when
  51 parsing an event specification
  52
  53 .sp
  54 .in +2
  55 .nf
  56 \fBint debugging;
  57 void
  58 myapp_errfn(const char *fn, const char *fmt, va_list ap)
  59 {
  60         if (strcmp(fn, "strtoevent") != 0 && !debugging)
  61             return;
  62         (void) fprintf(stderr, "myapp: cpc_%s(): ", fn);
  63         (void) vfprintf(stderr, fmt, ap);
  64 }\fR
  65 .fi
  66 .in -2
  67
  68 .SH ATTRIBUTES
  69 .sp
  70 .LP
  71 See \fBattributes\fR(5) for descriptions of the following attributes:
  72 .sp
  73
  74 .sp
  75 .TS
  76 box;
  77 c | c
  78 l | l .
  79 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  80 _
  81 MT-Level        Unsafe
  82 _
  83 Interface Stability     Obsolete
  84 .TE
  85
  86 .SH SEE ALSO
  87 .sp
  88 .LP
  89 \fBcpc\fR(3CPC), \fBcpc_seterrhndlr\fR(3CPC), \fBlibcpc\fR(3LIB),
  90 \fBvsnprintf\fR(3C), \fBattributes\fR(5)
  91 .SH NOTES
  92 .sp
  93 .LP
  94 The \fBcpc_seterrfn()\fR function exists for binary compatibility only. Source
  95 containing this function will not compile. This function is obsolete and might
  96 be removed in a future release. Applications should use
  97 \fBcpc_seterrhndlr\fR(3CPC) instead.