CPU Performance Counters Library Functions  cpcseterrhndlr(3CPC)



NAME
     cpcseterrhndlr - control libcpc error reporting

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

     typedef void(cpcerrhndlrt)(cpct *cpc, const char *fn, int subcode,
          const char *fmt, valist ap);


     void cpcseterrhndlr(cpct *cpc, cpcerrhndlrt *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 cpcseterrhndlr() 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:

     CPCINVALIDEVENT

         A specified event is not supported by the processor.


     CPCINVALIDPICNUM

         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  cpcseterrhndlr(3CPC)



     CPCINVALIDATRIBUTE

         A specified attribute is not supported by the processor.


     CPCATRIBUTEOUTOFRANGE

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


     CPCRESOURCEUNAVAIL

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


     CPCPICNOTCAPABLE

         The requested counter cannot count an assigned event.


     CPCREQINVALIDFLAGS

         One or more requests has invalid flags.


     CPCONFLICTINGREQS

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


     CPCATREQUIRESPRIVILEGE

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



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

EXAMPLES
     Example 1 Debugging example.


     The following example  produces  error  messages  only  when
     debugging   the   program   containing   it,   or  when  the
     cpcbindcurlwp(), cpcbindcpu(), or cpcbindpctx()  func-
     tions are reporting an error when binding a cpcsett.




SunOS 5.11          Last change: 30 Jan 2004                    2






CPU Performance Counters Library Functions  cpcseterrhndlr(3CPC)



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


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Evolving                    
    
     MT-Level                     Safe                        
    


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


























SunOS 5.11          Last change: 30 Jan 2004                    3