TNF Library Functions tnfctlprobestateget(3TNF)
NAME
tnfctlprobestateget, tnfctlprobeenable,
tnfctlprobedisable, tnfctlprobetrace,
tnfctlprobeuntrace, tnfctlprobeconnect,
tnfctlprobedisconnectall - interfaces to query and to
change the state of a probe
SYNOPSIS
cc [ flag ... ] file ... -ltnfctl [ library ... ]
#include
tnfctlerrcodet tnfctlprobestateget(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, tnfctlprobestatet *state);
tnfctlerrcodet tnfctlprobeenable(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, void *ignored);
tnfctlerrcodet tnfctlprobedisable(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, void *ignored);
tnfctlerrcodet tnfctlprobetrace(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, void *ignored);
tnfctlerrcodet tnfctlprobeuntrace(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, void *ignored);
tnfctlerrcodet tnfctlprobedisconnectall(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, void *ignored);
tnfctlerrcodet tnfctlprobeconnect(tnfctlhandlet *hndl,
tnfctlprobet *probehndl, const char *libbasename,
const char *funcname);
DESCRIPTION
tnfctlprobestateget() returns the state of the probe
specified by probehndl in the process or kernel specified
by hndl. The user will pass these in to an apply iterator.
The caller must also allocate state and pass in a pointer to
it. The semantics of the individual members of state are:
id The unique integer assigned to
this probe. This number does not
change over the lifetime of this
probe. A probehndl can be
obtained by using the calls
SunOS 5.11 Last change: 1 Mar 2004 1
TNF Library Functions tnfctlprobestateget(3TNF)
tnfctlapply(),
tanfctlapplyids(), or
tnfctlregisterfuncs().
attrstring A string that consists of attri-
bute value pairs separated by
semicolons. For the syntax of
this string, see the syntax of
the detail argument of the
TNFPROBE(3TNF) macro. The attri-
butes name, slots, keys, file,
and line are defined for every
probe. Additional user-defined
attributes can be added by using
the detail argument of the
TNFPROBE(3TNF) macro. An example
of attrstring follows:
"name pageout;slots vnode pagespageout ;
keys vm pageio io;file vm.c;line 25;"
enabled BTRUE if the probe is enabled, or
BFALSE if the probe is disabled.
Probes are disabled by default.
Use tnfctlprobeenable() or
tnfctlprobedisable() to change
this state.
traced BTRUE if the probe is traced, or
BFALSE if the probe is not
traced. Probes in user processes
are traced by default. Kernel
probes are untraced by default.
Use tnfctlprobetrace() or
tnfctlprobeuntrace() to change
this state.
newprobe BTRUE if this is a new probe
brought in since the last change
in libraries. See dlopen(3C) or
dlclose(3C). Otherwise, the value
of newprobe will be BFALSE.
This field is not meaningful for
kernel probe control.
SunOS 5.11 Last change: 1 Mar 2004 2
TNF Library Functions tnfctlprobestateget(3TNF)
objname The name of the shared object or
executable in which the probe is
located. This string can be
freed, so the client should make a
copy of the string if it needs to
be saved for use by other
libtnfctl interfaces. In kernel
mode, this string is always NUL.
funcnames A null-terminated array of
pointers to strings that contain
the names of functions connected
to this probe. Whenever an
enabled probe is encountered at
runtime, these functions are exe-
cuted. This array also will be
freed by the library when the
state of the probe changes. Use
tnfctlprobeconnect() or
tnfctlprobedisconnectall() to
change this state.
funcaddrs A null-terminated array of
pointers to addresses of functions
in the target image connected to
this probe. This array also will
be freed by the library when the
state of the probe changes.
clientregistereddata Data that was registered by the
client for this probe by the crea-
tor function in
tnfctlregisterfuncs(3TNF).
tnfctlprobeenable(), tnfctlprobedisable(),
tnfctlprobetrace(), tnfctlprobeuntrace(), and
tnfctlprobedisconnectall() ignore the last argument. This
convenient feature permits these functions to be used in the
probeop field of tnfctlprobeapply(3TNF) and
tnfctlprobeapplyids(3TNF). tnfctlprobeenable() enables
the probe specified by probehndl. This is the master switch
on a probe. A probe does not perform any action until it is
enabled.
tnfctlprobedisable() disables the probe specified by
probehndl.
SunOS 5.11 Last change: 1 Mar 2004 3
TNF Library Functions tnfctlprobestateget(3TNF)
tnfctlprobetrace() turns on tracing for the probe speci-
fied by probehndl. Probes emit a trace record only if the
probe is traced.
tnfctlprobeuntrace() turns off tracing for the probe
specified by probehndl. This is useful if you want to con-
nect probe functions to a probe without tracing it.
tnfctlprobeconnect() connects the function funcname which
exists in the library libbasename, to the probe specified
by probehndl. tnfctlprobeconnect() returns an error code
if used on a kernel tnfctl handle. libbasename is the base
name (not a path) of the library. If it is NUL, and mul-
tiple functions in the target process match funcname, one
of the matching functions is chosen arbitrarily. A probe
function is a function that is in the target's address space
and is written to a certain specification. The specifica-
tion is not currently published.
tnfprobedebug() is one function exported by
libtnfprobe.so.1 and is the debug function that prex(1)
uses. When the debug function is executed, it prints out
the probe arguments and the value of the sunw%debug attri-
bute of the probe to stderr.
tnfctlprobedisconnectall() disconnects all probe func-
tions from the probe specified by probehndl.
Note that no libtnfctl call returns a probe handle
(tnfctlprobet), yet each of the routines described here
takes a probehndl as an argument. These routines may be
used by passing them to one of the tnfctlprobeapply(3TNF)
iterators as the "op" argument. Alternatively, probe handles
may be obtained and saved by a user's "op" function, and
they can be passed later as the probehndl argument when
using any of the functions described here.
RETURN VALUES
tnfctlprobestateget(), tnfctlprobeenable(),
tnfctlprobedisable(), tnfctlprobetrace(),
tnfctlprobeuntrace(), tnfctlprobedisconnectall() and
tnfctlprobeconnect() return TNFCTLERNONE upon success.
ERORS
The following error codes apply to
tnfctlprobestateget():
SunOS 5.11 Last change: 1 Mar 2004 4
TNF Library Functions tnfctlprobestateget(3TNF)
TNFCTLERINVALIDPROBE probehndl is no longer valid.
The library that the probe was in
could have been dynamically
closed by dlclose(3C).
The following error codes apply to tnfctlprobeenable(),
tnfctlprobedisable(), tnfctlprobetrace(),
tnfctlprobeuntrace(), and tnfctlprobedisconnectall()
TNFCTLERINVALIDPROBE probehndl is no longer valid.
The library that the probe was in
could have been dynamically
closed by dlclose(3C).
TNFCTLERBUFBROKEN Cannot do probe operations
because tracing is broken in the
target.
TNFCTLERNOBUF Cannot do probe operations until
a buffer is allocated. See
tnfctlbufferalloc(3TNF). This
error code does not apply to
kernel probe control.
The following error codes apply to tnfctlprobeconnect():
TNFCTLERINVALIDPROBE probehndl is no longer valid.
The library that the probe was in
could have been dynamically
closed by dlclose(3C).
TNFCTLERBADARG The handle is a kernel handle, or
funcname could not be found.
TNFCTLERBUFBROKEN Cannot do probe operations
because tracing is broken in the
target.
TNFCTLERNOBUF Cannot do probe operations until
a buffer is allocated. See
tnfctlbufferalloc(3TNF).
SunOS 5.11 Last change: 1 Mar 2004 5
TNF Library Functions tnfctlprobestateget(3TNF)
ATRIBUTES
See attributes(5) for description of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWtnfc
MT Level MT-Safe
SEE ALSO
prex(1), TNFPROBE(3TNF), libtnfctl(3TNF),
tnfctlchecklibs(3TNF), tnfctlcontinue(3TNF),
tnfctlprobeapply(3TNF), tnfctlprobeapplyids(3TNF),
tracing(3TNF), tnfkernelprobes(4), attributes(5)
SunOS 5.11 Last change: 1 Mar 2004 6
|
