1tnfctl_internal_open(3TNF)   TNF Library Functions  tnfctl_internal_open(3TNF)
2
3
4

NAME

6       tnfctl_internal_open - create handle for internal process probe control
7

SYNOPSIS

9       cc [ flag ... ] file ... -ltnfctl [ library ... ]
10       #include <tnf/tnfctl.h>
11
12
13
14       tnfctl_errcode_t tnfctl_internal_open(tnfctl_handle_t **ret_val);
15
16

DESCRIPTION

18       tnfctl_internal_open() returns in ret_val a pointer to an opaque handle
19       that can be used to control probes in the same process  as  the  caller
20       (internal  process  probe  control).  The  process  must  have  libtnf‐
21       probe.so.1  loaded.  Probes  in  libraries  that  are  brought  in   by
22       dlopen(3C) will be visible after the library has been opened. Probes in
23       libraries closed by a dlclose(3C) will not be visible after the library
24       has been disassociated.  See the NOTES section for more details.
25

RETURN VALUES

27       tnfctl_internal_open() returns TNFCTL_ERR_NONE upon success.
28

ERRORS

30       TNFCTL_ERR_ALLOCFAIL        A memory allocation failure occurred.
31
32
33       TNFCTL_ERR_BUSY             Another client is already tracing this pro‐
34                                   gram (internally or externally).
35
36
37       TNFCTL_ERR_NOLIBTNFPROBE    libtnfprobe.so.1 is not linked in the  tar‐
38                                   get process.
39
40
41       TNFCTL_ERR_INTERNAL         An internal error occurred.
42
43

ATTRIBUTES

45       See attributes(5) for descriptions of the following attributes:
46
47
48
49
50       ┌─────────────────────────────┬─────────────────────────────┐
51       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
52       ├─────────────────────────────┼─────────────────────────────┤
53       │Availability                 │SUNWtnfc                     │
54       ├─────────────────────────────┼─────────────────────────────┤
55       │MT Level                     │MT-Safe                      │
56       └─────────────────────────────┴─────────────────────────────┘
57

SEE ALSO

59       ld(1),   prex(1),   TNF_PROBE(3TNF),  dlopen(3C),  dlclose(3C),  libtn‐
60       fctl(3TNF), tracing(3TNF), attributes(5)
61
62
63       Linker and Libraries Guide
64

NOTES

66       libtnfctl interposes on dlopen(3C) and dlclose(3C) in order to be noti‐
67       fied  of libraries being dynamically opened and closed. This interposi‐
68       tion is necessary for internal process probe control to update its list
69       of probes. In these interposition functions, a lock is acquired to syn‐
70       chronize on traversal of the library list  maintained  by  the  runtime
71       linker.   To  avoid  deadlocking  on  this lock, tnfctl_internal_open()
72       should not be called from within the init section of a library that can
73       be opened by dlopen(3C).
74
75
76       Since  interposition does not work as expected when a library is opened
77       dynamically, tnfctl_internal_open() should not be used  if  the  client
78       opened  libtnfctl through  dlopen(3C). In this case, the client program
79       should be built with a static dependency on  libtnfctl.  Also,  if  the
80       client  program  is explicitly linking in -ldl, it should link -ltnfctl
81       before -ldl.
82
83
84       Probes in filtered libraries (see ld(1)) will not be seen  because  the
85       filtee (backing library) is loaded lazily on the first symbol reference
86       and not at process startup or dlopen(3C) time. A workaround is to  call
87       tnfctl_check_libs(3TNF)  once  the  caller  is sure that the filtee has
88       been loaded.
89
90
91
92SunOS 5.11                        1 Mar 2004        tnfctl_internal_open(3TNF)
Impressum