TNF Library Functions                    tnfctlprobeapply(3TNF)



NAME
     tnfctlprobeapply, tnfctlprobeapplyids  -  iterate  over
     probes

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

     tnfctlerrcodet tnfctlprobeapply(tnfctlhandlet *hndl,
          tnfctlprobeopt probeop, void *clientdata);


     tnfctlerrcodet tnfctlprobeapplyids(tnfctlhandlet *hndl,
          ulongt probecount, ulongt *probeids,
          tnfctlprobeopt probeop, void *clientdata);


DESCRIPTION
     tnfctlprobeapply() is used to iterate over the probes con-
     trolled  by  hndl. For every probe, the probeop function is
     called:

       typedef tnfctlerrcodet (*tnfctlprobeopt)(
            tnfctlhandlet *hndl,
            tnfctlprobet *probehndl,
            void *clientdata);



     Several  predefined  functions  are  available  for  use  as
     probeop.     These     functions     are    described    in
     tnfctlprobestateget(3TNF).


     The clientdata supplied in tnfctlprobeapply() is passed in
     as  the  last  argument  of  probeop. The probehndl in the
     probe operation function can be used to query or change  the
     state  of  the probe.  See tnfctlprobestateget(3TNF). The
     probeop function should return  TNFCTLERNONE  upon  suc-
     cess.   It  can also return an error code,  which will cause
     tnfctlprobeapply() to stop  processing  the  rest  of  the
     probes  and return with the same error code. Note that there
     are five (5) error codes reserved  that the client  can  use
     for its own semantics. See  ERORS.


     The lifetime of probehndl is the same as  the  lifetime  of
     hndl. It is good until hndl is closed by tnfctlclose(3TNF).
     Do not confuse a probehndl with hndl. The probehndl refers
     to a particular probe, while hndl refers to a process or the
     kernel. If probehndl is  used  in  another  libtnfctl(3TNF)
     interface,  and  it references a probe in a library that has



SunOS 5.11           Last change: 1 Mar 2004                    1






TNF Library Functions                    tnfctlprobeapply(3TNF)



     been  dynamically closed (see dlclose(3C)), then  the  error
     code TNFCTLERINVALIDPROBE will be returned by that inter-
     face.


     tnfctlprobeapplyids()     is     very     similar      to
     tnfctlprobeapply().  The  difference  is  that probeop is
     called only for probes that match a probe  id  specified  in
     the array of integers referenced by probeids. The number of
     probe ids in the array should be specified  in  probecount.
     Use   tnfctlprobestateget()  to  get  the   probeid that
     corresponds to the probehandl.

RETURN VALUES
     tnfctlprobeapply()  and  tnfctlprobeapplyids()   return
     TNFCTLERNONE upon success.

ERORS
     The following errors apply to both tnfctlprobeapply()  and
     tnfctlprobeapplyids():

     TNFCTLERINTERNAL    An internal error occurred.


     TNFCTLERUSR1        Error code reserved for user.


     TNFCTLERUSR2        Error code reserved for user.


     TNFCTLERUSR3        Error code reserved for user.


     TNFCTLERUSR4        Error code reserved for user.


     TNFCTLERUSR5        Error code reserved for user.



     tnfctlprobeapply()  and    tnfctlprobeapplyids()   also
     return any error returned by the callback function probeop.


     The      following      errors      apply      only       to
     tnfctlprobeapplyids():

     TNFCTLERINVALIDPROBE    The probe  handle  is  no  longer
                                valid.  For example, the probe is
                                in  a   library  that  has   been
                                closed by dlclose(3C).




SunOS 5.11           Last change: 1 Mar 2004                    2






TNF Library Functions                    tnfctlprobeapply(3TNF)



EXAMPLES
     Example 1 Enabling Probes


     To enable all probes:


       tnfctlprobeapply(hndl, tnfctlprobeenable, NUL);


     Example 2 Disabling Probes


     To disable the probes that match a certain  pattern  in  the
     probe attribute string:


       /* To disable all probes that contain the string "vm" */
       tnfctlprobeapply(hndl, selectdisable, "vm");
       static tnfctlerrcodet
       selectdisable(tnfctlhandlet *hndl, tnfctlprobet *probehndl,
       void *clientdata)
       {
            char *pattern = clientdata;
            tnfctlprobestatet probestate;
            tnfctlprobestateget(hndl, probehndl, &probestate);
            if (strstr(probestate.attrstring, pattern)) {
                 tnfctlprobedisable(hndl, probehndl, NUL);
            }
       }



     Note that these examples do  not  have  any  error  handling
     code.


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















SunOS 5.11           Last change: 1 Mar 2004                    3






TNF Library Functions                    tnfctlprobeapply(3TNF)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWtnfc                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     prex(1),    TNFPROBE(3TNF),    dlclose(3C),     dlopen(3C),
     libtnfctl(3TNF),                         tnfctlclose(3TNF),
     tnfctlprobestateget(3TNF),                 tracing(3TNF),
     tnfkernelprobes(4), attributes(5)


     Linker and Libraries Guide






































SunOS 5.11           Last change: 1 Mar 2004                    4