svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
libcollector(3)
Miscellaneous Library Functions libcollector(3)
NAME
libcollector - API for the Performance Analyzer tools collector library
SYNOPSIS
C and C++ API
#include "collectorAPI.h"
ld ... -Rlib-path -Llib-path -lcollectorAPI ... (dynamic linking)
ld ... -Llib-path -Bstatic -lcollectorAPI -Bdynamic ... (static linking)
ld ... lib-path/libcollectorAPI.a ... (static linking)
(For C++ and Fortran compilations, -L and -R are not needed.)
lib-path is described below in section "LINKING C, C++, AND FORTRAN".
void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_terminate_expt(void);
void collector_func_load(char *name, char *alias,
char *sourcename, void *vaddr, int size,
int lntsize, Lineno *lntable);
void collector_func_unload(void *vaddr);
Fortran API
include "libfcollector.h"
collector_sample(string)
character*(*) string
collector_pause()
collector_resume()
collector_terminate_expt()
Java API
import com.sun.forte.st.collector.CollectorAPI;
CollectorAPI.sample(String name);
CollectorAPI.pause();
CollectorAPI.resume();
CollectorAPI.terminate();
DESCRIPTION
The libcollector APIs described here control the behavior of data col‐
lection at runtime. The API calls have an effect only if an experiment
is being collected, and can therefore be left in the source code perma‐
nently.
The APIs for all languages include a set of functions that you can use
to record sample points in an experiment; to stop and start the record‐
ing of event-specific data in an experiment; and to terminate an exper‐
iment. The C/C++ APIs also provide a set of functions for recording
dynamically-created functions in the experiment. The Fortran and Java
APIs do not provide such functions.
APIs for Recording Sample Points
The collector_sample() and CollectorAPI.sample() functions record a
sample point when they are called and label the sample with the string
that is passed to the API function. If no experiment is active, the
call is ignored. The label is not currently used.
Sample points contain data for the process and not for individual
threads. In a multithreaded application, the collector_sample() func‐
tion ensures that it writes only one sample if another call is made to
it while it is recording a sample.
APIs for Stopping and Starting Data Recording
The collector_pause() and CollectorAPI.pause() functions turn off the
writing of event-specific data to the experiment. The action applies to
all threads. Calls to the functions are ignored if no experiment is
active, the experiment is already terminated, or writing of data is
already turned off.
The collector_resume() and CollectorAPI.resume() functions turn on the
writing of event-specific data to the experiment. The action applies to
all threads. Calls to the functions are ignored if no experiment is
active, the experiment is already terminated, or writing of data is
already turned on. In a multithreaded application, a call to pause that
is made at the same time as a call to resume in another thread can
cause incorrect information about the status of recording to be written
in the experiment log file.
APIs for Terminating an Experiment
The collector_terminate_expt() and CollectorAPI.terminate() functions
terminate the experiment whose data is being collected. No further data
is collected, but the program continues to run normally. Calls to the
function are ignored if no experiment is active or the experiment is
already terminated.
APIs for Recording Dynamically Created Functions
The C and C++ API includes a set of functions that are used to provide
information about dynamically-generated functions to the Collector:
collector_func_load() is used to pass information about dynamically-
generated functions into the Collector for
recording in the experiment.
collector_func_unload() is used to inform the Collector that the
dynamic function at the address given has been
unloaded.
These API functions are not available in Fortran or Java. The Java
HotSpot virtual machine uses a slightly different, non-public inter‐
face.
The parameters for collector_func_load() include the following:
name The name of the dynamically constructed function. This
name is the name that is used in the Functions view of
Performance Analyzer. The name need not follow any of the
normal naming conventions of functions, and they can con‐
tain embedded blanks or embedded quote characters.
alias Arbitrary string used to describe the function. It can be
NULL. The alias string is not interpreted in any way and
can contain embedded blanks. The alias is displayed in
the Selection Details panel of Performance Analyzer. You
can use it to indicate what the function is or why the
function was dynamically constructed.
sourcename Path to the source file from which the function was con‐
structed. It can be NULL.
vaddr Address at which the function was loaded.
size Size of the function in bytes.
lntsize Count of the number of entries in the line number table.
It should be zero if line number information is not pro‐
vided.
lntable Table containing lntsize entries, each of which is a pair
of integers. The first integer is an offset and the sec‐
ond interger is a line number. All instructions between
an offset in one entry and the offset given in the next
entry are attributed to the line number given in the
first entry. Offsets must be in increasing numeric order,
but the order of line numbers is arbitrary. If lntable is
NULL, no source listings of the function are possible,
although disassembly listings are available.
USAGE
Compiling With C and C++
To access the C and C++ interface,you must include collectorAPI.h in
the source file when compiling and you must link with -lcollectorAPI.
For C and C++, compile with
-Iinstallation-directory/include/cc
Compiling With Fortran
You must include libfcollector.h in the Fortran source file when com‐
piling.
For Fortran, compile with
-Iinstallation-directory/include/f95
Linking With C, C++, and Fortran
For 32-bit applications, lib-path is:
installation-directory/lib
where installation-directory is the directory in which the Oracle
Developer Studio release was installed.
For 64-bit applications, lib-path is:
installation-directory/lib/v9 (SPARC)
installation-directory/lib/amd64 (x86)
In either case, for C programs link with -Rlib-path -Llib-path in addi‐
tion to the library specification.
For C++ and Fortran compilations, -L and -R are not needed.
Using the API From Java
To use the Java API, import com.sun.forte.st.collector.CollectorAPI and
invoke the application with a classpath pointing to the following
library class file:
installation-directory/lib/analyzer/lib/collector.jar
where installation-directory is the directory in which the Oracle
Developer Studio release was installed.
You must also pass the -Djava.library.path=jlib-path argument to the
JVM so that the shared library libcollectorAPI.so can be found by the
JVM. Note that this library path is not the same as the library path
used to load libcollectorAPI.so for the native languages.
For 32-bit applications, jlib-path is:
installation-directory/lib/analyzer
where installation-directory is the directory in which the Oracle
Developer Studio release was installed.
For 64-bit applications, jlib-path is:
installation-directory/lib/analyzer/v9 (SPARC)
installation-directory/lib/analyzer/amd64 (x86)
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
tab() box; lw(2.75i) |lw(2.75i) lw(2.75i) |lw(2.75i)
ATTRIBUTE TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT-Lev‐
elMT-Safe
SEE ALSO
collect(1), collector(1), er_print(1)
Performance Analyzer manual
Studio 12.6 February 2016 libcollector(3)