Manual Pages for UNIX Operating System command usage for man cpc_seterrhndlr

CPU Performance Counters Library Functions  cpc_seterrhndlr(3CPC)



NAME
     cpc_seterrhndlr - control libcpc error reporting

SYNOPSIS
     cc [ flag... ] file... -lcpc [ library... ]
     #include 

     typedef void(cpc_errhndlr_t)(cpc_t *cpc, const char *fn, int subcode,
          const char *fmt, va_list ap);


     void cpc_seterrhndlr(cpc_t *cpc, cpc_errhndlr_t *errfn);


DESCRIPTION
     For the convenience of programmers instrumenting their code,
     several  libcpc(3LIB) functions automatically emit to stderr
     error messages that  attempt  to  provide  a  more  detailed
     explanation of their error return values.  While this can be
     useful for simple programs, some applications might wanat to
     report their errors differently, for example, to a window or
     to a log file.


     The cpc_seterrhndlr() function allows the caller to  provide
     an  alternate function for reporting errors. The type signa-
     ture is shown in the SYNOPSIS. The fn argument is passed the
     library  function  name  that detected the error, an integer
     subcode indicating the specific error  condidtion  that  has
     occurred,  and the format string fmt that contains a textual
     description of the integer subcode. The  format  string  fmt
     and   argument   pointer   ap  can  be  passed  directly  to
     vsnprintf(3C) or similar varargs-based function for  format-
     ting.


     The integer subcodes  are  provided  to  allow  programs  to
     recognize  error  conditions  while  using  libcpc.  The fmt
     string is provided as a convenience for easy  printing.  The
     error subcodes are:

     CPC_INVALID_EVENT

         A specified event is not supported by the processor.


     CPC_INVALID_PICNUM

         The counter number does not fall in the range of  avail-
         able counters.





SunOS 5.11          Last change: 30 Jan 2004                    1






CPU Performance Counters Library Functions  cpc_seterrhndlr(3CPC)



     CPC_INVALID_ATTRIBUTE

         A specified attribute is not supported by the processor.


     CPC_ATTRIBUTE_OUT_OF_RANGE

         The value of an attribute is outside the range supported
         by the processor.


     CPC_RESOURCE_UNAVAIL

         A hardware resource necessary for completing  an  opera-
         tion was unavailable.


     CPC_PIC_NOT_CAPABLE

         The requested counter cannot count an assigned event.


     CPC_REQ_INVALID_FLAGS

         One or more requests has invalid flags.


     CPC_CONFLICTING_REQS

         The requests in a set  cannot  be  programmed  onto  the
         hardware at the same time.


     CPC_ATTR_REQUIRES_PRIVILEGE

         A request  contains  an  attribute  which  requires  the
         cpc_cpu privilege, which the process does not have.



     The default printing routine can be restored by calling  the
     routine with an errfn argument of NULL.

EXAMPLES
     Example 1 Debugging example.


     The following example  produces  error  messages  only  when
     debugging   the   program   containing   it,   or  when  the
     cpc_bind_curlwp(), cpc_bind_cpu(), or cpc_bind_pctx()  func-
     tions are reporting an error when binding a cpc_set_t.




SunOS 5.11          Last change: 30 Jan 2004                    2






CPU Performance Counters Library Functions  cpc_seterrhndlr(3CPC)



       int debugging;
       void
       myapp_errfn(const char *fn, int subcode, const char *fmt, va_list ap)
       {
               if (strncmp(fn, "cpc_bind", 8) != 0 && !debugging)
                   return;
               (void) fprintf(stderr, "myapp: cpc_%s(): ", fn);
               (void) vfprintf(stderr, fmt, ap);
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     cpc_bind_curlwp(3CPC), libcpc(3LIB),  vsnprintf(3C),  attri-
     butes(5)


























SunOS 5.11          Last change: 30 Jan 2004                    3