TNF Library Functions                  tnfctlinternalopen(3TNF)



NAME
     tnfctlinternalopen - create handle  for  internal  process
     probe control

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



     tnfctlerrcodet tnfctlinternalopen(tnfctlhandlet **retval);


DESCRIPTION
     tnfctlinternalopen() returns in retval a  pointer  to  an
     opaque handle that can be used to control probes in the same
     process as the caller (internal process probe control).  The
     process   must  have   libtnfprobe.so.1  loaded.  Probes  in
     libraries that are brought in by dlopen(3C) will be  visible
     after  the  library  has  been  opened.  Probes in libraries
     closed by a  dlclose(3C)  will  not  be  visible  after  the
     library  has  been disassociated.  See the NOTES section for
     more details.

RETURN VALUES
     tnfctlinternalopen() returns TNFCTLERNONE upon success.

ERORS
     TNFCTLERALOCFAIL        A  memory   allocation   failure
                                 occurred.


     TNFCTLERBUSY             Another client is already  trac-
                                 ing  this program (internally or
                                 externally).


     TNFCTLERNOLIBTNFPROBE    libtnfprobe.so.1 is  not  linked
                                 in the target process.


     TNFCTLERINTERNAL         An internal error occurred.


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








SunOS 5.11           Last change: 1 Mar 2004                    1






TNF Library Functions                  tnfctlinternalopen(3TNF)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Availability                 SUNWtnfc                    
    
     MT Level                     MT-Safe                     
    


SEE ALSO
     ld(1), prex(1),  TNFPROBE(3TNF),  dlopen(3C),  dlclose(3C),
     libtnfctl(3TNF), tracing(3TNF), attributes(5)


     Linker and Libraries Guide

NOTES
     libtnfctl interposes on dlopen(3C) and dlclose(3C) in  order
     to  be  notified  of  libraries being dynamically opened and
     closed. This interposition is necessary for internal process
     probe  control to update its list of probes. In these inter-
     position functions, a lock is  acquired  to  synchronize  on
     traversal  of  the  library  list  maintained by the runtime
     linker.    To    avoid    deadlocking    on    this    lock,
     tnfctlinternalopen()  should not be called from within the
     init section of a library that can be opened by dlopen(3C).


     Since interposition does not work as expected when a library
     is  opened dynamically, tnfctlinternalopen() should not be
     used if the client opened  libtnfctl through  dlopen(3C). In
     this  case, the client program should be built with a static
     dependency on libtnfctl. Also,  if  the  client  program  is
     explicitly  linking  in -ldl, it should link -ltnfctl before
     -ldl.


     Probes in filtered libraries (see ld(1)) will  not  be  seen
     because the filtee (backing library) is loaded lazily on the
     first  symbol  reference  and  not  at  process  startup  or
     dlopen(3C)     time.     A    workaround    is    to    call
     tnfctlchecklibs(3TNF) once the caller  is  sure  that  the
     filtee has been loaded.












SunOS 5.11           Last change: 1 Mar 2004                    2