diff options
author | Toomas Soome <tsoome@me.com> | 2021-09-12 13:43:58 +0300 |
---|---|---|
committer | Toomas Soome <tsoome@me.com> | 2022-08-30 19:09:40 +0300 |
commit | 2570281cf351044b6936651ce26dbe1f801dcbd8 (patch) | |
tree | 54957dc5692258b6308df50c8d0f73a334421091 /usr/src/man | |
parent | 2ec63ffb3ec249bd7cb4523118c8437e6c6be335 (diff) | |
download | illumos-joyent-2570281cf351044b6936651ce26dbe1f801dcbd8.tar.gz |
14079 remove TNF
Reviewed by: Gordon Ross <gordon.w.ross@gmail.com>
Reviewed by: Igor Kozhukhov <igor@dilos.org>
Approved by: Garrett D'Amore <garrett@damore.org>
Diffstat (limited to 'usr/src/man')
28 files changed, 1 insertions, 6610 deletions
diff --git a/usr/src/man/Makefile b/usr/src/man/Makefile index fe86625dfd..fd58b2ab30 100644 --- a/usr/src/man/Makefile +++ b/usr/src/man/Makefile @@ -80,7 +80,6 @@ SUBDIRS= man1 \ man3stmf \ man3sysevent \ man3tecla \ - man3tnf \ man3tsol \ man3utempter \ man3uuid \ diff --git a/usr/src/man/man1/Makefile b/usr/src/man/man1/Makefile index e98c187773..df95ce213d 100644 --- a/usr/src/man/man1/Makefile +++ b/usr/src/man/man1/Makefile @@ -290,7 +290,6 @@ MANFILES= acctcom.1 \ praliases.1 \ prctl.1 \ preap.1 \ - prex.1 \ print.1 \ printf.1 \ priocntl.1 \ @@ -373,8 +372,6 @@ MANFILES= acctcom.1 \ times.1 \ timex.1 \ tip.1 \ - tnfdump.1 \ - tnfxtract.1 \ touch.1 \ tput.1 \ tr.1 \ diff --git a/usr/src/man/man1/prex.1 b/usr/src/man/man1/prex.1 deleted file mode 100644 index 201ebc68c9..0000000000 --- a/usr/src/man/man1/prex.1 +++ /dev/null @@ -1,1032 +0,0 @@ -'\" te -.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH PREX 1 "Mar 1, 2004" -.SH NAME -prex \- control tracing and manipulate probe points in a process or the kernel -.SH SYNOPSIS -.LP -.nf -\fBprex\fR [\fB-o\fR \fItrace_file_name\fR] [\fB-l\fR \fIlibraries\fR] [\fB-s\fR \fIkbytes_size\fR] \fIcmd\fR - [\fIcmd-args\fR]... -.fi - -.LP -.nf -\fBprex\fR [\fB-o\fR \fItrace_file_name\fR] [\fB-l\fR \fIlibraries\fR] [\fB-s\fR \fIkbytes_size\fR] \fB-p\fR \fIpid\fR -.fi - -.LP -.nf -\fBprex\fR \fB-k\fR [\fB-s\fR \fIkbytes_size\fR] -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBprex\fR command is the part of the Solaris tracing architecture that -controls probes in a process or the kernel. See \fBtracing\fR(3TNF) for an -overview of this tracing architecture, including example source code using it. -.sp -.LP -\fBprex\fR is the application used for external control of probes. It -automatically preloads the \fBlibtnfprobe\fR library. \fBprex\fR locates all -the probes in a target executable or the kernel and provides an interface for -the user to manipulate them. It allows a probe to be turned on for tracing, -debugging, or both. Tracing generates a \fBTNF\fR (Trace Normal Form) trace -file that can be converted to \fBASCII\fR by \fBtnfdump\fR(1) and used for -performance analysis. Debugging generates a line to standard error whenever the -probe is hit at run time. -.sp -.LP -\fBprex\fR does not work on static executables. It only works on dynamic -executables. -.SS "Invoking prex" -.sp -.LP -There are three ways to invoke \fBprex\fR: -.RS +4 -.TP -1. -Use \fBprex\fR to start the target application \fIcmd\fR. In this case, the -target application need not be built with a dependency on \fBlibtnfprobe\fR. -See \fBTNF_PROBE\fR(3TNF). \fBprex\fR sets the environment variable -\fBLD_PRELOAD\fR to load \fBlibtnfprobe\fR into the target process. See -\fBld\fR(1). \fBprex\fR then uses the environment variable \fBPATH\fR to find -the target application. -.RE -.RS +4 -.TP -2. -Attach \fBprex\fR to a running application. In this case, the running target -application should have \fBlibtnfprobe\fR already linked in. Alternatively, the -user may manually set \fBLD_PRELOAD\fR to include \fBlibtnfprobe.so.1\fR prior -to invoking the target. -.RE -.RS +4 -.TP -3. -Use \fBprex\fR with the \fB-k\fR option to set \fBprex\fR to \fBkernel -mode\fR. \fBprex\fR can then be used to control probes in the Solaris kernel. -In kernel mode, additional commands are defined, and some commands that are -valid in other modes are invalid. See \fBKernel\fR \fBMode\fR below. -.RE -.SS "Control File Format and Command Language" -.sp -.LP -In a future release of \fBprex\fR, the command language may be moved to a -syntax that is supported by an existing scripting language like \fBksh\fR(1). -In the meantime, the interface to \fBprex\fR is uncommitted. -.RS +4 -.TP -.ie t \(bu -.el o -Commands should be in \fBASCII\fR. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Each command is terminated with the NEWLINE character. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -A command can be continued onto the next line by ending the previous line with -the backslash ("\fB\e\fR") character. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Tokens in a command must be separated by whitespace (one or more spaces or -tabs). -.RE -.RS +4 -.TP -.ie t \(bu -.el o -The "\fB#\fR" character implies that the rest of the line is a comment. -.RE -.SS "Basic prex Commands" -.sp - -.sp -.TS -c c -l l . -Command Result -_ -% \fBprex a.out\fR T{ -Attaches \fBprex\fR to your program and starts \fBprex\fR. -T} -prex> \fBenable $all\fR Enables all the probes. -prex> \fBquit resume\fR T{ -Quits \fBprex\fR and resumes execution of program. -T} -.TE - -.SS "Control File Search Path" -.sp -.LP -There are two different methods of communicating with \fBprex\fR: -.RS +4 -.TP -.ie t \(bu -.el o -By specifications in a control file. During start-up, \fBprex\fR searches for a -file named \fB\&.prexrc\fR in the directories specified below. \fBprex\fR does -not stop at the first one it finds. This way a user can override any defaults -that are set up. The search order is: -.sp -.in +2 -.nf -$HOME/ -\&./ -.fi -.in -2 -.sp - -.RE -.RS +4 -.TP -.ie t \(bu -.el o -By typing commands at the \fBprex\fR prompt. -.RE -.sp -.LP -The command language for both methods is the same and is specified in USAGE. -The commands that return output will not make sense in a control file. The -output will go to standard output. -.sp -.LP -When using \fBprex\fR on a target process, the target will be in one of two -states, running or stopped. This can be detected by the presence or absence of -the \fBprex>\fR prompt. If the prompt is absent, it means that the target -process is running. Typing Control-C will stop the target pr ocess and return -the user to the prompt. There is no guarantee that Control-C will return to a -\fBprex\fR prompt immediately. For example, if the target process is stopped on -a job control stop (\fBSIGSTOP\fR), then Control-C in \fBprex\fR will wait -until the target has been continued (\fBSIGCONT\fR). See \fBSignals to Target -Program\fR below for more information on signals and the target process. -.SH OPTIONS -.sp -.LP -The following options are supported: -.sp -.ne 2 -.na -\fB\fB-k\fR\fR -.ad -.RS 22n -\fBkernel mode\fR: \fBprex\fR is used to control probes in the Solaris kernel. -In kernel mode, additional commands are defined, and some commands valid in -other modes are invalid. See \fBKernel Mode\fR below. -.RE - -.sp -.ne 2 -.na -\fB\fB-l\fR \fIlibraries\fR\fR -.ad -.RS 22n -The \fIlibraries\fR mentioned are linked in to the target application using -\fBLD_PRELOAD\fR (see \fBld\fR(1)). This option cannot be used when attaching -to a running process. The argument to the \fB-l\fR option should be a -space-separated string enclosed in double quotes. Each token in the string is a -library name. It follows the \fBLD_PRELOAD\fR rules on how libraries should be -specified and where they will be found. -.RE - -.sp -.ne 2 -.na -\fB\fB-o\fR \fItrace_file_name\fR\fR -.ad -.RS 22n -File to be used for the trace output. \fItrace_file_name\fR is assumed to be -relative to the current working directory of \fBprex\fR (that is, the directory -that the user was in when \fBprex\fR was started). -.sp -If \fBprex\fR attaches to a process that is already tracing, the new -\fItrace_file_name\fR (if provided) will not be used. If no -\fItrace_file_name\fR is specified, the default is -\fB/$TMPDIR/trace-\fR\fIpid\fR where \fIpid\fR is the process id of the target -program. If \fBTMPDIR\fR is not set, \fB/tmp\fR is used. -.RE - -.sp -.ne 2 -.na -\fB\fB-s\fR \fIkbytes_size\fR\fR -.ad -.RS 22n -Maximum size of the output trace file in Kbytes. The default size of the trace -\fIkbytes_size\fR is \fB4096\fR (2^10) bytes or \fB4\fR Mbytes for normal -usage, and \fB384\fR or \fB384\fR kbytes in kernel mode. The minimum size that -can be specified is \fB128\fR Kbytes. The trace file can be thought of as a -least recently used circular buffer. Once the file has been filled, newer -events will overwrite the older ones. -.RE - -.SH USAGE -.sp -.LP -This section describes the usage of the \fBprex\fR utility. -.SS "Grammar" -.sp -.LP -Probes are specified by a list of space-separated selectors. Selectors are of -the form: -.sp -.in +2 -.nf -\fIattribute\fR=\fIvalue\fR -.fi -.in -2 - -.sp -.LP -(See \fBTNF_PROBE\fR(3TNF)). The "\fIattribute\fR=" is optional. If it is not -specified, it defaults to "\fBkeys=\fR". -.sp -.LP -The \fIattribute\fR or \fIvalue\fR (generically called "spec") can be any of -the following: -.sp -.ne 2 -.na -\fB\fBIDENT\fR\fR -.ad -.RS 14n -Any sequence of letters, digits, _\|, \e\|, ., % not beginning with a digit. -\fBIDENT\fR implies an exact match. -.RE - -.sp -.ne 2 -.na -\fB\fBQUOTED_STR\fR\fR -.ad -.RS 14n -Usually used to escape reserved words (any commands in the command language). -\fBQUOTED_STR\fR implies an exact match and has to be enclosed in single quotes -(' '). -.RE - -.sp -.ne 2 -.na -\fB\fBREGEXP\fR\fR -.ad -.RS 14n -An \fBed\fR(1) regular expression pattern match. \fBREGEXP\fR has to be -enclosed in slashes (/ /), A / can be included in a \fBREGEXP\fR by escaping it -with a backslash \e\|. -.RE - -.sp -.LP -The following grammar explains the syntax. -.sp -.in +2 -.nf -selector_list ::= | /* empty */ - \fIselector_list\fR \fIselector\fR -selector ::= \fIspec\fR=\fIspec\fR | /* whitespace around `=' opt */ - \fIspec\fR -spec ::= IDENT | - QUOTED_STR | - REGEXP -.fi -.in -2 - -.sp -.LP -The terminals in the above grammar are: -.sp -.in +2 -.nf -IDENT = [a-zA-Z_\e.%]{[a-zA-Z0-9_\e.%]}+ -QUOTED_STR = '[^\en']*' /* any string in single quotes */ -REGEXP = /[^\en/]*/ /* regexp's have to be in / / */ -.fi -.in -2 - -.sp -.LP -This is a list of the remaining grammar that is needed to understand the syntax -of the command language (defined in next subsection): -.sp -.in +2 -.nf -filename ::= QUOTED_STR /* QUOTED_STR defined above */ -spec_list ::= /* empty */ | - \fIspec_list\fR \fIspec\fR /* \fIspec\fR defined above */ -fcn_handle ::= &IDENT /* IDENT defined above */ -set_name ::= $IDENT /* IDENT defined above */ -.fi -.in -2 - -.SS "Command Language" -.RS +4 -.TP -1. -Set Creation and Set Listing -.sp -.in +2 -.nf -\fBcreate $\fIset_name\fR \fIselector_list\fR -list sets # list the defined sets\fR -.fi -.in -2 -.sp - -\fBcreate\fR can be used to define a set which contains probes that match the -\fIselector_list\fR. The set \fB$all\fR is pre-defined as /.*/ and it matches -all the probes. -.RE -.RS +4 -.TP -2. -Function Listing -.sp -.in +2 -.nf -\fBlist fcns # list the available \fIfcn_handle\fR\fR -.fi -.in -2 -.sp - -The user can list the different functions that can be connected to probe -points. Currently, only the debug function called \fB&debug\fR is available. -.RE -.RS +4 -.TP -3. -Commands to Connect and Disconnect Probe Functions -.sp -.in +2 -.nf -\fBconnect &\fIfcn_handle\fR $\fIset_name\fR -connect &\fIfcn_handle\fR \fIselector_list\fR -clear $\fIset_name\fR -clear \fIselector_list\fR\fR -.fi -.in -2 -.sp - -The \fBconnect\fR command is used to connect probe functions (which must be -prefixed by `\fB&\fR\&') to probes. The probes are specified either as a single -set (with a `\fB$\fR'), or by explicitly listing the probe selectors in the -command. The probe function has to be one that is listed by the \fBlist fcns\fR -command. This command does not enable the probes. -.sp -The \fBclear\fR command is used to disconnect all connected probe functions -from the specified probes. -.RE -.RS +4 -.TP -4. -Commands to Toggle the Tracing Mode -.sp -.in +2 -.nf -\fBtrace $\fIset_name\fR -trace \fIselector_list\fR -untrace $\fIset_name\fR -untrace \fIselector_list\fR\fR -.fi -.in -2 -.sp - -The \fBtrace\fR and \fBuntrace\fR commands are used to toggle the tracing -action of a probe point (that is, whether a probe will emit a trace record or -not if it is hit). This command does not enable the probes specified. Probes -have tracing on by default. The most efficient way to turn off tracing is by -using the \fBdisable\fR command. \fBuntrace\fR is useful if you want debug -output but no tracing. If so, set the state of the probe to enabled, untraced, -and the debug function connected. -.RE -.RS +4 -.TP -5. -Commands to Enable and Disable Probes -.sp -.in +2 -.nf -\fBenable $\fIset_name\fR -enable \fIselector_list\fR -disable $\fIset_name\fR -disable \fIselector_list\fR\fR -.fi -.in -2 -.sp - -The \fBenable\fR and \fBdisable\fR commands are used to control whether the -probes perform the action that they have been set up for. To trace a probe, it -has to be both enabled and traced (using the \fBtrace\fR command). Probes are -disabled by default. The \fBlist history\fR command is used to list the probe -control commands issued: \fBconnect\fR, \fBclear\fR, \fBtrace\fR, -\fBuntrace\fR, \fBenable\fR, and \fBdisable\fR. These are the commands that -are executed whenever a new shared object is brought in to the target program -by \fBdlopen\fR(3C). See the subsection, \fBdlopen'ed Libraries\fR, below for -more information. -.sp -The following table shows the actions that result from specific combinations of -tracing, enabling, and connecting: -.sp -.in +2 -.nf -Enabled or Tracing State Debug State Results -Disabled (On/Off) (Connected/Cleared) In ------------------------------------------------------------- -Enabled On Connected Tracing and - Debugging - -Enabled On Cleared Tracing only - -Enabled Off Connected Debugging only - -Enabled Off Cleared Nothing - -Disabled On Connected Nothing - -Disabled On Cleared Nothing - -Disabled Off Connected Nothing - -Disabled Off Cleared Nothing -.fi -.in -2 -.sp - -.RE -.RS +4 -.TP -6. -List History -.sp -.in +2 -.nf -\fBlist history # lists probe control command history\fR -.fi -.in -2 -.sp - -The \fBlist history\fR command displays a list of the probe control commands -previously issued in the tracing session, for example, \fBconnect\fR, -\fBclear\fR, \fBtrace\fR, \fBdisable\fR. Commands in the history list are -executed wherever a new shared object is brought into the target program by -\fBdlopen\fR(3C). -.RE -.RS +4 -.TP -7. -Commands to List Probes, List Values, or List Trace File Name -.sp -.in +2 -.nf -\fBlist \fIspec_list\fR probes $\fIset_name\fR # list probes $all -list \fIspec_list\fR probes \fIselector_list\fR # list name probes file=test.c -list values \fIspec_list\fR # list values keys given in \fIspec_list\fR -list tracefile # list tracefile\fR -.fi -.in -2 -.sp - -The first two commands list the selected attributes and values of the specified -probes. They can be used to check the state of a probe. The third command lists -the various values associated with the selected attributes. The fourth command -lists the current tracefile. -.RE -.RS +4 -.TP -8. -Help Command -.sp -.in +2 -.nf -\fBhelp \fItopic\fR\fR -.fi -.in -2 -.sp - -To get a list of the help topics that are available, invoke the \fBhelp\fR -command with no arguments. If a \fItopic\fR argument is specified, help is -printed for that topic. -.RE -.RS +4 -.TP -9. -Source a File -.sp -.in +2 -.nf -\fBsource \fIfilename\fR\fR -.fi -.in -2 -.sp - -The \fBsource\fR command can be used to source a file of \fBprex\fR commands. -\fBsource\fR can be nested (that is, a file can source another file). -\fIfilename\fR is a quoted string. -.RE -.RS +4 -.TP -10. -Process Control -.sp -.in +2 -.nf -\fBcontinue # resumes the target process -quit kill # quit prex, kill target -quit resume # quit prex, continue target -quit suspend # quit prex, leave target suspended -quit # quit prex (continue or kill target)\fR -.fi -.in -2 -.sp - -The default \fBquit\fR will continue the target process if \fBprex\fR attached -to it. Instead, if \fBprex\fR had started the target program, \fBquit\fR will -kill the target process. -.RE -.SS "dlopen'ed Libraries" -.sp -.LP -Probes in shared objects that are brought in by \fBdlopen\fR(3C) are -automatically set up according to the command history of \fBprex\fR. When a -shared object is removed by a \fBdlclose\fR(3C), \fBprex\fR again needs to -refresh its understanding of the probes in the target program. This implies -that there is more work to do for \fBdlopen\fR(3C) and \fBdlclose\fR(3C) \(emso -they will take slightly longer. If a user is not interested in this feature and -doesn't want to interfere with \fBdlopen\fR(3C) and \fBdlclose\fR(3C), detach -\fBprex\fR from the target to inhibit this feature. -.SS "Signals to Target Program" -.sp -.LP -\fBprex\fR does not interfere with signals that are delivered directly to the -target program. However, \fBprex\fR receives all signals normally generated -from the terminal, for example, Control-C (\fBSIGINT\fR), and Control-Z -(\fBSIGSTOP\fR), and does not forward them to the target program. To signal the -target program, use the \fBkill\fR(1) command from a shell. -.SS "Interactions with Other Applications" -.sp -.LP -Process managing applications like \fBdbx\fR, \fBtruss\fR(1), and \fBprex\fR -cannot operate on the same target program simultaneously. \fBprex\fR will not -be able to attach to a target which is being controlled by another application. -A user can trace and debug a program serially by the following method: first -attach \fBprex\fR to target (or start target through \fBprex\fR), set up the -probes using the command language, and then type \fBquit suspend\fR. The user -can then attach \fBdbx\fR to the suspended process and debug it. A user can -also suspend the target by sending it a \fBSIGSTOP\fR signal, and then by -typing \fBquit resume\fR to \fBprex\fR. In this case, the user should also send -a \fBSIGCONT\fR signal after invoking \fBdbx\fR on the stopped process (else -\fBdbx\fR will be hung). -.SS "Failure of Event Writing Operations" -.sp -.LP -There are a few failure points that are possible when writing out events to a -trace file, for example, system call failures. These failures result in a -failure code being set in the target process. The target process continues -normally, but no trace records are written. Whenever a user enters Control-C to -\fBprex\fR to get to a \fBprex\fR prompt, \fBprex\fR will check the failure -code in the target and inform the user if there was a tracing failure. -.SS "Target Executing a Fork or exec" -.sp -.LP -If the target program does a \fBfork\fR(2), any probes that the child -encounters will cause events to be logged to the same trace file. Events are -annotated with a process id, so it will be possible to determine which process -a particular event came from. In multi-threaded programs, there is a race -condition with a thread doing a fork while the other threads are still running. -For the trace file not to get corrupted, the user should either use -\fBfork1\fR(2), or make sure that all other threads are quiescent when doing a -.BR fork (2), -.sp -.LP -If the target program itself (not any children it may \fBfork\fR(2)) does an -\fBexec\fR(2), \fBprex\fR detaches from the target and exits. The user can -reconnect \fBprex\fR with \fBprex\fR \fB-p\fR \fIpid\fR. -.sp -.LP -A \fBvfork\fR(2) is generally followed quickly by an \fBexec\fR(2) in the -child, and in the interim, the child borrows the parent's process while the -parent waits for the \fBexec\fR(2). Any events logged by the child from the -parent process will appear to have been logged by the parent. -.SS "Kernel Mode" -.sp -.LP -Invoking \fBprex\fR with the \fB-k\fR flag causes \fBprex\fR to run in -\fBkernel mode\fR. In kernel mode, \fBprex\fR controls probes in the Solaris -kernel. See \fBtnf_kernel_probes\fR(5) for a list of available probes in the -Solaris kernel. A few \fBprex\fR commands are unavailable in kernel mode; many -other commands are valid in kernel mode only. -.sp -.LP -The \fB-l\fR, \fB-o\fR, and \fB-p\fR command-line options are not valid in -kernel mode (that is, they may not be combined with the \fB-k\fR flag). -.sp -.LP -The rest of this section describes the differences in the \fBprex\fR command -language when running \fBprex\fR in kernel mode. -.RS +4 -.TP -1. -\fBprex\fR will not stop the kernel -.sp -When \fBprex\fR attaches to a running user program, it stops the user program. -Obviously, it cannot do this when attaching to the kernel. Instead, \fBprex\fR -provides a ``tracing master switch'': no probes will have any effect unless the -tracing master switch is on. This allows the user to iteratively select probes -to enable, then enable them all at once by turning on the master switch. -.sp -The command -.sp -.in +2 -.nf -\fBktrace [ on | off ]\fR -.fi -.in -2 -.sp - -is used to inspect and set the value of the master switch. Without an argument, -\fBprex\fR reports the current state of the master switch. -.sp -Since \fBprex\fR will not stop or kill the kernel, the -.sp -.in +2 -.nf -\fBquit resume\fR -.fi -.in -2 -.sp - -and -.sp -.in +2 -.nf -\fBquit kill\fR -.fi -.in -2 -.sp - -commands are not valid in kernel mode. -.RE -.RS +4 -.TP -2. -No functions may be attached to probes in the kernel -.sp -In particular, the debug function is unavailable in kernel mode. -.RE -.RS +4 -.TP -3. -Trace output is written to an in-core buffer -.sp -In kernel mode, a trace output file is not generated directly, in order to -allow probes to be placed in time-critical code. Instead, trace output is -written to an in-core buffer, and copied out by a separate program, -\fBtnfxtract\fR(1). -.sp -The in-core buffer is not automatically created. The following \fBprex\fR -command controls buffer allocation and deallocation: -.sp -.in +2 -.nf -\fBbuffer [ alloc [ \fIsize\fR ] | dealloc ]\fR -.fi -.in -2 -.sp - -Without an argument, the \fBbuffer\fR command reports the size of the currently -allocated buffer, if any. With an argument of \fBalloc\fR [\fIsize\fR], -\fBprex\fR allocates a buffer of the given size. \fIsize\fR is in bytes, with -an optional suffix of '\fBk\fR' or '\fBm\fR' specifying a multiplier of -\fB1024\fR or \fB1048576\fR, respectively. If no \fIsize\fR is specified, the -\fIsize\fR specified on the command line with the \fB-s\fR option is used as a -default. If the \fB-s\fR command line option was not used, the ``default -default'' is 384 kilobytes. -.sp -With an argument of \fBdealloc\fR, \fBprex\fR deallocates the trace buffer in -the kernel. -.sp -\fBprex\fR will reject attempts to turn the tracing master switch on when no -buffer is allocated, and to deallocate the buffer when the tracing master -switch is on. \fBprex\fR will refuse to allocate a buffer when one is already -allocated; use \fBbuffer dealloc\fR first. -.sp -\fBprex\fR will not allocate a buffer larger than one-half of a machine's -physical memory. -.RE -.RS +4 -.TP -4. -\fBprex\fR supports per-process probe enabling in the kernel -.sp -In kernel mode, it is possible to select a set of processes for which probes -are enabled. No trace output will be written when other processes traverse -these probe points. This is called "process filter mode". By default, process -filter mode is off, and all processes cause the generation of trace records -when they hit an enabled probe. -.sp -Some kernel events such as interrupts cannot be associated with a particular -user process. By convention, these events are considered to be generated by -process id 0. -.sp -\fBprex\fR provides commands to turn process filter mode on and off, to get the -current status of the process filter mode switch, to add and delete processes -(by process id) from the process filter set, and to list the current process -filter set. -.sp -The process filter set is maintained even when process filter mode is off, but -has no effect unless process filter mode is on. -.sp -When a process in the process filter set exits, its process id is automatically -deleted from the process filter set. -.sp -The command: -.sp -.in +2 -.nf -\fBpfilter [ on | off | add \fIpidlist\fR | delete \fIpidlist\fR ]\fR -.fi -.in -2 -.sp - -controls the process filter switch, and process filter set membership. With no -arguments, \fBpfilter\fR prints the current process filter set and the state of -the process filter mode switch: -.sp -.ne 2 -.na -\fB\fBon\fR or \fBoff\fR\fR -.ad -.RS 18n -set the state of the process filter mode switch. -.RE - -.sp -.ne 2 -.na -\fB\fBadd\fR \fIpidlist\fR\fR -.ad -.br -.na -\fB\fBdelete\fR \fIpidlist\fR\fR -.ad -.RS 18n -add or delete processes from the process filter set. \fIpidlist\fR is a -comma-separated list of one or more process ids. -.RE - -.RE -.SH EXAMPLES -.sp -.LP -See \fBtracing\fR(3TNF) for complete examples showing, among other things, the -use of \fBprex\fR to do simple probe control. -.sp -.LP -When either the process or kernel is started, all probes are disabled. -.LP -\fBExample 1 \fRSet creation and set listing -.sp -.in +2 -.nf -\fBcreate $out name=/out/ # $out = probes with "out" in - # value of "name" attribute -create $foo /page/ name=biodone # $foo = union of - # probes with "page" in value of keys attribute - # probes with "biodone" as value of "name" attribute -list sets # list the defined sets -list fcns # list the defined probe fcns\fR -.fi -.in -2 -.sp - -.LP -\fBExample 2 \fRCommands to trace and connect probe functions -.sp -.in +2 -.nf -\fBtrace foobar='on' # exact match on foobar attribute -trace $all # trace all probes (predefined set $all) -connect &debug $foo # connect debug func to probes in $foo\fR -.fi -.in -2 -.sp - -.LP -\fBExample 3 \fRCommands to enable and disable probes -.sp -.in +2 -.nf -\fBenable $all # enable all probes -enable /vm/ name=alloc # enable the specified probes -disable $foo # disable probes in set $foo -list history # list probe control commands issued\fR -.fi -.in -2 -.sp - -.LP -\fBExample 4 \fRProcess control -.sp -.in +2 -.nf -\fBcontinue # resumes the target process -^C # stop target; give control to prex -quit resume # exit prex, leave process running - # and resume execution of program\fR -.fi -.in -2 -.sp - -.LP -\fBExample 5 \fRKernel mode -.sp -.in +2 -.nf -\fBbuffer alloc 2m # allocate a 2 Megabyte buffer -enable $all # enable all probes -trace $all # trace all probes -ktrace on # turn tracing on -ktrace off # turn tracing back off -pfilter on # turn process filter mode on -pfilter add 1379 # add pid 1379 to process filter -ktrace on # turn tracing on - # (only pid 1379 will be traced)\fR -.fi -.in -2 -.sp - -.SH FILES -.sp -.ne 2 -.na -\fB\fB\&.prexrc\fR\fR -.ad -.RS 15n -local \fBprex\fR initialization file -.RE - -.sp -.ne 2 -.na -\fB\fB~/.prexrc\fR\fR -.ad -.RS 15n -user's \fBprex\fR initialization file -.RE - -.sp -.ne 2 -.na -\fB\fB/proc/\fInnnnn\fR\fR\fR -.ad -.RS 15n -process files -.RE - -.SH SEE ALSO -.sp -.LP -.BR ed (1), -.BR kill (1), -.BR ksh (1), -.BR ld (1), -.BR tnfdump (1), -.BR tnfxtract (1), -.BR truss (1), -.BR exec (2), -.BR fork (2), -.BR fork1 (2), -.BR vfork (2), -.BR dlclose (3C), -.BR dlopen (3C), -.BR gethrtime (3C), -.BR TNF_DECLARE_RECORD (3TNF), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) -.SH NOTES -.sp -.LP -Currently, the only probe function that is available is the \fB&debug\fR -function. When this function is executed, it prints out the arguments sent in -to the probe as well as the value associated with the \fBsunw%debug\fR -attribute in the detail field (if any) to \fBstderr\fR. -.sp -.LP -For example, for the following probe point: -.sp -.in +2 -.nf -TNF_PROBE_2(input_values, "testapp main", - "sunw%debug 'have read input values successfully'", - tnf_long, int_input, x, - tnf_string, string_input, input); -.fi -.in -2 -.sp - -.sp -.LP -If \fIx\fR was 100 and \fIinput\fR was the string "success", then the output of -the debug probe function would be: -.sp -.in +2 -.nf -probe input_values; sunw%debug "have read input values successfully"; -int_input=100; string_input="success"; -.fi -.in -2 -.sp - -.sp -.LP -Some non-SPARC hardware lacks a true high-resolution timer, causing -\fBgethrtime()\fR to return the same value multiple times in succession. This -can lead to problems in how some tools interpret the trace file. This situation -can be improved by interposing a version of \fBgethrtime()\fR, which causes -these successive values to be artificially incremented by one nanosecond: -.sp -.in +2 -.nf -hrtime_t -gethrtime() -{ - static mutex_t lock; - static hrtime_t (*real_gethrtime)(void) = NULL; - static hrtime_t last_time = 0; - - hrtime_t this_time; - - if (real_gethrtime == NULL) { - real_gethrtime = - (hrtime_t (*)(void)) dlsym(RTLD_NEXT, "gethrtime"); - } - this_time = real_gethrtime(); - - mutex_lock(&lock); - if (this_time <= last_time) - this_time = ++last_time; - else - last_time = this_time; - mutex_unlock(&lock); - - return (this_time); -} -.fi -.in -2 -.sp - -.sp -.LP -Of course, this does not increase the resolution of the timer, so timestamps -for individual events are still relatively inaccurate. But this technique -maintains ordering, so that if event A causes event B, B never appears to -happen before or at the same time as A. -.sp -.LP -\fBdbx\fR is available with the Sun Workshop Products. -.SH BUGS -.sp -.LP -\fBprex\fR should issue a notification when a process id has been automatically -deleted from the filter set. -.sp -.LP -There is a known bug in \fBprex\fR which can result in this message: -.sp -.in +2 -.nf -Tracing shut down in target program due to an internal -error - Please restart prex and target -.fi -.in -2 -.sp - -.sp -.LP -When \fBprex\fR runs as root, and the target process is not root, and the -tracefile is placed in a directory where it cannot be removed and re-created (a -directory with the sticky bit on, like \fB/tmp\fR),mm then the target process -will not be able to open the tracefile when it needs to. This results in -tracing being disabled. -.sp -.LP -Changing any of the circumstances listed above should fix the problem. Either -don't run \fBprex\fR as root, or run the target process as root, or specify the -tracefile in a directory other than \fB/tmp\fR. diff --git a/usr/src/man/man1/tnfdump.1 b/usr/src/man/man1/tnfdump.1 deleted file mode 100644 index 160f2d9e89..0000000000 --- a/usr/src/man/man1/tnfdump.1 +++ /dev/null @@ -1,348 +0,0 @@ -'\" te -.\" Copyright (c) 2001, Sun Microsystems, Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFDUMP 1 "December 28, 2020" -.SH NAME -tnfdump \- convert binary TNF file to ASCII -.SH SYNOPSIS -.nf -\fBtnfdump\fR [\fB-r\fR] [\fB-x\fR] \fItnf_file\fR... -.fi - -.SH DESCRIPTION -The \fBtnfdump\fR utility converts the specified binary \fBTNF\fR trace files -to \fBASCII\fR. The \fBASCII\fR output can be used to do performance analysis. -The default mode (without the \fB-r\fR option) prints all the event records -(that were generated by \fBTNF_PROBE\fR(3TNF)) and the event descriptor records -only. It also orders the events by time. -.SH OPTIONS -The following option is supported: -.sp -.ne 2 -.na -\fB\fB-r\fR\fR -.ad -.RS 6n -Does a raw conversion of \fBTNF\fR to \fBASCII\fR. The output is a literal -translation of the binary \fBTNF\fR file and includes all the records in the -file. This output is useful only if you have a good understanding of -\fBTNF\fR. A sample output is listed in EXAMPLES below. -.RE - -.sp -.ne 2 -.na -\fB\fB-x\fR\fR -.ad -.RS 6n -Prints all \fBTNF\fR unsigned type argument values in hexadecimal format -instead of decimal format. -.RE - -.SH RETURN VALUES -\fBtnfdump\fR returns \fB0\fR on successful exit. -.SH EXAMPLES -\fBExample 1 \fRConverting a file into ASCII -.sp -.LP -To convert the file \fB/tmp/trace-2130\fR into \fBASCII\fR, use the -\fBtnfdump\fR command and the name of the binary trace file. Be aware that the -\fBtnfdump\fR output goes to \fBstdout\fR by default. - -.sp -.in +2 -.nf -example% \fBtnfdump /tmp/trace-2130\fR -.fi -.in -2 -.sp - -.sp -.in +2 -.nf -probe tnf_name: "inloop" tnf_string: "keys cookie main loop;\e - file cookie2.c;line 50;sunw%debug in the loop" -probe tnf_name: "end" tnf_string: "keys cookie main end;\e - file cookie2.c;line 41;sunw%debug exiting program" -------------- ----------- ---- ------ --- ---------- ---------------- -Elapsed (ms) Delta (ms) PID LWPID TID CPU Probe Data/ - Name Description ... -------------- ----------- ---- ------ --- ---------- ---------------- - 0.000000 0.000000 8792 1 0 - inloop loop_count: 0 - total_iterations: 0 - 0.339000 0.339000 8792 1 0 - inloop loop_count: 1 - total_iterations: 1 - 0.350500 0.011500 8792 1 0 - inloop loop_count: 2 - total_iterations: 2 - 0.359500 0.009000 8792 1 0 - inloop loop_count: 3 - total_iterations: 3 - 0.369500 0.010000 8792 1 0 - inloop loop_count: 4 - total_iterations: 4 -7775.969500 7775.600000 8792 1 0 - inloop loop_count: 0 - total_iterations: 5 -7776.016000 0.046500 8792 1 0 - inloop loop_count: 1 - total_iterations: 6 -7776.025000 0.009000 8792 1 0 - inloop loop_count: 2 - total_iterations: 7 -7776.034000 0.009000 8792 1 0 - inloop loop_count: 3 - total_iterations: 8 -7776.043000 0.009000 8792 1 0 - inloop loop_count: 4 - total_iterations: 9 -7776.052000 0.009000 8792 1 0 - inloop loop_count: 5 - total_iterations: 10 -7776.061000 0.009000 8792 1 0 - inloop loop_count: 6 - total_iterations: 11 -9475.979500 1699.918500 8792 1 0 - end node_struct: - { type: node_tnf - cur_sum: 9 max_cnt: 12 } -.fi -.in -2 -.sp - -.sp -.LP -All probes that are encountered during execution have a description of it -printed out. The description is one per line prefixed by the -keyword '\fBprobe\fR'. The name of the probe is in double quotes after the -keyword '\fBtnf_name\fR'. The description of this probe is in double quotes after the -keyword '\fBtnf_string\fR'. - -.sp -.LP -A heading is printed after all the description of the probes are printed. The -first column gives the elapsed time in milli-seconds since the first event. The -second column gives the elapsed time in milli-seconds since the previous event. -The next four columns are the process id, lwp id, thread id, and cpu number. -The next column is the name of the probe that generated this event. This can be -matched to the probe description explained above. The last column is the data -that the event contains, formatted as \fBarg_name_n\fR \fB(see\fR -\fBTNF_PROBE\fR(3TNF)) followed by a colon and the value of that argument. The -format of the value depends on its type. \fBtnf_opaque\fR arguments are printed -in hexadecimal. All other integers are printed in decimal. Strings are printed -in double quotes and user-defined records are enclosed in braces `{ }'. The -first field of a user defined record indicates its \fBTNF\fR type (see -\fBTNF_DECLARE_RECORD\fR(3TNF)). The rest of the fields are the members of the -record. - -.sp -.LP -A `-' in any column indicates that there is no data for that particular column. - -.LP -\fBExample 2 \fRTo do a raw conversion of a file into ASCII -.sp -.LP -To do a raw conversion of the file \fB/tmp/trace-4000\fR into \fBASCII\fR, use: - -.sp -.in +2 -.nf -example% \fBtnfdump -r /tmp/trace-4000\fR -.fi -.in -2 -.sp - -.sp -.LP -The output will look like the following: - -.sp -.in +2 -.nf -0x10e00 : { - tnf_tag 0x109c0 tnf_block_header - generation 1 - bytes_valid 320 - A_lock 0 - B_lock 0 - next_block 0x0 - } -0x10e10 : { - tnf_tag 0x10010 probe1 - tnf_tag_arg 0x10e24 <tnf_sched_rec> - time_delta 128 - test_ulong 4294967295 - test_long -1 - } -0x10e24 : { - tnf_tag 0x10cf4 tnf_sched_rec - tid 0 - lwpid 1 - pid 13568 - time_base 277077875828500 - } -0x10e3c : { - tnf_tag 0x11010 probe2 - tnf_tag_arg 0x10e24 <tnf_sched_rec> - time_delta 735500 - test_str 0x10e48 "string1" - } -0x10e48 : { - tnf_tag 0x1072c tnf_string - tnf_self_size 16 - chars "string1" - } -0x10e58 : { - tnf_tag 0x110ec probe3 - tnf_tag_arg 0x10e24 <tnf_sched_rec> - time_delta 868000 - test_ulonglong 18446744073709551615 - test_longlong -1 - test_float 3.142857 - } -\|.\|.\|. -\|.\|.\|. -\|.\|.\|. -0x110ec : { - tnf_tag 0x10030 tnf_probe_type - tnf_tag_code 42 - tnf_name 0x1110c "probe3" - tnf_properties 0x1111c <tnf_properties> - tnf_slot_types 0x11130 <tnf_slot_types> - tnf_type_size 32 - tnf_slot_names 0x111c4 <tnf_slot_names> - tnf_string 0x11268 "keys targdebug main;\e - file targdebug.c;line 61;" - } -0x1110c : { - tnf_tag 0x10068 tnf_name - tnf_self_size 16 - chars "probe3" - } -0x1111c : { - tnf_tag 0x100b4 tnf_properties - tnf_self_size 20 - 0 0x101a0 tnf_tagged - 1 0x101c4 tnf_struct - 2 0x10b84 tnf_tag_arg - } -0x11130 : { - tnf_tag 0x10210 tnf_slot_types - tnf_self_size 28 - 0 0x10bd0 tnf_probe_event - 1 0x10c20 tnf_time_delta - 2 0x1114c tnf_uint64 - 3 0x10d54 tnf_int64 - 4 0x11188 tnf_float32 - } -.fi -.in -2 -.sp - -.sp -.LP -The first number is the file offset of the record. The record is enclosed in -braces `{ }'. The first column in a record is the slot name (for records whose -fields do not have names, it is the type name). The second column in the record -is the value of that slot if it is a scalar (only scalars that are of type -\fBtnf_opaque\fR are printed in hex), or the offset of the record if it is a -reference to another record. - -.sp -.LP -The third column in a record is optional. It does not exist for scalar slots of -records. If it exists, the third column is a type name with or without angle -brackets, or a string in double quotes. Unadorned names indicate a reference to -the named metatag record (that is, a reference to a record with that name in -the \fBtnf_name\fR field). Type names in angled brackets indicate a reference -to a record that is an instance of that type (that is, a reference to a record -with that name in the \fBtnf_tag\fR field). The content of strings are printed -out in double quotes at the reference site. - -.sp -.LP -Records that are arrays have their array elements follow the header slots, and -are numbered 0, 1, 2, and so on, except strings where the string is written as -the 'chars' (pseudo-name) slot. - -.sp -.LP -Records that are events (generated by \fBTNF_PROBE\fR(3TNF)) will have a slot -name of \fBtnf_tag_arg\fR as their second field which is a reference to the -schedule record. Schedule records describe more information about the event -like the thread-id, process-id, and the \fBtime_base\fR. The \fBtime_delta\fR -of an event can be added to the \fBtime_base\fR of the schedule record that the -event references, to give an absolute time. This time is expressed as -nanoseconds since some arbitrary time in the past (see \fBgethrtime\fR(3C)). - -.LP -\fBExample 3 \fRPrinting TNF unsigned arguments in hexadecimal -.sp -.LP -To print \fBTNF\fR unsigned arguments in hexadecimal for the file -\fB/tmp/trace-2192\fR, use: - -.sp -.in +2 -.nf -example% \fBtnfdump -x /tmp/trace-2192\fR -.fi -.in -2 -.sp - -.sp -.LP -The output will look like the following: - -.sp -.in +2 -.nf -probe tnf_name: "start" tnf_string: "keys cookie main; -file test17.c;line 20;sunw%debug starting main" -probe tnf_name: "inloop" tnf_string: "keys cookie main -loop;file test17.c;line 41;sunw%debug in the loop" -probe tnf_name: "final" tnf_string: "keys cookie main -final;file test17.c;line 32;sunw%debug in the final" ------------- ----------- ---- ----- --- --------- --------------------- - Elapsed Delta PID LWPID TID CPU Probe Data/Description ... - (ms) (ms) Name ------------- ----------- ---- ----- --- --------- --------------------- - 0.000000 0.000000 6280 1 1 - start - 2455.211311 2455.211311 6280 1 1 - inloop loop_count: 0x0 - total_iterations: 0x0 - 2455.215768 0.004457 6280 1 1 - inloop loop_count: 0x1 - total_iterations: 0x1 - 2455.217041 0.001273 6280 1 1 - inloop loop_count: 0x2 - total_iterations: 0x2 - 2455.218285 0.001244 6280 1 1 - inloop loop_count: 0x3 - total_iterations: 0x3 - 2455.219600 0.001315 6280 1 1 - inloop loop_count: 0x4 - total_iterations: 0x4 - 4058.815125 1603.595525 6280 1 1 - inloop loop_count: 0x0 - total_iterations: 0x5 - 4058.818699 0.003574 6280 1 1 - inloop loop_count: 0x1 - total_iterations: 0x6 - 4058.819931 0.001232 6280 1 1 - inloop loop_count: 0x2 - total_iterations: 0x7 - 4058.821264 0.001333 6280 1 1 - inloop loop_count: 0x3 - total_iterations: 0x8 - 4058.822520 0.001256 6280 1 1 - inloop loop_count: 0x4 - total_iterations: 0x9 - 4058.823781 0.001261 6280 1 1 - inloop loop_count: 0x5 - total_iterations: 0xa - 4058.825037 0.001256 6280 1 1 - inloop loop_count: 0x6 - total_iterations: 0xb -13896.655450 9837.830413 6280 1 1 - final loop_count16: 0x258 - total_iterations8: 0xb0 -:: -:: -:: -.fi -.in -2 -.sp - -.sp -.LP -Notice that the \fBloop_count\fR and the \fBtotal_iterations\fR are \fBTNF\fR -unsigned arguments. Their values are printed in hexadecimal when requested by -option \fB-x\fR. - -.SH SEE ALSO -.BR prex (1), -.BR gethrtime (3C), -.BR TNF_DECLARE_RECORD (3TNF), -.BR TNF_PROBE (3TNF), -.BR tnf_process_disable (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man1/tnfxtract.1 b/usr/src/man/man1/tnfxtract.1 deleted file mode 100644 index df74485bdc..0000000000 --- a/usr/src/man/man1/tnfxtract.1 +++ /dev/null @@ -1,140 +0,0 @@ -'\" te -.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFXTRACT 1 "Aug 19, 2003" -.SH NAME -tnfxtract \- extract kernel probes output into a trace file -.SH SYNOPSIS -.LP -.nf -\fBtnfxtract\fR [\fB-d\fR \fIdumpfile\fR \fB-n\fR \fInamelist\fR] \fItnf_file\fR -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBtnfxtract\fR utility collects kernel trace output from an in-core buffer -in the Solaris kernel, or from the memory image of a crashed system, and -generates a binary \fBTNF\fR trace file like those produced directly by user -programs being traced. -.sp -.LP -Either both or neither of the \fB-d\fR and \fB-n\fR options must be specified. -If neither is specified, trace output is extracted from the running kernel. If -both are specified, the \fB-d\fR argument names the file containing the -(crashed) system memory image, and the \fB-n\fR argument names the file -containing the symbol table for the system memory image. -.sp -.LP -The \fBTNF\fR trace file \fItnf_file\fR produced is exactly the same size as -the in-core buffer; it is essentially a snapshot of that buffer. It is legal -to run \fBtnfxtract\fR while kernel tracing is active, i.e., while the in-core -buffer is being written. \fBtnfxtract\fR insures that the output file it -generates is low-level consistent, that is, that only whole probes are written -out, and that internal data structures in the buffer are not corrupted because -the buffer is being concurrently written. -.sp -.LP -The \fBTNF\fR trace file generated is suitable as input to \fBtnfdump\fR(1), -which will generate an \fBASCII\fR file. -.SH OPTIONS -.sp -.LP -The following options are supported: -.sp -.ne 2 -.na -\fB\fB-d\fR \fIdumpfile\fR\fR -.ad -.RS 15n -Uses \fIdumpfile\fR as the system memory image, instead of the running kernel. -The \fIdumpfile\fR is normally the path name of a file generated by the -\fBsavecore\fR utility. -.RE - -.sp -.ne 2 -.na -\fB\fB-n\fR \fInamelist\fR\fR -.ad -.RS 15n -Uses \fInamelist\fR as the file containing the symbol table information for the -given \fIdumpfile\fR. -.RE - -.SH OPERANDS -.sp -.LP -The following operand is supported: -.sp -.ne 2 -.na -\fB\fItnf_file\fR\fR -.ad -.RS 12n -Output file generated by \fBtnfxtract\fR based on kernel trace output from an -in-core buffer in the Solaris kernel. -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRExtracting probes from a running kernel -.sp -.LP -Extract probes from the running kernel into \fBktrace.out\fR: - -.sp -.in +2 -.nf -example% \fBtnfxtract ktrace.out\fR -.fi -.in -2 -.sp - -.LP -\fBExample 2 \fRExtracting probes from a kernel crash dump -.sp -.LP -Extract probes from a kernel crash dump into \fBktrace.out\fR: - -.sp -.in +2 -.nf -example% \fBtnfxtract -d /var/crash/`uname -n`/vmcore.0 \e - -n /var/crash/`uname -n`/unix.0 ktrace.out\fR -.fi -.in -2 -.sp - -.SH EXIT STATUS -.sp -.LP -The following exit values are returned: -.sp -.ne 2 -.na -\fB\fB0\fR\fR -.ad -.RS 6n -Successful completion. -.RE - -.sp -.ne 2 -.na -\fB\fB>0\fR\fR -.ad -.RS 6n -An error occurred. -.RE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR tnfdump (1), -.BR tnf_kernel_probes (5), -.BR attributes (7), -.BR savecore (8) diff --git a/usr/src/man/man3/Intro.3 b/usr/src/man/man3/Intro.3 index 9ce8548ea9..7ecddc9805 100644 --- a/usr/src/man/man3/Intro.3 +++ b/usr/src/man/man3/Intro.3 @@ -5,7 +5,7 @@ .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH INTRO 3 "Aug 19, 2019" +.TH INTRO 3 "Sep 12, 2021" .SH NAME Intro, intro \- introduction to functions and libraries .SH DESCRIPTION @@ -903,22 +903,6 @@ See \fBlibtecla\fR(3LIB). .sp .ne 2 .na -\fB(3TNF)\fR -.ad -.sp .6 -.RS 4n -These functions constitute the TNF libraries, \fBlibtnf\fR, \fBlibtnfctl\fR, -and \fBlibtnfprobe\fR. These libraries are implemented as shared objects, -\fBlibtnf.so\fR, \fBlibtnfctl.so\fR, and \fBlibtnfprobe.so\fR, respectively, -but are not automatically linked by the C compilation system. Specify -\fB-ltnf\fR, \fB-ltnfctl\fR, or \fB-ltnfprobe\fR on the \fBcc\fR command line -to link with these libraries. See \fBlibtnfctl\fR(3TNF) and -\fBlibtnfctl\fR(3LIB). -.RE - -.sp -.ne 2 -.na \fB(3TSOL)\fR .ad .sp .6 diff --git a/usr/src/man/man3lib/Makefile b/usr/src/man/man3lib/Makefile index e1ff6e7c7e..1f698ad311 100644 --- a/usr/src/man/man3lib/Makefile +++ b/usr/src/man/man3lib/Makefile @@ -100,7 +100,6 @@ MANFILES= libMPAPI.3lib \ libsysevent.3lib \ libtecla.3lib \ libthread.3lib \ - libtnfctl.3lib \ libtsalarm.3lib \ libtsnet.3lib \ libtsol.3lib \ diff --git a/usr/src/man/man3lib/libtnfctl.3lib b/usr/src/man/man3lib/libtnfctl.3lib deleted file mode 100644 index 47531a168b..0000000000 --- a/usr/src/man/man3lib/libtnfctl.3lib +++ /dev/null @@ -1,100 +0,0 @@ -'\" te -.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH LIBTNFCTL 3LIB "May 22, 2003" -.SH NAME -libtnfctl \- TNF probe control library -.SH SYNOPSIS -.LP -.nf -cc [ \fIflag\fR... ] \fIfile\fR.. \fB-ltnfctl\fR [ \fIlibrary\fR... ] -#include <\fBtnf/tnfctl.h\fR> -.fi - -.SH DESCRIPTION -.sp -.LP -Functions in this library provide TNF probe control routines for use by -processes and the kernel. -.SH INTERFACES -.sp -.LP -The shared object \fBlibtnfctl.so.1\fR provides the public interfaces defined -below. See \fBIntro\fR(3) for additional information on shared object -interfaces. -.sp - -.sp -.TS -l l -l l . -\fBtnfctl_buffer_alloc\fR \fBtnfctl_buffer_dealloc\fR -\fBtnfctl_check_libs\fR \fBtnfctl_close\fR -\fBtnfctl_continue\fR \fBtnfctl_exec_open\fR -\fBtnfctl_filter_list_add\fR \fBtnfctl_filter_list_delete\fR -\fBtnfctl_filter_list_get\fR \fBtnfctl_filter_state_set\fR -\fBtnfctl_indirect_open\fR \fBtnfctl_internal_open\fR -\fBtnfctl_kernel_open\fR \fBtnfctl_pid_open\fR -\fBtnfctl_probe_apply\fR \fBtnfctl_probe_apply_ids\fR -\fBtnfctl_probe_connect\fR \fBtnfctl_probe_disable\fR -\fBtnfctl_probe_disconnect_all\fR \fBtnfctl_probe_enable\fR -\fBtnfctl_probe_state_get\fR \fBtnfctl_probe_trace\fR -\fBtnfctl_probe_untrace\fR \fBtnfctl_register_funcs\fR -\fBtnfctl_strerror\fR \fBtnfctl_trace_attrs_get\fR -\fBtnfctl_trace_state_set\fR -.TE - -.SH FILES -.sp -.ne 2 -.na -\fB\fB/usr/lib/libtnfctl.so.1\fR\fR -.ad -.RS 30n -shared object -.RE - -.sp -.ne 2 -.na -\fB\fB/usr/lib/64/libtnfctl.so.1\fR\fR -.ad -.RS 30n -64-bit shared object -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT-Level MT-Safe with exceptions -.TE - -.SH SEE ALSO -.sp -.LP -.BR pvs (1), -.BR Intro (3), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR attributes (7) -.SH NOTES -.sp -.LP -This \fBAPI\fR is MT-Safe. Multiple threads can concurrently operate on -independent \fBtnfctl\fR handles, which is the typical behavior expected. -\fBlibtnfctl\fR does not support multiple threads operating on the same -\fBtnfctl\fR handle. If this is desired, it is the client's responsibility to -implement locking to ensure that two threads that use the same \fBtnfctl\fR -handle are not simultaneously present in a \fBlibtnfctl\fR interface. diff --git a/usr/src/man/man3tnf/Makefile b/usr/src/man/man3tnf/Makefile deleted file mode 100644 index d56a657acb..0000000000 --- a/usr/src/man/man3tnf/Makefile +++ /dev/null @@ -1,124 +0,0 @@ -# -# This file and its contents are supplied under the terms of the -# Common Development and Distribution License ("CDDL"), version 1.0. -# You may only use this file in accordance with the terms of version -# 1.0 of the CDDL. -# -# A full copy of the text of the CDDL should have accompanied this -# source. A copy of the CDDL is also available via the Internet -# at http://www.illumos.org/license/CDDL. -# - -# -# Copyright 2011, Richard Lowe -# Copyright 2013 Nexenta Systems, Inc. All rights reserved. -# - -include $(SRC)/Makefile.master - -MANSECT= 3tnf - -MANFILES= TNF_DECLARE_RECORD.3tnf \ - TNF_PROBE.3tnf \ - libtnfctl.3tnf \ - tnf_process_disable.3tnf \ - tnfctl_buffer_alloc.3tnf \ - tnfctl_close.3tnf \ - tnfctl_indirect_open.3tnf \ - tnfctl_internal_open.3tnf \ - tnfctl_kernel_open.3tnf \ - tnfctl_pid_open.3tnf \ - tnfctl_probe_apply.3tnf \ - tnfctl_probe_state_get.3tnf \ - tnfctl_register_funcs.3tnf \ - tnfctl_strerror.3tnf \ - tnfctl_trace_attrs_get.3tnf \ - tnfctl_trace_state_set.3tnf \ - tracing.3tnf - -MANLINKS= TNF_DEBUG.3tnf \ - TNF_DEFINE_RECORD_1.3tnf \ - TNF_DEFINE_RECORD_2.3tnf \ - TNF_DEFINE_RECORD_3.3tnf \ - TNF_DEFINE_RECORD_4.3tnf \ - TNF_DEFINE_RECORD_5.3tnf \ - TNF_PROBE_0.3tnf \ - TNF_PROBE_0_DEBUG.3tnf \ - TNF_PROBE_1.3tnf \ - TNF_PROBE_1_DEBUG.3tnf \ - TNF_PROBE_2.3tnf \ - TNF_PROBE_2_DEBUG.3tnf \ - TNF_PROBE_3.3tnf \ - TNF_PROBE_3_DEBUG.3tnf \ - TNF_PROBE_4.3tnf \ - TNF_PROBE_4_DEBUG.3tnf \ - TNF_PROBE_5.3tnf \ - TNF_PROBE_5_DEBUG.3tnf \ - tnf_process_enable.3tnf \ - tnf_thread_disable.3tnf \ - tnf_thread_enable.3tnf \ - tnfctl_buffer_dealloc.3tnf \ - tnfctl_check_libs.3tnf \ - tnfctl_continue.3tnf \ - tnfctl_exec_open.3tnf \ - tnfctl_filter_list_add.3tnf \ - tnfctl_filter_list_delete.3tnf \ - tnfctl_filter_list_get.3tnf \ - tnfctl_filter_state_set.3tnf \ - tnfctl_probe_apply_ids.3tnf \ - tnfctl_probe_connect.3tnf \ - tnfctl_probe_disable.3tnf \ - tnfctl_probe_disconnect_all.3tnf \ - tnfctl_probe_enable.3tnf \ - tnfctl_probe_trace.3tnf \ - tnfctl_probe_untrace.3tnf - -TNF_DEFINE_RECORD_1.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_2.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_3.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_4.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf -TNF_DEFINE_RECORD_5.3tnf := LINKSRC = TNF_DECLARE_RECORD.3tnf - -TNF_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_0.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_0_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_1.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_1_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_2.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_2_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_3.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_3_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_4.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_4_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_5.3tnf := LINKSRC = TNF_PROBE.3tnf -TNF_PROBE_5_DEBUG.3tnf := LINKSRC = TNF_PROBE.3tnf - -tnf_process_enable.3tnf := LINKSRC = tnf_process_disable.3tnf -tnf_thread_disable.3tnf := LINKSRC = tnf_process_disable.3tnf -tnf_thread_enable.3tnf := LINKSRC = tnf_process_disable.3tnf - -tnfctl_buffer_dealloc.3tnf := LINKSRC = tnfctl_buffer_alloc.3tnf - -tnfctl_check_libs.3tnf := LINKSRC = tnfctl_indirect_open.3tnf - -tnfctl_continue.3tnf := LINKSRC = tnfctl_pid_open.3tnf -tnfctl_exec_open.3tnf := LINKSRC = tnfctl_pid_open.3tnf - -tnfctl_probe_apply_ids.3tnf := LINKSRC = tnfctl_probe_apply.3tnf - -tnfctl_probe_connect.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_disable.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_disconnect_all.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_enable.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_trace.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_probe_untrace.3tnf := LINKSRC = tnfctl_probe_state_get.3tnf -tnfctl_filter_list_add.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf -tnfctl_filter_list_delete.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf -tnfctl_filter_list_get.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf -tnfctl_filter_state_set.3tnf := LINKSRC = tnfctl_trace_state_set.3tnf - -.KEEP_STATE: - -include $(SRC)/man/Makefile.man - -install: $(ROOTMANFILES) $(ROOTMANLINKS) diff --git a/usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf b/usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf deleted file mode 100644 index bb656366f2..0000000000 --- a/usr/src/man/man3tnf/TNF_DECLARE_RECORD.3tnf +++ /dev/null @@ -1,180 +0,0 @@ -'\" te -.\" Copyright 1994 Sun Microsystems Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with -.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNF_DECLARE_RECORD 3TNF "Dec 31, 1996" -.SH NAME -TNF_DECLARE_RECORD, TNF_DEFINE_RECORD_1, TNF_DEFINE_RECORD_2, -TNF_DEFINE_RECORD_3, TNF_DEFINE_RECORD_4, TNF_DEFINE_RECORD_5 \- TNF type -extension interface for probes -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ...[ \fB-ltnfprobe\fR ] [ \fIlibrary\fR ... ] -#include <tnf/probe.h> - - - -\fBTNF_DECLARE_RECORD\fR(\fIc_type\fR, \fItnf_type\fR); -.fi - -.LP -.nf -\fBTNF_DEFINE_RECORD_1\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR); -.fi - -.LP -.nf -\fBTNF_DEFINE_RECORD_2\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, - \fItnf_member_type_2\fR, \fIc_member_name_2\fR); -.fi - -.LP -.nf -\fBTNF_DEFINE_RECORD_3\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, - \fItnf_member_type_2\fR, \fIc_member_name_2\fR, \fItnf_member_type_3\fR, - \fIc_member_name_3\fR); -.fi - -.LP -.nf -\fBTNF_DEFINE_RECORD_4\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, - \fItnf_member_type_2\fR, \fIc_member_name_2\fR, \fItnf_member_type_3\fR, - \fIc_member_name_3\fR, \fItnf_member_type_4\fR, \fIc_member_name_4\fR); -.fi - -.LP -.nf -\fBTNF_DEFINE_RECORD_5\fR(\fIc_type\fR, \fItnf_type\fR, \fItnf_member_type_1\fR, \fIc_member_name_1\fR, - \fItnf_member_type_2\fR, \fIc_member_name_2\fR, \fItnf_member_type_3\fR, - \fIc_member_name_3\fR,\fItnf_member_type_4\fR, \fIc_member_name_4\fR, - \fItnf_member_type_5\fR, \fIc_member_name_5\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -This macro interface is used to extend the TNF (Trace Normal Form) types that -can be used in \fBTNF_PROBE\fR(3TNF). -.sp -.LP -There should be only one \fBTNF_DECLARE_RECORD\fR and one -\fBTNF_DEFINE_RECORD\fR per new type being defined. The -\fBTNF_DECLARE_RECORD\fR should precede the \fBTNF_DEFINE_RECORD\fR. It can be -in a header file that multiple source files share if those source files need -to use the \fItnf_type\fR being defined. The \fBTNF_DEFINE_RECORD\fR should -only appear in one of the source files. -.sp -.LP -The \fBTNF_DEFINE_RECORD\fR macro interface defines a function as well as a -couple of data structures. Hence, this interface has to be used in a source -file (.c or .cc file) at file scope and not inside a function. -.sp -.LP -Note that there is no semicolon after the \fBTNF_DEFINE_RECORD\fR interface. -Having one will generate a compiler warning. -.sp -.LP -Compiling with the preprocessor option \fB-DNPROBE\fR or with the preprocessor -control statement \fB#define NPROBE\fR ahead of the \fB#include -<tnf/probe.h>\fR statement, will stop the TNF type extension code from being -compiled into the program. -.sp -.LP -The \fIc_type\fR argument must be a C struct type. It is the template from -which the new \fItnf_type\fR is being created. Not all elements of the C -struct need be provided in the TNF type being defined. -.sp -.LP -The \fItnf_type\fR argument is the name being given to the newly created type. -Use of this interface uses the name space prefixed by \fItnf_type\fR. If a new -type called "xxx_type" is defined by a library, then the library should not use -"xxx_type" as a prefix in any other symbols it defines. The policy on managing -the type name space is the same as managing any other name space in a library; -that is, prefix any new TNF types by the unique prefix that the rest of the -symbols in the library use. This would prevent name space collisions when -linking multiple libraries that define new TNF types. For example, if a -library \fBlibpalloc.so\fR uses the prefix "pal" for all symbols it defines, -then it should also use the prefix "pal" for all new TNF types being defined. -.sp -.LP -The \fItnf_member_type_n\fR argument is the TNF type of the \fIn\fRth provided -member of the C structure. -.sp -.LP -The \fItnf_member_name_n\fR argument is the name of the \fIn\fRth provided -member of the C structure. -.SH EXAMPLES -.LP -\fBExample 1 \fRDefining and using a TNF type. -.sp -.LP -The following example demonstrates how a new TNF type is defined and used in a -probe. This code is assumed to be part of a fictitious library called -"libpalloc.so" which uses the prefix "pal" for all it's symbols. - -.sp -.in +2 -.nf -#include <tnf/probe.h> -typedef struct pal_header { - long size; - char * descriptor; - struct pal_header *next; -} pal_header_t; -TNF_DECLARE_RECORD(pal_header_t, pal_tnf_header); -TNF_DEFINE_RECORD_2(pal_header_t, pal_tnf_header, - tnf_long, size, - tnf_string, descriptor) -/* - * Note: name space prefixed by pal_tnf_header should not - * be used by this client anymore. - */ -void -pal_free(pal_header_t *header_p) -{ - int state; - TNF_PROBE_2(pal_free_start, "palloc pal_free", - "sunw%debug entering pal_free", - tnf_long, state_var, state, - pal_tnf_header, header_var, header_p); - ... -} -.fi -.in -2 - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT-Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR tnfdump (1), -.BR TNF_PROBE (3TNF), -.BR tnf_process_disable (3TNF), -.BR attributes (7) -.SH NOTES -.sp -.LP -It is possible to make a \fItnf_type\fR definition be recursive or mutually -recursive e.g. a structure that uses the "next" field to point to itself (a -linked list). If such a structure is sent in to a \fBTNF_PROBE\fR(3TNF), then -the entire linked list will be logged to the trace file (until the "next" field -is \fINULL\fR). But, if the list is circular, it will result in an infinite -loop. To break the recursion, either do not include the "next" field in the -\fItnf_type\fR, or define the type of the "next" member as \fBtnf_opaque\fR. diff --git a/usr/src/man/man3tnf/TNF_PROBE.3tnf b/usr/src/man/man3tnf/TNF_PROBE.3tnf deleted file mode 100644 index 7f5bd161bf..0000000000 --- a/usr/src/man/man3tnf/TNF_PROBE.3tnf +++ /dev/null @@ -1,332 +0,0 @@ -'\" te -.\" Copyright 2004. Sun Microsystems Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. -.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with -.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNF_PROBE 3TNF "Mar 1, 2004" -.SH NAME -TNF_PROBE, TNF_PROBE_0, TNF_PROBE_1, TNF_PROBE_2, TNF_PROBE_3, TNF_PROBE_4, -TNF_PROBE_5, TNF_PROBE_0_DEBUG, TNF_PROBE_1_DEBUG, TNF_PROBE_2_DEBUG, -TNF_PROBE_3_DEBUG, TNF_PROBE_4_DEBUG, TNF_PROBE_5_DEBUG, TNF_DEBUG \- probe -insertion interface -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] [ \fB-DTNF_DEBUG\fR ] \fIfile\fR ... [ \fB-ltnfprobe\fR ] [ \fIlibrary\fR ... ] -#include <tnf/probe.h> - -\fBTNF_PROBE_0\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_1\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_2\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_3\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR,\fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR, - \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_4\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR, - \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR, - \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_5\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR, - \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR, - \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR, - \fIarg_type_5\fR, \fIarg_name_5\fR, \fIarg_value_5\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_0_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_1_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_2_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_3_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR, - \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_4_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR, - \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR, - \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR); -.fi - -.LP -.nf -\fBTNF_PROBE_5_DEBUG\fR(\fIname\fR, \fIkeys\fR, \fIdetail\fR, \fIarg_type_1\fR, \fIarg_name_1\fR, \fIarg_value_1\fR, - \fIarg_type_2\fR, \fIarg_name_2\fR, \fIarg_value_2\fR, - \fIarg_type_3\fR, \fIarg_name_3\fR, \fIarg_value_3\fR, - \fIarg_type_4\fR, \fIarg_name_4\fR, \fIarg_value_4\fR, - \fIarg_type_5\fR, \fIarg_name_5\fR, \fIarg_value_5\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -This macro interface is used to insert probes into C or C++ code for tracing. -See \fBtracing\fR(3TNF) for a discussion of the Solaris tracing architecture, -including example source code that uses it. -.sp -.LP -You can place probes anywhere in C and C++ programs including .init -sections, .fini sections, multi-threaded code, shared objects, and shared objects opened -by \fBdlopen\fR(3C). Use probes to generate trace data for performance -analysis or to write debugging output to stderr. Probes are controlled at -runtime by \fBprex\fR(1). -.sp -.LP -The trace data is logged to a trace file in Trace Normal Form ( \fBTNF).\fR -The interface for the user to specify the name and size of the trace file is -described in \fBprex\fR(1). Think of the trace file as the least recently used -circular buffer. Once the file has been filled, newer events will overwrite the -older ones. -.sp -.LP -Use \fBTNF_PROBE_0\fR through \fBTNF_PROBE_5\fR to create production probes. -These probes are compiled in by default. Developers are encouraged to embed -such probes strategically, and to leave them compiled within production -software. Such probes facilitate on-site analysis of the software. -.sp -.LP -Use \fBTNF_PROBE_0_DEBUG\fR through \fBTNF_PROBE_5_DEBUG\fR to create debug -probes. These probes are compiled out by default. If you compile the program -with the preprocessor option \fB-DTNF_DEBUG\fR or with the preprocessor -control statement \fB#define\fR \fBTNF_DEBUG\fR ahead of the \fB#include\fR -\fB<tnf/probe.h>\fR statement, the debug probes will be compiled into the -program. When compiled in, debug probes differ in only one way from the -equivalent production probes. They contain an additional "debug" attribute -which may be used to distinguish them from production probes at runtime, for -example, when using \fBprex()\fR. Developers are encouraged to embed any number -of probes for debugging purposes. Disabled probes have such a small runtime -overhead that even large numbers of them do not make a significant impact. -.sp -.LP -If you compile with the preprocessor option \fB-DNPROBE\fR or place the -preprocessor control statement \fB#define\fR \fBNPROBE\fR ahead of the -\fB#include\fR \fB<tnf/probe.h>\fR statement, no probes will be compiled into -the program. -.SS "name" -.sp -.LP -The \fIname\fR of the probe should follow the syntax guidelines for identifiers -in ANSI C. The use of \fIname\fR declares it, hence no separate declaration is -necessary. This is a block scope declaration, so it does not affect the name -space of the program. -.SS "keys" -.sp -.LP -\fIkeys\fR is a string of space-separated keywords that specify the groups that -the probe belongs to. Semicolons, single quotation marks, and the equal -character (=) are not allowed in this string. If any of the groups are enabled, -the probe is enabled. \fIkeys\fR cannot be a variable. It must be a string -constant. -.SS "detail" -.sp -.LP -\fIdetail\fR is a string that consists of <attribute> <value> pairs that are -each separated by a semicolon. The first word (up to the space) is considered -to be the attribute and the rest of the string (up to the semicolon) is -considered the value. Single quotation marks are used to denote a string value. -Besides quotation marks, spaces separate multiple values. The value is -optional. Although semicolons or single quotation marks generally are not -allowed within either the attribute or the value, when text with embedded -spaces is meant to denote a single value, use single quotes surrounding this -text. -.sp -.LP -Use \fIdetail\fR for one of two reasons. First, use \fIdetail\fR to supply -an attribute that a user can type into \fBprex\fR(1) to select probes. For -example, if a user defines an attribute called color, then \fBprex\fR(1) can -select probes based on the value of color. Second, use \fIdetail\fR to annotate -a probe with a string that is written out to a trace file only once. -\fBprex\fR(1) uses spaces to tokenize the value when searching for a match. -Spaces around the semicolon delimiter are allowed. \fIdetail\fR cannot be a -variable; it must be a string constant. For example, the \fIdetail\fR string: -.sp -.in +2 -.nf -"XYZ%debug 'entering function A'; XYZ%exception 'no file'; -XYZ%func_entry; XYZ%color red blue" -.fi -.in -2 - -.sp -.LP -consists of 4 units: -.sp - -.sp -.TS -box; -c c c -l l l . -\fBAttribute\fR \fBValue\fR \fBValues that\fR \fBprex\fR \fBmatches on\fR -_ -XYZ%debug \&'entering function A' \&'entering function A' -XYZ%exception \&'no file' \&'no file' -XYZ%func_entry /.*/ (regular expression) -XYZ%color red blue red <or> blue -.TE - -.sp -.LP -Attribute names must be prefixed by the vendor stock symbol followed by -the '%' character. This avoids conflicts in the attribute name space. All -attributes that do not have a '%' character are reserved. The following -attributes are predefined: -.sp - -.sp -.TS -box; -c c -l l . -\fBAttribute\fR \fBSemantics\fR -_ -name name of probe -keys T{ -keys of the probe (value is space\(mi separated tokens) -T} -file file name of the probe -line line number of the probe -slots T{ -slot names of the probe event (\fIarg_name_n\fR) -T} -object T{ -the executable or shared object that this probe is in. -T} -debug T{ -distinguishes debug probes from production probes -T} -.TE - -.SS "arg_type_n" -.sp -.LP -This is the type of the \fIn\fRth argument. The following are predefined -\fBTNF\fR types: -.sp - -.sp -.TS -box; -c c -l l . -\fBtnf Type\fR \fBAssociated C type (and semantics)\fR -_ -tnf_int int -tnf_uint unsigned int -tnf_long long -tnf_ulong unsigned long -tnf_longlong T{ -long long (if implemented in compilation system) -T} -tnf_ulonglong T{ -unsigned long long (if implemented in compilation system) -T} -tnf_float float -tnf_double double -tnf_string char * -tnf_opaque void * -.TE - -.sp -.LP -To define new \fBTNF\fR types that are records consisting of the predefined -\fBTNF\fR types or references to other user defined types, use the interface -specified in \fBTNF_DECLARE_RECORD\fR(3TNF). -.SS "arg_name_n" -.sp -.LP -\fIarg_name_n\fR is the name that the user associates with the \fIn\fRth -argument. Do not place quotation marks around \fIarg_name_n\fR. Follow the -syntax guidelines for identifiers in ANSI C. The string version of -\fIarg_name_n\fR is stored for every probe and can be accessed as the attribute -"slots". -.SS "arg_value_n" -.sp -.LP -\fIarg_value_n\fR is evaluated to yield a value to be included in the trace -file. A read access is done on any variables that are in mentioned in -\fIarg_value_n\fR. In a multithreaded program, it is the user's responsibility -to place locks around the \fBTNF_PROBE\fR macro if \fIarg_value_n\fR contains -a variable that should be read protected. -.SH EXAMPLES -.LP -\fBExample 1 \fRtracing(3TNF) -.sp -.LP -See \fBtracing\fR(3TNF) for complete examples showing debug and production -probes in source code. - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR ld (1), -.BR prex (1), -.BR tnfdump (1), -.BR dlopen (3C), -.BR TNF_DECLARE_RECORD (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tracing (3TNF), -.BR attributes (7), -.BR threads (7) -.SH NOTES -.sp -.LP -If attaching to a running program with \fBprex\fR(1) to control the probes, -compile the program with \fB-ltnfprobe\fR or start the program with the -environment variable \fBLD_PRELOAD\fR set to \fBlibtnfprobe.so.1\fR. See -\fBld\fR(1). If \fBlibtnfprobe\fR is explicitly linked into the program, it -must be listed before \fBlibdoor\fR, which in turn must be listed before -\fBlibthread\fR on the link line. diff --git a/usr/src/man/man3tnf/libtnfctl.3tnf b/usr/src/man/man3tnf/libtnfctl.3tnf deleted file mode 100644 index 6e0784413e..0000000000 --- a/usr/src/man/man3tnf/libtnfctl.3tnf +++ /dev/null @@ -1,472 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH LIBTNFCTL 3TNF "June 20, 2021" -.SH NAME -libtnfctl \- library for TNF probe control in a process or the kernel -.SH SYNOPSIS -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> -.fi - -.SH DESCRIPTION -The \fBlibtnfctl\fR library provides an \fBAPI\fR to control \fBTNF\fR -("Trace Normal Form") probes within a process or the kernel. See -\fBtracing\fR(3TNF) for an overview of the Solaris tracing architecture. The -client of \fBlibtnfctl\fR controls probes in one of four modes: -.sp -.ne 2 -.na -\fBinternal mode\fR -.ad -.RS 17n -The target is the controlling process itself; that is, the client controls its -own probes. -.RE - -.sp -.ne 2 -.na -\fBdirect mode\fR -.ad -.RS 17n -The target is a separate process; a client can either \fBexec\fR(2) a program -or attach to a running process for probe control. The \fBlibtnfctl\fR library -uses \fBproc\fR(5) on the target process for probe and process control in this -mode, and additionally provides basic process control features. -.RE - -.sp -.ne 2 -.na -\fBindirect mode\fR -.ad -.RS 17n -The target is a separate process, but the controlling process is already using -\fBproc\fR(5) to control the target, and hence \fBlibtnfctl\fR cannot use -those interfaces directly. Use this mode to control probes from within a -debugger. In this mode, the client must provide a set of functions that -\fBlibtnfctl\fR can use to query and update the target process. -.RE - -.sp -.ne 2 -.na -\fBkernel mode\fR -.ad -.RS 17n -The target is the Solaris kernel. -.RE - -.sp -.LP -A process is controlled "externally" if it is being controlled in either direct -mode or indirect mode. Alternatively, a process is controlled "internally" when -it uses internal mode to control its own probes. -.sp -.LP -There can be only one client at a time doing probe control on a given process. -Therefore, it is not possible for a process to be controlled internally while -it is being controlled externally. It is also not possible to have a process -controlled by multiple external processes. Similarly, there can be only one -process at a time doing kernel probe control. Note, however, that while a given -target may only be controlled by one \fBlibtnfctl\fR client, a single client -may control an arbitrary number of targets. That is, it is possible for a -process to simultaneously control its own probes, probes in other processes, -and probes in the kernel. -.sp -.LP -The following tables denotes the modes applicable to all \fBlibtnfctl\fR -interfaces (INT = internal mode; D = direct mode; IND = indirect mode; K = -kernel mode). -.sp -.LP -These interfaces create handles in the specified modes: -.sp - -.sp -.TS -l l l l l -l l l l l . -\fBtnfctl_internal_open()\fR INT -\fBtnfctl_exec_open()\fR D -\fBtnfctl_pid_open()\fR D -\fBtnfctl_indirect_open()\fR IND -\fBtnfctl_kernel_open()\fR K -.TE - -.sp -.LP -These interfaces are used with the specified modes: -.sp - -.sp -.TS -l l l l l -l l l l l . -\fBtnfctl_continue()\fR D -\fBtnfctl_probe_connect()\fR INT D IND -\fBtnfctl_probe_disconnect_all ()\fR INT D IND -\fBtnfctl_trace_attrs_get()\fR INT D IND K -\fBtnfctl_buffer_alloc()\fR INT D IND K -\fBtnfctl_register_funcs()\fR INT D IND K -\fBtnfctl_probe_apply()\fR INT D IND K -\fBtnfctl_probe_apply_ids()\fR INT D IND K -\fBtnfctl_probe_state_get ()\fR INT D IND K -\fBtnfctl_probe_enable()\fR INT D IND K -\fBtnfctl_probe_disable()\fR INT D IND K -\fBtnfctl_probe_trace()\fR INT D IND K -\fBtnfctl_probe_untrace()\fR INT D IND K -\fBtnfctl_check_libs()\fR INT D IND K -\fBtnfctl_close()\fR INT D IND K -\fBtnfctl_strerror()\fR INT D IND K -\fBtnfctl_buffer_dealloc()\fR K -\fBtnfctl_trace_state_set()\fR K -\fBtnfctl_filter_state_set()\fR K -\fBtnfctl_filter_list_get()\fR K -\fBtnfctl_filter_list_add()\fR K -\fBtnfctl_filter_list_delete()\fR K -.TE - -.sp -.LP -When using \fBlibtnfctl\fR, the first task is to create a handle for -controlling probes. The \fBtnfctl_internal_open()\fR function creates an -internal mode handle for controlling probes in the same process, as described -above. The \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR functions -create handles in direct mode. The \fBtnfctl_indirect_open()\fR function -creates an indirect mode handle, and the \fBtnfctl_kernel_open()\fR function -creates a kernel mode handle. A handle is required for use in nearly all other -\fBlibtnfctl\fR functions. The \fBtnfctl_close()\fR function releases the -resources associated with a handle. -.sp -.LP -The \fBtnfctl_continue()\fR function is used in direct mode to resume execution -of the target process. -.sp -.LP -The \fBtnfctl_buffer_alloc()\fR function allocates a trace file or, in kernel -mode, a trace buffer. -.sp -.LP -The \fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR functions -call a specified function for each probe or for a designated set of probes. -.sp -.LP -The \fBtnfctl_register_funcs()\fR function registers functions to be called -whenever new probes are seen or probes have disappeared, providing an -opportunity to do one-time processing for each probe. -.sp -.LP -The \fBtnfctl_check_libs()\fR function is used primarily in indirect mode to -check whether any new probes have appeared, that is, they have been made -available by \fBdlopen\fR(3C), or have disappeared, that is, they have -disassociated from the process by \fBdlclose\fR(3C). -.sp -.LP -The \fBtnfctl_probe_enable()\fR and \fBtnfctl_probe_disable()\fR functions -control whether the probe, when hit, will be ignored. -.sp -.LP -The \fBtnfctl_probe_trace()\fR and \fBtnfctl_probe_untrace()\fR functions -control whether an enabled probe, when hit, will cause an entry to be made in -the trace file. -.sp -.LP -The \fBtnfctl_probe_connect()\fR and \fBtnfctl_probe_disconnect_all()\fR -functions control which functions, if any, are called when an enabled probe is -hit. -.sp -.LP -The \fBtnfctl_probe_state_get()\fR function returns information about the -status of a probe, such as whether it is currently enabled. -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function returns information about the -tracing session, such as the size of the trace buffer or trace file. -.sp -.LP -The \fBtnfctl_strerror()\fR function maps a \fBtnfctl\fR error code to a -string, for reporting purposes. -.sp -.LP -The remaining functions apply only to kernel mode. -.sp -.LP -The \fBtnfctl_trace_state_set()\fR function controls the master switch for -kernel tracing. See \fBprex\fR(1) for more details. -.sp -.LP -The \fBtnfctl_filter_state_set()\fR, \fBtnfctl_filter_list_get()\fR, -\fBtnfctl_filter_list_add()\fR, and \fBtnfctl_filter_list_delete()\fR functions -allow a set of processes to be specified for which probes will not be ignored -when hit. This prevents kernel activity caused by uninteresting processes from -cluttering up the kernel's trace buffer. -.sp -.LP -The \fBtnfctl_buffer_dealloc()\fR function deallocates the kernel's internal -trace buffer. -.SH RETURN VALUES -Upon successful completion, these functions return \fBTNFCTL_ERR_NONE\fR. -.SH ERRORS -The error codes for \fBlibtnfctl\fR are: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 28n -Permission denied. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTARGET\fR\fR -.ad -.RS 28n -The target process completed. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR -.ad -.RS 28n -The requested trace size is too small. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR -.ad -.RS 28n -The requested trace size is too big. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 28n -Bad input argument. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR -.ad -.RS 28n -The target is not a dynamic executable. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so\fR not linked in target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 28n -Tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR -.ad -.RS 28n -A buffer already exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 28n -No buffer exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR -.ad -.RS 28n -Cannot deallocate buffer. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 28n -No such target process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR -.ad -.RS 28n -File not found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Cannot attach to process or kernel because it is already tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 28n -Probe no longer valid. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR1\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR2\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR3\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR4\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR5\fR\fR -.ad -.RS 28n -Error code reserved for user. -.RE - -.SH ATTRIBUTES -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe with exceptions -.TE - -.SH SEE ALSO -.BR prex (1), -.BR exec (2), -.BR dlclose (3C), -.BR dlopen (3C), -.BR libtnfctl (3LIB), -.BR TNF_PROBE (3TNF), -.BR tnfctl_buffer_alloc (3TNF), -.BR tnfctl_buffer_dealloc (3TNF), -.BR tnfctl_check_libs (3TNF), -.BR tnfctl_close (3TNF), -.BR tnfctl_continue (3TNF), -.BR tnfctl_exec_open (3TNF), -.BR tnfctl_filter_list_add (3TNF), -.BR tnfctl_filter_list_delete (3TNF), -.BR tnfctl_filter_list_get (3TNF), -.BR tnfctl_filter_state_set (3TNF), -.BR tnfctl_indirect_open (3TNF), -.BR tnfctl_internal_open (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_pid_open (3TNF), -.BR tnfctl_probe_apply (3TNF), -.BR tnfctl_probe_apply_ids (3TNF), -.BR tnfctl_probe_connect (3TNF), -.BR tnfctl_probe_disable (3TNF), -.BR tnfctl_probe_enable (3TNF), -.BR tnfctl_probe_state_get (3TNF), -.BR tnfctl_probe_trace (3TNF), -.BR tnfctl_probe_untrace (3TNF), -.BR tnfctl_register_funcs (3TNF), -.BR tnfctl_strerror (3TNF), -.BR tnfctl_trace_attrs_get (3TNF), -.BR tnfctl_trace_state_set (3TNF), -.BR proc (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -This \fBAPI\fR is MT-Safe. Multiple threads may concurrently operate on -independent \fBtnfctl\fR handles, which is the typical behavior expected. The -\fBlibtnfctl\fR library does not support multiple threads operating on the same -\fBtnfctl\fR handle. If this is desired, it is the client's responsibility to -implement locking to ensure that two threads that use the same \fBtnfctl\fR -handle are not simultaneously in a \fBlibtnfctl\fR interface. diff --git a/usr/src/man/man3tnf/tnf_process_disable.3tnf b/usr/src/man/man3tnf/tnf_process_disable.3tnf deleted file mode 100644 index 2042da9c7f..0000000000 --- a/usr/src/man/man3tnf/tnf_process_disable.3tnf +++ /dev/null @@ -1,119 +0,0 @@ -'\" te -.\" Copyright 2002 Sun Microsystems Inc. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNF_PROCESS_DISABLE 3TNF "Feb 5, 2002" -.SH NAME -tnf_process_disable, tnf_process_enable, tnf_thread_disable, tnf_thread_enable -\- probe control internal interface -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfprobe\fR [ \fIlibrary\fR ... ] -#include <tnf/probe.h> - - - -\fBvoid\fR \fBtnf_process_disable\fR(\fBvoid\fR); -.fi - -.LP -.nf -\fBvoid\fR \fBtnf_process_enable\fR(\fBvoid\fR); -.fi - -.LP -.nf -\fBvoid\fR \fBtnf_thread_disable\fR(\fBvoid\fR); -.fi - -.LP -.nf -\fBvoid\fR \fBtnf_thread_enable\fR(\fBvoid\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -There are three levels of granularity for controlling tracing and probe -functions (called probing from here on): probing for the entire process, a -particular thread, and the probe itself can be disabled or enabled. The first -two (process and thread) are controlled by this interface. The probe is -controlled with the \fBprex\fR(1) utility. -.sp -.LP -The \fBtnf_process_disable()\fR function turns off probing for the process. The -default process state is to have probing enabled. The -\fBtnf_process_enable()\fR function turns on probing for the process. -.sp -.LP -The \fBtnf_thread_disable()\fR function turns off probing for the currently -running thread. Threads are "born" or created with this state enabled. The -\fBtnf_thread_enable()\fR function turns on probing for the currently running -thread. If the program is a non-threaded program, these two thread interfaces -disable or enable probing for the process. -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -Interface Stability Unstable -_ -MT-Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR tnfdump (1), -.BR TNF_DECLARE_RECORD (3TNF), -.BR TNF_PROBE (3TNF), -.BR attributes (7) -.SH NOTES -.sp -.LP -A probe is considered enabled only if: -.RS +4 -.TP -.ie t \(bu -.el o -\fBprex\fR(1) has enabled the probe AND -.RE -.RS +4 -.TP -.ie t \(bu -.el o -the process has probing enabled, which is the default or could be set with -\fBtnf_process_enable()\fR AND -.RE -.RS +4 -.TP -.ie t \(bu -.el o -the thread that hits the probe has probing enabled, which is every thread's -default or could be set with \fBtnf_thread_enable()\fR. -.RE -.sp -.LP -There is a run time cost associated with determining that the probe is -disabled. To reduce the performance effect of probes, this cost should be -minimized. The quickest way that a probe can be determined to be disabled is -by the enable control that \fBprex\fR(1) uses. Therefore, to disable all the -probes in a process use the \fBdisable\fR command in \fBprex\fR(1) rather than -\fBtnf_process_disable()\fR. -.sp -.LP -The \fBtnf_process_disable()\fR and \fBtnf_process_enable()\fR functions should -only be used to toggle probing based on some internal program condition. The -\fBtnf_thread_disable()\fR function should be used to turn off probing for -threads that are uninteresting. diff --git a/usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf b/usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf deleted file mode 100644 index 1d7a7f5666..0000000000 --- a/usr/src/man/man3tnf/tnfctl_buffer_alloc.3tnf +++ /dev/null @@ -1,207 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_BUFFER_ALLOC 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_buffer_alloc, tnfctl_buffer_dealloc \- allocate or deallocate a buffer -for trace data -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> -\fBtnfctl_errcode_t\fR \fBtnfctl_buffer_alloc\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBconst char *\fR\fItrace_file_name\fR, \fBsize_t\fR \fItrace_buffer_size\fR); -.fi - -.LP -.nf -\fB\fR\fBtnfctl_buffer_dealloc\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_buffer_alloc()\fR allocates a buffer to which trace events are -logged. When tracing a process using a \fBtnfctl\fR handle returned by -\fBtnfctl_pid_open\fR(3TNF), \fBtnfctl_exec_open\fR(3TNF), -\fBtnfctl_indirect_open\fR(3TNF), and \fBtnfctl_internal_open\fR(3TNF)), -\fItrace_file_name\fR is the name of the trace file to which trace events -should be logged. It can be an absolute path specification or a relative path -specification. If it is relative, the current working directory of the process -that is calling \fBtnfctl_buffer_alloc()\fR is prefixed to -\fItrace_file_name\fR. If the named trace file already exists, it is -overwritten. For kernel tracing, that is, for a tnfctl handle returned by -\fBtnfctl_kernel_open\fR(3TNF), trace events are logged to a trace buffer in -memory; therefore, \fItrace_file_name\fR is ignored. Use \fBtnfxtract\fR(1) to -extract a kernel buffer into a file. -.sp -.LP -\fItrace_buffer_size\fR is the size in bytes of the trace buffer that should be -allocated. An error is returned if an attempt is made to allocate a buffer when -one already exists. \fBtnfctl_buffer_alloc()\fR affects the trace attributes; -use \fBtnfctl_trace_attrs_get\fR(3TNF) to get the latest trace attributes -after a buffer is allocated. -.sp -.LP -\fBtnfctl_buffer_dealloc()\fR is used to deallocate a kernel trace buffer that -is no longer needed. \fIhndl\fR must be a kernel handle, returned by -\fBtnfctl_kernel_open\fR(3TNF). A process's trace file cannot be deallocated -using \fBtnfctl_buffer_dealloc()\fR. Instead, once the trace file is no longer -needed for analysis and after the process being traced exits, use \fBrm\fR(1) -to remove the trace file. Do not remove the trace file while the process being -traced is still alive. \fBtnfctl_buffer_dealloc()\fR affects the trace -attributes; use \fBtnfctl_trace_attrs_get\fR(3TNF) to get the latest trace -attributes after a buffer is deallocated. -.sp -.LP -For a complete discussion of \fBtnf tracing\fR, see \fBtracing\fR(3TNF). -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_buffer_alloc()\fR and \fBtnfctl_buffer_dealloc()\fR return -\fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_buffer_alloc()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFEXISTS\fR\fR -.ad -.RS 27n -A buffer already exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 27n -Permission denied; could not create a trace file. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOSMALL\fR\fR -.ad -.RS 27n -The \fItrace_buffer_size\fR requested is smaller than the minimum trace buffer -size needed. Use \fBtrace_min_size\fR of trace attributes in -\fBtnfctl_trace_attrs_get\fR(3TNF) to determine the minimum size of the buffer. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_SIZETOOBIG\fR\fR -.ad -.RS 27n -The requested trace file size is too big. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 27n -\fItrace_file_name\fR is \fINULL\fR or the absolute path name is longer than -\fBMAX\fR\fBPATH\fR\fBLEN.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 27n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 27n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_buffer_dealloc()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 25n -\fIhndl\fR is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 25n -No buffer exists to deallocate. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADDEALLOC\fR\fR -.ad -.RS 25n -Cannot deallocate a trace buffer unless tracing is stopped. Use -\fBtnfctl_trace_state_set\fR(3TNF) to stop tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 25n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR rm (1), -.BR tnfxtract (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_exec_open (3TNF), -.BR tnfctl_indirect_open (3TNF), -.BR tnfctl_internal_open (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_pid_open (3TNF), -.BR tnfctl_trace_attrs_get (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_close.3tnf b/usr/src/man/man3tnf/tnfctl_close.3tnf deleted file mode 100644 index 1d1a732e05..0000000000 --- a/usr/src/man/man3tnf/tnfctl_close.3tnf +++ /dev/null @@ -1,129 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_CLOSE 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_close \- close a tnfctl handle -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> -\fBtnfctl_errcode_t\fR \fBtnfctl_close\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_targ_op_t\fR \fIaction\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_close()\fR is used to close a tnfctl handle and to free up the memory -associated with the handle. When the handle is closed, the tracing state and -the states of the probes are not changed. \fBtnfctl_close()\fR can be used to -close handles in any mode, that is, whether they were created by -\fBtnfctl_internal_open\fR(3TNF), \fBtnfctl_pid_open\fR(3TNF), -\fBtnfctl_exec_open\fR(3TNF), \fBtnfctl_indirect_open\fR(3TNF), or -\fBtnfctl_kernel_open\fR(3TNF). -.sp -.LP -The \fIaction\fR argument is only used in direct mode, that is, if \fIhndl\fR -was created by \fBtnfctl_exec_open\fR(3TNF) or \fBtnfctl_pid_open\fR(3TNF). In -direct mode, \fIaction\fR specifies whether the process will proceed, be -killed, or remain suspended. \fIaction\fR may have the following values: -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_DEFAULT\fR\fR -.ad -.RS 23n -Kills the target process if \fIhndl\fR was created with -\fBtnfctl_exec_open\fR(3TNF), but lets it continue if it was created with -\fBtnfctl_pid_open\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_KILL\fR\fR -.ad -.RS 23n -Kills the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_RESUME\fR\fR -.ad -.RS 23n -Allows the target process to continue. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_TARG_SUSPEND\fR\fR -.ad -.RS 23n -Leaves the target process suspended. This is not a job control suspend. It is -possible to attach to the process again with a debugger or with the -\fBtnfctl_pid_open\fR(3TNF) interface. The target process can also be -continued with \fBprun\fR(1). -.RE - -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_close()\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_close()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 23n -A bad argument was sent in \fIaction\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR prun (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_exec_open (3TNF), -.BR tnfctl_indirect_open (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_pid_open (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_indirect_open.3tnf b/usr/src/man/man3tnf/tnfctl_indirect_open.3tnf deleted file mode 100644 index 4708ff4948..0000000000 --- a/usr/src/man/man3tnf/tnfctl_indirect_open.3tnf +++ /dev/null @@ -1,210 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_INDIRECT_OPEN 3TNF "August 29, 2021" -.SH NAME -tnfctl_indirect_open, tnfctl_check_libs \- control probes of another process -where caller provides /proc functionality -.SH SYNOPSIS -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_indirect_open\fR(\fBvoid *\fR\fIprochandle\fR, - \fBtnfctl_ind_config_t *\fR\fIconfig\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_check_libs\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR); -.fi - -.SH DESCRIPTION -The interfaces \fBtnfctl_indirect_open()\fR and \fBtnfctl_check_libs()\fR are -used to control probes in another process where the \fBlibtnfctl\fR(3TNF) -client has already opened \fBproc\fR(5) on the target process. An example of -this is when the client is a debugger. Since these clients already use -\fB/proc\fR on the target, \fBlibtnfctl\fR(3TNF) cannot use \fB/proc\fR -directly. Therefore, these clients must provide callback functions that can be -used to inspect and to update the target process. The target process must -load \fBlibtnfprobe.so.1\fR (defined in \fB<tnf/tnfctl.h>\fR as macro -\fBTNFCTL_LIBTNFPROBE).\fR -.sp -.LP -The first argument \fIprochandle\fR is a pointer to an opaque structure that is -used in the callback functions that inspect and update the target process. -This structure should encapsulate the state that the caller needs to use -\fB/proc\fR on the target process (the \fB/proc\fR file descriptor). The -second argument, \fIconfig\fR, is a pointer to -.sp -.in +2 -.nf -typedef -struct tnfctl_ind_config { - int (*p_read)(void *prochandle, paddr_t addr, char *buf, - size_t size); - int (*p_write)(void *prochandle, paddr_t addr, char *buf, - size_t size); - pid_t (*p_getpid)(void *prochandle); - int (*p_obj_iter)(void *prochandle, tnfctl_ind_obj_f *func, - void *client_data); -} tnfctl_ind_config_t; -.fi -.in -2 - -.sp -.LP -The first field \fIp_read\fR is the address of a function that can read -\fBsize\fR bytes at address \fIaddr\fR in the target image into the buffer -\fIbuf\fR. The function should return \fB0\fR upon success. The second field -\fIp_write\fR is the address of a function that can write \fBsize\fR bytes at -address \fIaddr\fR in the target image from the buffer \fIbuf\fR. The function -should return \fB0\fR upon success. The third field \fIp_getpid\fR is the -address of a function that should return the process id of the target process -(\fIprochandle\fR). The fourth field \fIp_obj_iter\fR is the address of a -function that iterates over all load objects and the executable by calling the -callback function \fIfunc\fR with \fIclient_data\fR. If \fIfunc\fR returns -\fB0\fR, \fIp_obj_iter\fR should continue processing link objects. If -\fIfunc\fR returns any other value, \fIp_obj_iter\fR should stop calling the -callback function and return that value. \fIp_obj_iter\fR should return -\fB0\fR if it iterates over all load objects. -.sp -.LP -If a failure is returned by any of the functions in \fIconfig\fR, the error is -propagated back as \fBPREX_ERR_INTERNAL\fR by the \fBlibtnfctl\fR interface -that called it. -.sp -.LP -The definition of \fBtnfctl_ind_obj_f\fR is: -.sp -.in +2 -.nf -typedef int -tnfctl_ind_obj_f(void *prochandle, - const struct tnfctl_ind_obj_info *obj - void *client_data); -typedef struct tnfctl_ind_obj_info { - int objfd; /* -1 indicates fd not available */ - paddr_t text_base; /* virtual addr of text segment */ - paddr_t data_base; /* virtual addr of data segment */ - const char *objname; /* null-term. pathname to loadobj */ -} tnfctl_ind_obj_info_t; -.fi -.in -2 - -.sp -.LP -\fIobjfd\fR should be the file descriptor of the load object or executable. If -it is \fB\(mi1\fR, then \fIobjname\fR should be an absolute pathname to the -load object or executable. If \fIobjfd\fR is not closed by \fBlibtnfctl\fR, it -should be closed by the load object iterator function. \fItext_base\fR and -\fIdata_base\fR are the addresses where the text and data segments of the load -object are mapped in the target process. -.sp -.LP -Whenever the target process opens or closes a dynamic object, the set of -available probes may change. See \fBdlopen\fR(3C) and \fBdlclose\fR(3C). In -indirect mode, call \fBtnfctl_check_libs()\fR when such events occur to make -\fBlibtnfctl\fR aware of any changes. In other modes this is unnecessary but -harmless. It is also harmless to call \fBtnfctl_check_libs()\fR when no such -events have occurred. -.SH RETURN VALUES -\fBtnfctl_indirect_open()\fR and \fBtnfctl_check_libs()\fR return -\fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -The following error codes apply to \fBtnfctl_indirect_open()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Internal tracing is being used. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not loaded in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_check_libs()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 24n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.SH ATTRIBUTES -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_probe_enable (3TNF), -.BR tnfctl_probe_trace (3TNF), -.BR tracing (3TNF), -.BR proc (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -\fBtnfctl_indirect_open()\fR should only be called after the dynamic linker has -mapped in all the libraries (rtld sync point) and called only after the process -is stopped. Indirect process probe control assumes the target process is -stopped whenever any \fBlibtnfctl\fR interface is used on it. For example, -when used for indirect process probe control, \fBtnfctl_probe_enable\fR(3TNF) -and \fBtnfctl_probe_trace\fR(3TNF) should be called only for a process that is -stopped. diff --git a/usr/src/man/man3tnf/tnfctl_internal_open.3tnf b/usr/src/man/man3tnf/tnfctl_internal_open.3tnf deleted file mode 100644 index c3062712c1..0000000000 --- a/usr/src/man/man3tnf/tnfctl_internal_open.3tnf +++ /dev/null @@ -1,126 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_INTERNAL_OPEN 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_internal_open \- create handle for internal process probe control -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - - - -\fBtnfctl_errcode_t\fR \fBtnfctl_internal_open\fR(\fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_internal_open()\fR returns in \fIret_val\fR 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 \fBlibtnfprobe.so.1\fR -loaded. Probes in libraries that are brought in by \fBdlopen\fR(3C) will be -visible after the library has been opened. Probes in libraries closed by a -\fBdlclose\fR(3C) will not be visible after the library has been disassociated. -See the \fBNOTES\fR section for more details. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_internal_open()\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Another client is already tracing this program (internally or externally). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not linked in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR ld (1), -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -.sp -.LP -\fBlibtnfctl\fR interposes on \fBdlopen\fR(3C) and \fBdlclose\fR(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 interposition functions, a lock is acquired to -synchronize on traversal of the library list maintained by the runtime linker. -To avoid deadlocking on this lock, \fBtnfctl_internal_open()\fR should not be -called from within the init section of a library that can be opened by -\fBdlopen\fR(3C). -.sp -.LP -Since interposition does not work as expected when a library is opened -dynamically, \fBtnfctl_internal_open()\fR should not be used if the client -opened \fBlibtnfctl\fR through \fBdlopen\fR(3C). In this case, the client -program should be built with a static dependency on \fBlibtnfctl.\fR Also, if -the client program is explicitly linking in \fB-ldl\fR, it should link -\fB-ltnfctl\fR before \fB-ldl\fR. -.sp -.LP -Probes in filtered libraries (see \fBld\fR(1)) will not be seen because the -filtee (backing library) is loaded lazily on the first symbol reference and not -at process startup or \fBdlopen\fR(3C) time. A workaround is to call -\fBtnfctl_check_libs\fR(3TNF) once the caller is sure that the filtee has been -loaded. diff --git a/usr/src/man/man3tnf/tnfctl_kernel_open.3tnf b/usr/src/man/man3tnf/tnfctl_kernel_open.3tnf deleted file mode 100644 index e9d23afd5a..0000000000 --- a/usr/src/man/man3tnf/tnfctl_kernel_open.3tnf +++ /dev/null @@ -1,117 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_KERNEL_OPEN 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_kernel_open \- create handle for kernel probe control -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - - - -\fBtnfctl_errcode_t\fR \fBtnfctl_kernel_open\fR(\fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_kernel_open()\fR starts a kernel tracing session and returns in -\fBret_val\fR an opaque handle that can be used to control tracing and probes -in the kernel. Only one kernel tracing session is possible at a time on a -given machine. An error code of \fBTNFCTL_ERR_BUSY\fR is returned if there is -another process using kernel tracing. Use the command -.sp -.in +2 -.nf -\fBfuser\fR \fB-f\fR \fB/dev/tnfctl\fR -.fi -.in -2 -.sp - -.sp -.LP -to print the process id of the process currently using kernel tracing. Only a -superuser may use \fBtnfctl_kernel_open()\fR. An error code of -\fBTNFCTL_ERR_ACCES\fR is returned if the caller does not have the necessary -privileges. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_kernel_open\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 27n -Permission denied. Superuser privileges are needed for kernel tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 27n -Another client is currently using kernel tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 27n -Memory allocation failed. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR -.ad -.RS 27n -\fB/dev/tnfctl\fR not found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 27n -Some other failure occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7), -.BR fuser (8) diff --git a/usr/src/man/man3tnf/tnfctl_pid_open.3tnf b/usr/src/man/man3tnf/tnfctl_pid_open.3tnf deleted file mode 100644 index ad6257600a..0000000000 --- a/usr/src/man/man3tnf/tnfctl_pid_open.3tnf +++ /dev/null @@ -1,499 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_PID_OPEN 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_pid_open, tnfctl_exec_open, tnfctl_continue \- interfaces for direct -probe and process control for another process -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_pid_open\fR(\fBpid_t\fR \fIpid\fR, \fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_exec_open\fR(\fBconst char *\fR\fIpgm_name\fR, - \fBchar * const *\fR\fIargv\fR, \fBchar * const *\fR\fIenvp\fR, - \fBconst char *\fR\fIlibnfprobe_path\fR, \fBconst char *\fR\fIld_preload\fR, - \fBtnfctl_handle_t **\fR\fIret_val\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_continue\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_event_t *\fR\fIevt\fR, \fBtnfctl_handle_t **\fR\fIchild_hndl\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and -\fBtnfctl_continue()\fR functions create handles to control probes in another -process (direct process probe control). Either \fBtnfctl_pid_open()\fR or -\fBtnfctl_exec_open()\fR will return a handle in \fIret_val\fR that can be used -for probe control. On return of these calls, the process is stopped. -\fBtnfctl_continue()\fR allows the process specified by \fIhndl\fR to continue -execution. -.sp -.LP -The \fBtnfctl_pid_open()\fR function attaches to a running process with process -id of \fIpid\fR. The process is stopped on return of this call. The -\fBtnfctl_pid_open()\fR function returns an error message if \fIpid\fR is the -same as the calling process. See \fBtnfctl_internal_open\fR(3TNF) for -information on internal process probe control. A pointer to an opaque handle is -returned in \fIret_val\fR, which can be used to control the process and the -probes in the process. The target process must have \fBlibtnfprobe.so.1\fR -(defined in <\fBtnf/tnfctl.h\fR> as macro \fBTNFCTL_LIBTNFPROBE)\fR linked in -for probe control to work. -.sp -.LP -The \fBtnfctl_exec_open()\fR function is used to \fBexec\fR(2) a program and -obtain a probe control handle. For probe control to work, the process image to -be \fBexec\fR'd must load \fBlibtnfprobe.so.1\fR. The \fBtnfctl_exec_open()\fR -function makes it simple for the library to be loaded at process start up time. -The \fIpgm_name\fR argument is the command to \fBexec\fR. If \fIpgm_name\fR is -not an absolute path, then the \fB$PATH\fR environment variable is used to -find the \fIpgm_name\fR. \fIargv\fR is a null-terminated argument pointer, that -is, it is a null-terminated array of pointers to null-terminated strings. These -strings constitute the argument list available to the new process image. The -\fIargv\fR argument must have at least one member, and it should point to a -string that is the same as \fIpgm_name\fR. See \fBexecve\fR(2). The -\fIlibnfprobe_path\fR argument is an optional argument, and if set, it should -be the path to the directory that contains \fBlibtnfprobe.so.1\fR. There is no -need for a trailing "/" in this argument. This argument is useful if -\fBlibtnfprobe.so.1\fR is not installed in \fB/usr/lib\fR. \fIld_preload\fR is -a space-separated list of libraries to preload into the target program. This -string should follow the syntax guidelines of the \fBLD_PRELOAD\fR environment -variable. See \fBld.so.1\fR(1). The following illustrates how strings are -concatenated to form the \fBLD_PRELOAD\fR environment variable in the new -process image: -.sp -.in +2 -.nf -<current value of $LD_PRELOAD> + <space> + -libtnfprobe_path + "/libtnfprobe.so.1" +<space> + -ld_preload -.fi -.in -2 - -.sp -.LP -This option is useful for preloading interposition libraries that have probes -in them. -.sp -.LP -\fIenvp\fR is an optional argument, and if set, it is used for the environment -of the target program. It is a null-terminated array of pointers to -null-terminated strings. These strings constitute the environment of the new -process image. See \fBexecve\fR(2). If \fIenvp\fR is set, it overrides -\fIld_preload\fR. In this case, it is the caller's responsibility to ensure -that \fBlibtnfprobe.so.1\fR is loaded into the target program. If \fIenvp\fR -is not set, the new process image inherits the environment of the calling -process, except for \fBLD_PRELOAD\fR. -.sp -.LP -The \fIret_val\fR argument is the handle that can be used to control the -process and the probes within the process. Upon return, the process is stopped -before any user code, including \fB\&.init\fR sections, has been executed. -.sp -.LP -The \fBtnfctl_continue()\fR function is a blocking call and lets the target -process referenced by \fIhndl\fR continue running. It can only be used on -handles returned by \fBtnfctl_pid_open()\fR and \fBtnfctl_exec_open()\fR -(direct process probe control). It returns when the target stops; the reason -that the process stopped is returned in \fIevt\fR. This call is interruptible -by signals. If it is interrupted, the process is stopped, and -\fBTNFCTL_EVENT_EINTR\fR is returned in \fIevt\fR. The client of this library -will have to decide which signal implies a stop to the target and catch that -signal. Since a signal interrupts \fBtnfctl_continue()\fR, it will return, and -the caller can decide whether or not to call \fBtnfctl_continue()\fR again. -.sp -.LP -\fBtnfctl_continue()\fR returns with an event of \fBTNFCTL_EVENT_DLOPEN\fR, -\fBTNFCTL_EVENT_DLCLOSE\fR, \fBTNFCTL_EVENT_EXEC\fR, \fBTNFCTL_EVENT_FORK\fR, -\fBTNFCTL_EVENT_EXIT\fR, or \fBTNFCTL_EVENT_TARGGONE\fR, respectively, when the -target program calls \fBdlopen\fR(3C), \fBdlclose\fR(3C), any flavor of -\fBexec\fR(2), \fBfork\fR(2) (or \fBfork1\fR(2)), \fBexit\fR(2), or terminates -unexpectedly. If the target program called \fBexec\fR(2), the client then needs -to call \fBtnfctl_close\fR(3TNF) on the current handle leaving the target -resumed, suspended, or killed (second argument to \fBtnfctl_close\fR(3TNF)). -No other \fBlibtnfctl\fR interface call can be used on the existing handle. If -the client wants to control the \fBexec\fR'ed image, it should leave the old -handle suspended, and use \fBtnfctl_pid_open()\fR to reattach to the same -process. This new handle can then be used to control the \fBexec\fR'ed image. -See \fBEXAMPLES\fR below for sample code. If the target process did a -\fBfork\fR(2) or \fBfork1\fR(2), and if control of the child process is not -needed, then \fIchild_hndl\fR should be \fINULL\fR. If control of the child -process is needed, then \fIchild_hndl\fR should be set. If it is set, a -pointer to a handle that can be used to control the child process is returned -in \fIchild_hndl\fR. The child process is stopped at the end of the -\fBfork()\fR system call. See \fBEXAMPLES\fR for an example of this event. -.SH RETURN VALUES -.sp -.LP -The \fBtnfctl_pid_open()\fR, \fBtnfctl_exec_open()\fR, and -\fBtnfctl_continue()\fR functions return \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_pid_open()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 28n -The \fIpid\fR specified is the same process. Use -\fBtnfctl_internal_open\fR(3TNF) instead. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 28n -Permission denied. No privilege to connect to a setuid process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUSY\fR\fR -.ad -.RS 28n -Another client is already using \fB/proc\fR to control this process or -internal tracing is being used. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR -.ad -.RS 28n -The process is not a dynamic executable. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 28n -No such target process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not linked in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_exec_open()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ACCES\fR\fR -.ad -.RS 28n -Permission denied. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 28n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOTDYNAMIC\fR\fR -.ad -.RS 28n -The target is not a dynamic executable. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOLIBTNFPROBE\fR\fR -.ad -.RS 28n -\fBlibtnfprobe.so.1\fR is not linked in the target process. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_FILENOTFOUND\fR\fR -.ad -.RS 28n -The program is not found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 28n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_continue()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -Bad input argument. \fIhndl\fR is not a direct process probe control handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 24n -No such target process exists. -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRUsing \fBtnfctl_pid_open()\fR -.sp -.LP -These examples do not include any error-handling code. Only the initial -example includes the declaration of the variables that are used in all of the -examples. - -.sp -.LP -The following example shows how to preload \fBlibtnfprobe.so.1\fR from the -normal location and inherit the parent's environment. - -.sp -.in +2 -.nf -const char *pgm; -char * const *argv; -tnfctl_handle_t *hndl, *new_hndl, *child_hndl; -tnfctl_errcode_t err; -char * const *envptr; -extern char **environ; -tnfctl_event_t evt; -int pid; - -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -err = tnfctl_exec_open(pgm, argv, NULL, NULL, NULL, &hndl); -.fi -.in -2 - -.sp -.LP -This example shows how to preload two user-supplied libraries -\fBlibc_probe.so.1\fR and \fBlibthread_probe.so.1\fR. They interpose on the -corresponding \fBlibc.so\fR and \fBlibthread.so\fR interfaces and have probes -for function entry and exit. \fBlibtnfprobe.so.1\fR is preloaded from the -normal location and the parent's environment is inherited. - -.sp -.in +2 -.nf -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -err = tnfctl_exec_open(pgm, argv, NULL, NULL, - "libc_probe.so.1 libthread_probe.so.1", &hndl); -.fi -.in -2 - -.sp -.LP -This example preloads an interposition library \fBlibc_probe.so.1\fR, and -specifies a different location from which to preload \fBlibtnfprobe.so.1\fR. - -.sp -.in +2 -.nf -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -err = tnfctl_exec_open(pgm, argv, NULL, "/opt/SUNWXXX/lib", - "libc_probe.so.1", &hndl); -.fi -.in -2 - -.sp -.LP -To set up the environment explicitly for probe control to work, the target -process must link \fBlibtnfprobe.so.1\fR. If using \fIenvp\fR, it is the -caller's responsibility to do so. - -.sp -.in +2 -.nf -/* assuming argv has been allocated */ -argv[0] = pgm; -/* set up rest of argument vector here */ -/* envptr set up to caller's needs */ -err = tnfctl_exec_open(pgm, argv, envptr, NULL, NULL, &hndl); -.fi -.in -2 - -.sp -.LP -Use this example to resume a process that does an \fBexec\fR(2) without -controlling it. - -.sp -.in +2 -.nf -err = tnfctl_continue(hndl, &evt, NULL); -switch (evt) { -case TNFCTL_EVENT_EXEC: - /* let target process continue without control */ - err = tnfctl_close(hndl, TNFCTL_TARG_RESUME); - ... - break; -} -.fi -.in -2 - -.sp -.LP -Alternatively, use the next example to control a process that does an -\fBexec\fR(2). - -.sp -.in +2 -.nf -/* - * assume the pid variable has been set by calling - * tnfctl_trace_attrs_get() -*/ -err = tnfctl_continue(hndl, &evt, NULL); -switch (evt) { -case TNFCTL_EVENT_EXEC: - /* suspend the target process */ - err = tnfctl_close(hndl, TNFCTL_TARG_SUSPEND); - /* re-open the exec'ed image */ - err = tnfctl_pid_open(pid, &new_hndl); - /* new_hndl now controls the exec'ed image */ - ... - break; -} -.fi -.in -2 - -.sp -.LP -To let \fBfork\fR'ed children continue without control, use \fINULL\fR as the -last argument to \fBtnfctl_continue(\|).\fR - -.sp -.in +2 -.nf -err = tnfctl_continue(hndl, &evt, NULL); -.fi -.in -2 - -.sp -.LP -The next example is how to control child processes that \fBfork\fR(2) or -\fBfork1\fR(2) create. - -.sp -.in +2 -.nf -err = tnfctl_continue(hndl, &evt, &child_hndl); -switch (evt) { -case TNFCTL_EVENT_FORK: - /* spawn a new thread or process to control child_hndl */ - ... - break; -} -.fi -.in -2 - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -\fBld\fR(1), \fBprex\fR(1), \fBproc\fR(1), \fBexec\fR(2), \fBexecve\fR(2), -\fBexit\fR(2), \fBfork\fR(2), \fBTNF_PROBE\fR(3TNF), \fBdlclose\fR(3C), -\fBdlopen\fR(3C), \fBlibtnfctl\fR(3TNF), \fBtnfctl_close\fR(3TNF), -\fBtnfctl_internal_open\fR(3TNF), \fBtracing\fR(3TNF) \fBattributes\fR(7) -.sp -.LP -\fILinker and Libraries Guide\fR -.SH NOTES -.sp -.LP -After a call to \fBtnfctl_continue()\fR returns, a client should use -\fBtnfctl_trace_attrs_get\fR(3TNF) to check the \fBtrace_buf_state\fR member of -the trace attributes and make sure that there is no internal error in the -target. diff --git a/usr/src/man/man3tnf/tnfctl_probe_apply.3tnf b/usr/src/man/man3tnf/tnfctl_probe_apply.3tnf deleted file mode 100644 index dbdb0d5ccf..0000000000 --- a/usr/src/man/man3tnf/tnfctl_probe_apply.3tnf +++ /dev/null @@ -1,229 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_PROBE_APPLY 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_probe_apply, tnfctl_probe_apply_ids \- iterate over probes -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_apply_ids\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBulong_t\fR \fIprobe_count\fR, \fBulong_t *\fR\fIprobe_ids\fR, - \fBtnfctl_probe_op_t\fR \fIprobe_op\fR, \fBvoid *\fR\fIclientdata\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_probe_apply()\fR is used to iterate over the probes controlled by -\fIhndl.\fR For every probe, the \fIprobe_op\fR function is called: -.sp -.in +2 -.nf -typedef tnfctl_errcode_t (*tnfctl_probe_op_t)( - tnfctl_handle_t *hndl, - tnfctl_probe_t *probe_hndl, - void *clientdata); -.fi -.in -2 - -.sp -.LP -Several predefined functions are available for use as \fIprobe_op\fR. These -functions are described in \fBtnfctl_probe_state_get\fR(3TNF). -.sp -.LP -The \fIclientdata\fR supplied in \fBtnfctl_probe_apply()\fR is passed in as the -last argument of \fIprobe_op\fR. The \fIprobe_hndl\fR in the probe operation -function can be used to query or change the state of the probe. See -\fBtnfctl_probe_state_get\fR(3TNF). The \fIprobe_op\fR function should return -\fBTNFCTL_ERR_NONE\fR upon success. It can also return an error code, which -will cause \fBtnfctl_probe_apply()\fR 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 \fBERRORS\fR. -.sp -.LP -The lifetime of \fIprobe_hndl\fR is the same as the lifetime of \fIhndl\fR. It -is good until \fIhndl\fR is closed by \fBtnfctl_close\fR(3TNF). Do not confuse -a \fIprobe_hndl\fR with \fIhndl\fR. The \fIprobe_hndl\fR refers to a particular -probe, while \fIhndl\fR refers to a process or the kernel. If \fIprobe_hndl\fR -is used in another \fBlibtnfctl\fR(3TNF) interface, and it references a probe -in a library that has been dynamically closed (see \fBdlclose\fR(3C)), then -the error code \fBTNFCTL_ERR_INVALIDPROBE\fR will be returned by that -interface. -.sp -.LP -\fBtnfctl_probe_apply_ids()\fR is very similar to \fBtnfctl_probe_apply()\fR. -The difference is that \fIprobe_op\fR is called only for probes that match a -probe id specified in the array of integers referenced by \fIprobe_ids\fR. The -number of probe ids in the array should be specified in \fIprobe_count\fR. Use -\fBtnfctl_probe_state_get()\fR to get the \fIprobe_id\fR that corresponds to -the \fIprobe_handl\fR. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR return -\fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following errors apply to both \fBtnfctl_probe_apply()\fR and -\fBtnfctl_probe_apply_ids()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR1\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR2\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR3\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR4\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_USR5\fR\fR -.ad -.RS 23n -Error code reserved for user. -.RE - -.sp -.LP -\fBtnfctl_probe_apply()\fR and \fBtnfctl_probe_apply_ids()\fR also return any -error returned by the callback function \fIprobe_op\fR. -.sp -.LP -The following errors apply only to \fBtnfctl_probe_apply_ids()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -The probe handle is no longer valid. For example, the probe is in a library -that has been closed by \fBdlclose\fR(3C). -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fREnabling Probes -.sp -.LP -To enable all probes: - -.sp -.in +2 -.nf -tnfctl_probe_apply(hndl, tnfctl_probe_enable, NULL); -.fi -.in -2 - -.LP -\fBExample 2 \fRDisabling Probes -.sp -.LP -To disable the probes that match a certain pattern in the probe attribute -string: - -.sp -.in +2 -.nf -/* To disable all probes that contain the string "vm" */ -tnfctl_probe_apply(hndl, select_disable, "vm"); -static tnfctl_errcode_t -select_disable(tnfctl_handle_t *hndl, tnfctl_probe_t *probe_hndl, -void *client_data) -{ - char *pattern = client_data; - tnfctl_probe_state_t probe_state; - tnfctl_probe_state_get(hndl, probe_hndl, &probe_state); - if (strstr(probe_state.attr_string, pattern)) { - tnfctl_probe_disable(hndl, probe_hndl, NULL); - } -} -.fi -.in -2 - -.sp -.LP -Note that these examples do not have any error handling code. - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT-Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_close (3TNF), -.BR tnfctl_probe_state_get (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf b/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf deleted file mode 100644 index 51386d7ce0..0000000000 --- a/usr/src/man/man3tnf/tnfctl_probe_state_get.3tnf +++ /dev/null @@ -1,360 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_PROBE_STATE_GET 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_probe_state_get, tnfctl_probe_enable, tnfctl_probe_disable, -tnfctl_probe_trace, tnfctl_probe_untrace, tnfctl_probe_connect, -tnfctl_probe_disconnect_all \- interfaces to query and to change the state of a -probe -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_state_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBtnfctl_probe_state_t *\fR\fIstate\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_enable\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_disable\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_trace\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_untrace\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_disconnect_all\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBvoid *\fR\fIignored\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_probe_connect\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_probe_t *\fR\fIprobe_hndl\fR, \fBconst char *\fR\fIlib_base_name\fR, - \fBconst char *\fR\fIfunc_name\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_probe_state_get()\fR returns the state of the probe specified by -\fIprobe_hndl\fR in the process or kernel specified by \fIhndl\fR. The user -will pass these in to an apply iterator. The caller must also allocate -\fIstate\fR and pass in a pointer to it. The semantics of the individual -members of \fIstate\fR are: -.sp -.ne 2 -.na -\fB\fBid\fR\fR -.ad -.RS 26n -The unique integer assigned to this probe. This number does not change over the -lifetime of this probe. A \fIprobe_hndl\fR can be obtained by using the calls -\fBtnfctl_apply()\fR, \fBtanfctl_apply_ids()\fR, or -\fBtnfctl_register_funcs()\fR. -.RE - -.sp -.ne 2 -.na -\fB\fBattr_string\fR\fR -.ad -.RS 26n -A string that consists of \fIattribute\fR \fIvalue\fR pairs separated by -semicolons. For the syntax of this string, see the syntax of the -\fBdetail\fR argument of the \fBTNF_PROBE\fR(3TNF) macro. The attributes -\fIname\fR, \fIslots\fR, \fIkeys\fR, \fBfile\fR, and \fBline\fR are defined for -every probe. Additional user-defined attributes can be added by using the -\fIdetail\fR argument of the \fBTNF_PROBE\fR(3TNF) macro. An example of -\fIattr_string\fR follows: -.sp -.in +2 -.nf -"name pageout;slots vnode pages_pageout ; -keys vm pageio io;file vm.c;line 25;" -.fi -.in -2 - -.RE - -.sp -.ne 2 -.na -\fB\fBenabled\fR\fR -.ad -.RS 26n -\fBB_TRUE\fR if the probe is enabled, or \fBB_FALSE\fR if the probe is -disabled. Probes are disabled by default. Use \fBtnfctl_probe_enable()\fR or -\fBtnfctl_probe_disable()\fR to change this state. -.RE - -.sp -.ne 2 -.na -\fB\fBtraced\fR\fR -.ad -.RS 26n -\fBB_TRUE\fR if the probe is traced, or \fBB_FALSE\fR if the probe is not -traced. Probes in user processes are traced by default. Kernel probes are -untraced by default. Use \fBtnfctl_probe_trace()\fR or -\fBtnfctl_probe_untrace()\fR to change this state. -.RE - -.sp -.ne 2 -.na -\fB\fBnew_probe\fR\fR -.ad -.RS 26n -\fBB_TRUE\fR if this is a new probe brought in since the last change in -libraries. See \fBdlopen\fR(3C) or \fBdlclose\fR(3C). Otherwise, the value of -\fBnew_probe\fR will be \fBB_FALSE\fR. This field is not meaningful for kernel -probe control. -.RE - -.sp -.ne 2 -.na -\fB\fBobj_name\fR\fR -.ad -.RS 26n -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 \fBlibtnfctl\fR interfaces. In kernel -mode, this string is always \fINULL.\fR -.RE - -.sp -.ne 2 -.na -\fB\fBfunc_names\fR\fR -.ad -.RS 26n -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 executed. This array also will be freed by the -library when the state of the probe changes. Use \fBtnfctl_probe_connect()\fR -or \fBtnfctl_probe_disconnect_all()\fR to change this state. -.RE - -.sp -.ne 2 -.na -\fB\fBfunc_addrs\fR\fR -.ad -.RS 26n -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. -.RE - -.sp -.ne 2 -.na -\fB\fBclient_registered_data\fR\fR -.ad -.RS 26n -Data that was registered by the client for this probe by the creator function -in \fBtnfctl_register_funcs\fR(3TNF). -.RE - -.sp -.LP -\fBtnfctl_probe_enable(\|),\fR \fBtnfctl_probe_disable(\|),\fR -\fBtnfctl_probe_trace(\|),\fR \fBtnfctl_probe_untrace(\|),\fR and -\fBtnfctl_probe_disconnect_all()\fR ignore the last argument. This convenient -feature permits these functions to be used in the \fIprobe_op\fR field of -\fBtnfctl_probe_apply\fR(3TNF) and \fBtnfctl_probe_apply_ids\fR(3TNF). -\fBtnfctl_probe_enable()\fR enables the probe specified by \fIprobe_hndl\fR. -This is the master switch on a probe. A probe does not perform any action -until it is enabled. -.sp -.LP -\fBtnfctl_probe_disable()\fR disables the probe specified by \fIprobe_hndl\fR. -.sp -.LP -\fBtnfctl_probe_trace()\fR turns on tracing for the probe specified by -\fIprobe_hndl\fR. Probes emit a trace record only if the probe is traced. -.sp -.LP -\fBtnfctl_probe_untrace()\fR turns off tracing for the probe specified by -\fIprobe_hndl\fR. This is useful if you want to connect probe functions to a -probe without tracing it. -.sp -.LP -\fBtnfctl_probe_connect()\fR connects the function \fIfunc_name\fR which exists -in the library \fIlib_base_name\fR, to the probe specified by -\fIprobe_hndl\fR. \fBtnfctl_probe_connect()\fR returns an error code if used on -a kernel tnfctl handle. \fIlib_base_name\fR is the base name (not a path) of -the library. If it is \fINULL,\fR and multiple functions in the target -process match \fIfunc_name\fR, 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 specification is not -currently published. -.sp -.LP -\fBtnf_probe_debug()\fR is one function exported by \fBlibtnfprobe.so.1\fR and -is the debug function that \fBprex\fR(1) uses. When the debug function is -executed, it prints out the probe arguments and the value of the -\fBsunw%debug\fR attribute of the probe to \fBstderr\fR. -.sp -.LP -\fBtnfctl_probe_disconnect_all()\fR disconnects all probe functions from the -probe specified by \fIprobe_hndl\fR. -.sp -.LP -Note that no \fBlibtnfctl\fR call returns a probe handle -(\fBtnfctl_probe_t\fR), yet each of the routines described here takes a -\fIprobe_hndl\fR as an argument. These routines may be used by passing them to -one of the \fBtnfctl_probe_apply\fR(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 \fIprobe_hndl\fR argument when -using any of the functions described here. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_probe_state_get(\|),\fR \fBtnfctl_probe_enable(\|),\fR -\fBtnfctl_probe_disable(\|),\fR \fBtnfctl_probe_trace(\|),\fR -\fBtnfctl_probe_untrace(\|),\fR \fBtnfctl_probe_disconnect_all()\fR and -\fBtnfctl_probe_connect()\fR return \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_probe_state_get()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -\fIprobe_hndl\fR is no longer valid. The library that the probe was in could -have been dynamically closed by \fBdlclose\fR(3C). -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_probe_enable()\fR, -\fBtnfctl_probe_disable()\fR, \fBtnfctl_probe_trace()\fR, -\fBtnfctl_probe_untrace()\fR, and \fBtnfctl_probe_disconnect_all()\fR -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -\fIprobe_hndl\fR is no longer valid. The library that the probe was in could -have been dynamically closed by \fBdlclose\fR(3C). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 27n -Cannot do probe operations because tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 27n -Cannot do probe operations until a buffer is allocated. See -\fBtnfctl_buffer_alloc\fR(3TNF). This error code does not apply to kernel -probe control. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_probe_connect()\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INVALIDPROBE\fR\fR -.ad -.RS 27n -\fIprobe_hndl\fR is no longer valid. The library that the probe was in could -have been dynamically closed by \fBdlclose\fR(3C). -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 27n -The handle is a kernel handle, or \fIfunc_name\fR could not be found. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 27n -Cannot do probe operations because tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 27n -Cannot do probe operations until a buffer is allocated. See -\fBtnfctl_buffer_alloc\fR(3TNF). -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for description of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_check_libs (3TNF), -.BR tnfctl_continue (3TNF), -.BR tnfctl_probe_apply (3TNF), -.BR tnfctl_probe_apply_ids (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_register_funcs.3tnf b/usr/src/man/man3tnf/tnfctl_register_funcs.3tnf deleted file mode 100644 index 55cb11ea8f..0000000000 --- a/usr/src/man/man3tnf/tnfctl_register_funcs.3tnf +++ /dev/null @@ -1,86 +0,0 @@ -'\" te -.\" Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_REGISTER_FUNCS 3TNF "Mar 1, 2004" -.SH NAME -tnfctl_register_funcs \- register callbacks for probe creation and destruction -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_register_funcs\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, \fBvoid * (*\fR\fIcreate_func\fR) - (tnfctl_handle_t *, tnfctl_probe_t *), \fBvoid (*\fR\fIdestroy_func\fR)(void *)); -.fi - -.SH DESCRIPTION -.sp -.LP -The function \fBtnfctl_register_funcs()\fR is used to store client-specific -data on a per-probe basis. It registers a creator and a destructor function -with \fIhndl\fR, either of which can be \fBNULL.\fR The creator function is -called for every probe that currently exists in \fIhndl.\fR Every time a new -probe is discovered, that is brought in by \fBdlopen\fR(3C), \fIcreate_func\fR -is called. -.sp -.LP -The return value of the creator function is stored as part of the probe state -and can be retrieved by \fBtnfctl_probe_state_get\fR(3TNF) in the member field -\fIclient_registered_data\fR. -.sp -.LP -\fIdestroy_func\fR is called for every probe handle that is freed. This does -not necessarily happen at the time \fBdlclose\fR(3C) frees the shared object. -The probe handles are freed only when \fIhndl\fR is closed by -\fBtnfctl_close\fR(3TNF). If \fBtnfctl_register_funcs()\fR is called a second -time for the same \fIhndl,\fR then the previously registered destructor -function is called first for all of the probes. -.SH RETURN VALUES -.sp -.LP -\fBtnfctl_register_funcs()\fR returns \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR dlclose (3C), -.BR dlopen (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_close (3TNF), -.BR tnfctl_probe_state_get (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) -.sp -.LP -\fILinker and Libraries Guide\fR diff --git a/usr/src/man/man3tnf/tnfctl_strerror.3tnf b/usr/src/man/man3tnf/tnfctl_strerror.3tnf deleted file mode 100644 index 651a36b6e4..0000000000 --- a/usr/src/man/man3tnf/tnfctl_strerror.3tnf +++ /dev/null @@ -1,54 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_STRERROR 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_strerror \- map a tnfctl error code to a string -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - - - -\fBconst char *\fR \fBtnfctl_strerror\fR(\fBtnfctl_errcode_t\fR \fIerrcode\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -\fBtnfctl_strerror()\fR maps the error number in \fIerrcode\fR to an error -message string, and it returns a pointer to that string. The returned string -should not be overwritten or freed. -.SH ERRORS -.sp -.LP -\fBtnfctl_strerror()\fR returns the string "unknown libtnfctl.so error code" if -the error number is not within the legal range. -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf b/usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf deleted file mode 100644 index f22726793a..0000000000 --- a/usr/src/man/man3tnf/tnfctl_trace_attrs_get.3tnf +++ /dev/null @@ -1,184 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_TRACE_ATTRS_GET 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_trace_attrs_get \- get the trace attributes from a tnfctl handle -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ltnfctl\fR [ \fIlibrary\fR... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_trace_attrs_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBtnfctl_trace_attrs_t *\fR\fIattrs\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function returns the trace attributes -associated with \fIhndl\fR in \fIattrs\fR. The trace attributes can be changed -by some of the other interfaces in \fBlibtnfctl\fR(3TNF). It is the client's -responsibility to use \fBtnfctl_trace_attrs_get()\fR to get the new trace -attributes after use of interfaces that change them. Typically, a client will -use \fBtnfctl_trace_attrs_get()\fR after a call to \fBtnfctl_continue\fR(3TNF) -in order to make sure that tracing is still working. See the discussion of -\fBtrace_buf_state\fR that follows. -.sp -.LP -Trace attributes are represented by the \fBstruct tnfctl_trace_attrs\fR -structure defined in <\fBtnf/tnfctl.h\fR>: -.sp -.in +2 -.nf -struct tnfctl_trace_attrs { -pid_t targ_pid; /* not kernel mode */ -const char *trace_file_name; /* not kernel mode */ -size_t trace_buf_size; -size_t trace_min_size; -tnfctl_bufstate_t trace_buf_state; -boolean_t trace_state; -boolean_t filter_state; /* kernel mode only */ -long pad; -}; -.fi -.in -2 - -.sp -.LP -The semantics of the individual members of \fIattrs\fR are: -.sp -.ne 2 -.na -\fB\fBtarg_pid\fR\fR -.ad -.RS 19n -The process id of the target process. This is not valid for kernel tracing. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_file_name\fR\fR -.ad -.RS 19n -The name of the trace file to which the target writes. \fBtrace_file_name\fR -will be \fBNULL\fR if no trace file exists or if kernel tracing is implemented. -This pointer should not be used after calling other \fBlibtnfctl\fR interfaces. -The client should copy this string if it should be saved for the use of other -\fBlibtnfctl\fR interfaces. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_buf_size\fR\fR -.ad -.RS 19n -The size of the trace buffer or file in bytes. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_min_size\fR\fR -.ad -.RS 19n -The minimum size in bytes of the trace buffer that can be allocated by using -the \fBtnfctl_buffer_alloc\fR(3TNF) interface. -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_buf_state\fR\fR -.ad -.RS 19n -The state of the trace buffer. \fBTNFCTL_BUF_OK\fR indicates that a trace -buffer has been allocated. \fBTNFCTL_BUF_NONE\fR indicates that no buffer has -been allocated. \fBTNFCTL_BUF_BROKEN\fR indicates that there is an internal -error in the target for tracing. The target will continue to run correctly, but -no trace records will be written. To fix tracing, restart the process. For -kernel tracing, deallocate the existing buffer with -\fBtnfctl_buffer_dealloc\fR(3TNF) and allocate a new one with -\fBtnfctl_buffer_alloc\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtrace_state\fR\fR -.ad -.RS 19n -The global tracing state of the target. Probes that are enabled will not write -out data unless this state is on. This state is off by default for the kernel -and can be changed by \fBtnfctl_trace_state_set\fR(3TNF). For a process, this -state is on by default and can only be changed by -\fBtnf_process_disable\fR(3TNF) and \fBtnf_process_enable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBfilter_state\fR\fR -.ad -.RS 19n -The state of process filtering. For kernel probe control, it is possible to -select a set of processes for which probes are enabled. See -\fBtnfctl_filter_list_get\fR(3TNF), \fBtnfctl_filter_list_add\fR(3TNF), and -\fBtnfctl_filter_list_delete\fR(3TNF). No trace output will be written when -other processes traverse these probe points. By default process filtering is -off, and all processes cause the generation of trace records when they hit an -enabled probe. Use \fBtnfctl_filter_state_set\fR(3TNF) to change the filter -state. -.RE - -.SH RETURN VALUES -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function returns \fBTNFCTL_ERR_NONE\fR upon -success. -.SH ERRORS -.sp -.LP -The \fBtnfctl_trace_attrs_get()\fR function will fail if: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tnfctl_buffer_alloc (3TNF), -.BR tnfctl_continue (3TNF), -.BR tnfctl_filter_list_get (3TNF), -.BR tracing (3TNF), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf b/usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf deleted file mode 100644 index 21f927757b..0000000000 --- a/usr/src/man/man3tnf/tnfctl_trace_state_set.3tnf +++ /dev/null @@ -1,277 +0,0 @@ -'\" te -.\" Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNFCTL_TRACE_STATE_SET 3TNF "Mar 4, 1997" -.SH NAME -tnfctl_trace_state_set, tnfctl_filter_state_set, tnfctl_filter_list_get, -tnfctl_filter_list_add, tnfctl_filter_list_delete \- control kernel tracing and -process filtering -.SH SYNOPSIS -.LP -.nf -\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-ltnfctl\fR [ \fIlibrary\fR ... ] -#include <tnf/tnfctl.h> - -\fBtnfctl_errcode_t\fR \fBtnfctl_trace_state_set\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBboolean_t\fR \fItrace_state\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_state_set\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBboolean_t\fR \fIfilter_state\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_get\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBpid_t **\fR\fIpid_list\fR,\ \fBint *\fR\fIpid_count\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_add\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBpid_t\fR \fIpid_to_add\fR); -.fi - -.LP -.nf -\fBtnfctl_errcode_t\fR \fBtnfctl_filter_list_delete\fR(\fBtnfctl_handle_t *\fR\fIhndl\fR, - \fBpid_t\fR \fIpid_to_delete\fR); -.fi - -.SH DESCRIPTION -.sp -.LP -The interfaces to control kernel tracing and process filtering are used only -with kernel handles, handles created by \fBtnfctl_kernel_open\fR(3TNF). These -interfaces are used to change the tracing and filter states for kernel -tracing. -.sp -.LP -\fBtnfctl_trace_state_set()\fR sets the kernel global tracing state to "on" if -\fItrace_state\fR is \fBB_TRUE,\fR or to "off" if \fItrace_state\fR is -\fBB_FALSE.\fR For the kernel, \fItrace_state\fR is off by default.Probes that -are enabled will not write out data unless this state is on. Use -\fBtnfctl_trace_attrs_get\fR(3TNF) to retrieve the current tracing state. -.sp -.LP -\fBtnfctl_filter_state_set()\fR sets the kernel process filtering state to "on" -if \fIfilter_state\fR is \fBB_TRUE,\fR or to "off" if \fIfilter_state\fR is -\fBB_FALSE.\fR \fIfilter_state\fR is off by default. If it is on, only probe -points encountered by processes in the process filter set by -\fBtnfctl_filter_list_add()\fR will generate trace points. Use -\fBtnfctl_trace_attrs_get\fR(3TNF) to retrieve the current process filtering -state. -.sp -.LP -\fBtnfctl_filter_list_get()\fR returns the process filter list as an array in -\fIpid_list\fR. The count of elements in the process filter list is returned in -\fIpid_count\fR. The caller should use \fBfree\fR(3C) to free memory allocated -for the array \fIpid_list\fR. -.sp -.LP -\fBtnfctl_filter_list_add()\fR adds \fIpid_to_add\fR to the process filter -list. The process filter list is maintained even when the process filtering -state is off, but it has no effect unless the process filtering state is on. -.sp -.LP -\fBtnfctl_filter_list_delete()\fR deletes \fIpid_to_delete\fR from the process -filter list. It returns an error if the process does not exist or is not in -the filter list. -.SH RETURN VALUES -.sp -.LP -The interfaces \fBtnfctl_trace_state_set()\fR, \fBtnfctl_filter_state_set()\fR, -\fBtnfctl_filter_list_add()\fR, \fBtnfctl_filter_list_delete()\fR, and -\fBtnfctl_filter_list_get()\fR return \fBTNFCTL_ERR_NONE\fR upon success. -.SH ERRORS -.sp -.LP -The following error codes apply to \fBtnfctl_trace_state_set\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOBUF\fR\fR -.ad -.RS 24n -Cannot turn on tracing without a buffer being allocated. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BUFBROKEN\fR\fR -.ad -.RS 24n -Tracing is broken in the target. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_state_set\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 23n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 23n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_list_add\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 24n -No such process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 24n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_list_delete\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_NOPROCESS\fR\fR -.ad -.RS 24n -No such process exists. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.sp -.LP -The following error codes apply to \fBtnfctl_filter_list_get\fR: -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_BADARG\fR\fR -.ad -.RS 24n -The handle is not a kernel handle. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_ALLOCFAIL\fR\fR -.ad -.RS 24n -A memory allocation failure occurred. -.RE - -.sp -.ne 2 -.na -\fB\fBTNFCTL_ERR_INTERNAL\fR\fR -.ad -.RS 24n -An internal error occurred. -.RE - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR free (3C), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnfctl_kernel_open (3TNF), -.BR tnfctl_trace_attrs_get (3TNF), -.BR tracing (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) diff --git a/usr/src/man/man3tnf/tracing.3tnf b/usr/src/man/man3tnf/tracing.3tnf deleted file mode 100644 index 7fee555446..0000000000 --- a/usr/src/man/man3tnf/tracing.3tnf +++ /dev/null @@ -1,313 +0,0 @@ -'\" te -.\" Copyright (c) 1997, Sun Microsystems, Inc. -.\" All Rights Reserved -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TRACING 3TNF "Mar 4, 1997" -.SH NAME -tracing \- overview of tnf tracing system -.SH DESCRIPTION -.sp -.LP -\fBtnf tracing\fR is a set of programs and \fBAPI's\fR that can be used to -present a high-level view of the performance of an executable, a library, or -part of the kernel. \fBtracing\fR is used to analyze a program's performance -and identify the conditions that produced a bug. -.sp -.LP -The core elements of \fBtracing\fR are: -.sp -.ne 2 -.na -\fB\fBTNF_PROBE_*(\|)\fR\fR -.ad -.RS 25n -The \fBTNF_PROBE_*(\|)\fR macros define "probes" to be placed in code which, -when enabled and executed, cause information to be added to a trace file. See -\fBTNF_PROBE\fR(3TNF). If there are insufficient \fBTNF_PROBE_*\fR macros to -store all the data of interest for a probe, data may be grouped into records. -See \fBTNF_DECLARE_RECORD\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBprex\fR\fR -.ad -.RS 25n -Displays and controls probes in running software. See prex(1). -.RE - -.sp -.ne 2 -.na -\fB\fBkernel\fR \fBprobes\fR\fR -.ad -.RS 25n -A set of probes built into the Solaris kernel which capture information about -system calls, multithreading, page faults, swapping, memory management, and -I/O. You can use these probes to obtain detailed traces of kernel activity -under your application workloads. See \fBtnf_kernel_probes\fR(5). -.RE - -.sp -.ne 2 -.na -\fB\fBtnfxtract\fR\fR -.ad -.RS 25n -A program that extracts the trace data from the kernel's in-memory buffer into -a file. See \fBtnfxtract\fR(1). -.RE - -.sp -.ne 2 -.na -\fB\fBtnfdump\fR\fR -.ad -.RS 25n -A program that displays the information from a trace file. See -\fBtnfdump\fR(1). -.RE - -.sp -.ne 2 -.na -\fB\fBlibtnfctl\fR\fR -.ad -.RS 25n -A library of interfaces that controls probes in a process. See -\fBlibtnfctl\fR(3TNF). \fBprex\fR(1) also utilizes this library. Other tools -and processes use the \fBlibtnfctl\fR interfaces to exercise fine control over -their own probes. -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_process_enable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn on tracing and probe functions for the -current process. See \fBtnf_process_enable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_process_disable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn off tracing and probe functions for the -current process. See \fBtnf_process_disable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_thread_enable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn on tracing and probe functions for the -currently running thread. See \fBtnf_thread_enable\fR(3TNF). -.RE - -.sp -.ne 2 -.na -\fB\fBtnf_thread_disable()\fR\fR -.ad -.RS 25n -A routine called by a process to turn off tracing and probe functions for the -currently running thread. See \fBtnf_thread_disable\fR(3TNF). -.RE - -.SH EXAMPLES -.LP -\fBExample 1 \fRTracing a Process -.sp -.LP -The following function in some daemon process accepts job requests of various -types, queueing them for later execution. There are two "debug probes" and one -"production probe." Note that probes which are intended for debugging will not -be compiled into the final version of the code; however, production probes are -compiled into the final product. - -.sp -.in +2 -.nf - /* - * To compile in all probes (for development): - * cc -DTNF_DEBUG ... - * - * To compile in only production probes (for release): - * cc ... - * - * To compile in no probes at all: - * cc -DNPROBE ... - */ -#include <tnf/probe.h> -void work(long, char *); -enum work_request_type { READ, WRITE, ERASE, UPDATE }; -static char *work_request_name[] = {"read", "write", "erase", "update"}; -main(\|) -{ - long i; - for (i = READ; i <= UPDATE; i++) - work(i, work_request_name[i]); -} -void work(long request_type, char *request_name) -{ - static long q_length; - TNF_PROBE_2_DEBUG(work_start, "work", - "XYZ%debug 'in function work'", - tnf_long, request_type_arg, request_type, - tnf_string, request_name_arg, request_name); - /* assume work request is queued for later processing */ - q_length++; - TNF_PROBE_1(work_queue, "work queue", - "XYZ%work_load heavy", - tnf_long, queue_length, q_length); - TNF_PROBE_0_DEBUG(work_end, "work", ""); -} -.fi -.in -2 - -.sp -.LP -The production probe "work_queue," which remains compiled in the code, will, -when enabled, log the length of the work queue each time a request is received. - -.sp -.LP -The debug probes "work_start" and "work_end, " which are compiled only during -the development phase, track entry to and exit from the \fBwork()\fR function -and measure how much time is spent executing it. Additionally, the debug probe -"work_start" logs the value of the two incoming arguments \fBrequest_type\fR -and \fBrequest_name\fR. The runtime overhead for disabled probes is low enough -that one can liberally embed them in the code with little impact on -performance. - -.sp -.LP -For debugging, the developer would compile with \fB-DTNF_DEBUG\fR, run the -program under control of \fBprex\fR(1), enable the probes of interest (in this -case, all probes), continue the program until exit, and dump the trace file: - -.sp -.in +2 -.nf -% cc --DTNF_DEBUG -o daemon daemon.c # compile in all probes -% prex daemon # run program under prex control -Target process stopped -Type "continue" to resume the target, "help" for help ... -prex> list probes $all # list all probes in program -<probe list output here> -prex> enable $all # enable all probes -prex> continue # let target process execute -<program output here> -prex: target process finished -% ls /tmp/trace-* # trace output is in trace-<pid> -/tmp/trace-4194 -% tnfdump /tmp/trace-4194 # get ascii output of trace file -<trace records output here> -.fi -.in -2 - -.sp -.LP -For the production version of the system, the developer simply compiles without -\fB-DTNF_DEBUG\fR\&. - -.LP -\fBExample 2 \fRTracing the Kernel -.sp -.LP -Kernel tracing is similar to tracing a process; however, there are some -differences. For instance, to trace the kernel, you need superuser privileges. -The following example uses prex(1) and traces the probes in the kernel that -capture system call information. - -.sp -.in +2 -.nf -Allocate kernel -trace buffer and capture trace data: -root# prex -k -Type "help" for help ... -prex> buffer alloc 2m # allocate kernel trace buffer -Buffer of size 2097152 bytes allocated -prex> list probes $all # list all kernel probes -<probe list output here> -prex> list probes syscall # list syscall probes - # (keys=syscall) -<syscall probes list output here> -prex> enable syscall # enable only syscall probes -prex> ktrace on # turn on kernel tracing -<Run your application in another window at this point> -prex> ktrace off # turn off kernel tracing -prex> quit # exit prex -Extract the kernel's trace buffer into a file: -root# tnfxtract /tmp/ktrace # extract kernel trace buffer -Reset kernel tracing: -root# prex -k -prex> disable $all # disable all probes -prex> untrace $all # untrace all probes -prex> buffer dealloc # deallocate kernel trace buffer -prex> quit -.fi -.in -2 - -.sp -.LP -CAUTION: Do not deallocate the trace buffer until you have extracted it into -a trace file. Otherwise, you will lose the trace data that you collected from -your experiment! - -.sp -.LP -Examine the kernel trace file: - -.sp -.in +2 -.nf -root# tnfdump /tmp/ktrace # get ascii dump of trace file -<trace records output here> -.fi -.in -2 - -.sp -.LP -\fBprex\fR can also attach to a running process, list probes, and perform a -variety of other tasks. - -.SH ATTRIBUTES -.sp -.LP -See \fBattributes\fR(7) for descriptions of the following attributes: -.sp - -.sp -.TS -box; -c | c -l | l . -ATTRIBUTE TYPE ATTRIBUTE VALUE -_ -MT Level MT-Safe -.TE - -.SH SEE ALSO -.sp -.LP -.BR prex (1), -.BR tnfdump (1), -.BR tnfxtract (1), -.BR TNF_DECLARE_RECORD (3TNF), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tnf_process_disable (3TNF), -.BR tnf_kernel_probes (5), -.BR attributes (7) diff --git a/usr/src/man/man5/Makefile b/usr/src/man/man5/Makefile index ead3d03a48..628602dfe2 100644 --- a/usr/src/man/man5/Makefile +++ b/usr/src/man/man5/Makefile @@ -182,7 +182,6 @@ _MANFILES= Intro.5 \ term.5 \ terminfo.5 \ timezone.5 \ - tnf_kernel_probes.5 \ ts_dptbl.5 \ ttydefs.5 \ ttysrch.5 \ diff --git a/usr/src/man/man5/tnf_kernel_probes.5 b/usr/src/man/man5/tnf_kernel_probes.5 deleted file mode 100644 index d01df72197..0000000000 --- a/usr/src/man/man5/tnf_kernel_probes.5 +++ /dev/null @@ -1,949 +0,0 @@ -'\" te -.\" Copyright 1999 Sun Microsystems, Inc. All Rights Reserved. -.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. -.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. -.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] -.TH TNF_KERNEL_PROBES 5 "June 20, 2021" -.SH NAME -tnf_kernel_probes \- TNF kernel probes -.SH DESCRIPTION -The set of probes (trace instrumentation points) available in the standard -kernel. The probes log trace data to a kernel trace buffer in Trace Normal -Form (TNF). Kernel probes are controlled by \fBprex\fR(1). A snapshot of the -kernel trace buffer can be made using \fBtnfxtract\fR(1) and examined using -\fBtnfdump\fR(1). -.sp -.LP -Each probe has a \fIname\fR and is associated with a set of symbolic -\fIkeys\fR, or \fIcategories\fR. These are used to select and control probes -from \fBprex\fR(1). A probe that is enabled for tracing generates a \fBTNF\fR -record, called an \fIevent record\fR. An event record contains two common -members and may contain other probe-specific data members. -.SS "Common Members" -.in +2 -.nf -\fBtnf_probe_event\fR \fItag\fR -\fBtnf_time_delta\fR \fItime_delta\fR -.fi -.in -2 - -.sp -.ne 2 -.na -\fB\fItag\fR\fR -.ad -.RS 14n -Encodes \fBTNF\fR references to two other records: -.sp -.ne 2 -.na -\fB\fItag\fR\fR -.ad -.RS 12n -Describes the layout of the event record. -.RE - -.sp -.ne 2 -.na -\fB\fIschedule\fR\fR -.ad -.RS 12n -Identifies the writing thread and also contains a 64-bit base time in -nanoseconds. -.RE - -.RE - -.sp -.ne 2 -.na -\fB\fItime_delta\fR\fR -.ad -.RS 14n -A 32-bit time offset from the base time; the sum of the two times is the actual -time of the event. -.RE - -.SS "Threads" -.SS "\fBthread_create\fR" -.in +2 -.nf -\fBtnf_kthread_id\fR \fItid\fR -\fBtnf_pid\fR \fIpid\fR -\fBtnf_symbol\fR \fIstart_pc\fR -.fi -.in -2 - -.sp -.LP -Thread creation event. -.sp -.ne 2 -.na -\fB\fItid\fR\fR -.ad -.RS 12n -The thread identifier for the new thread. -.RE - -.sp -.ne 2 -.na -\fB\fIpid\fR\fR -.ad -.RS 12n -The process identifier for the new thread. -.RE - -.sp -.ne 2 -.na -\fB\fIstart_pc\fR\fR -.ad -.RS 12n -The kernel address of its start routine. -.RE - -.SS "\fBthread_state\fR" -.in +2 -.nf -\fBtnf_kthread_id\fR \fItid\fR -\fBtnf_microstate\fR \fIstate\fR -.fi -.in -2 - -.sp -.LP -Thread microstate transition events. -.sp -.ne 2 -.na -\fB\fItid\fR\fR -.ad -.RS 9n -Optional; if it is absent, the event is for the writing thread, otherwise the -event is for the specified thread. -.RE - -.sp -.ne 2 -.na -\fB\fIstate\fR\fR -.ad -.RS 9n -Indicates the thread state: -.RS +4 -.TP -.ie t \(bu -.el o -Running in user mode. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Running in system mode. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Asleep waiting for a user-mode lock. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Asleep on a kernel object. -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Runnable (waiting for a cpu). -.RE -.RS +4 -.TP -.ie t \(bu -.el o -Stopped. -.RE -The values of this member are defined in <\fBsys/msacct.h\fR>. Note that to -reduce trace output, transitions between the \fIsystem\fR and \fIuser\fR -microstates that are induced by system calls are not traced. This information -is implicit in the system call entry and exit events. -.RE - -.SS "thread_exit" -Thread termination event for writing thread. This probe has no data members -other than the common members. -.SS "Scheduling" -\fB\fR -.SS "thread_queue" -.in +2 -.nf -\fBtnf_kthread_id\fR \fItid\fR -\fBtnf_cpuid\fR \fIcpuid\fR -\fBtnf_long\fR \fIpriority\fR -\fBtnf_ulong\fR \fIqueue_length\fR -.fi -.in -2 - -.sp -.LP -Thread scheduling events. These are triggered when a runnable thread is placed -on a dispatch queue. -.sp -.ne 2 -.na -\fB\fIcpuid\fR\fR -.ad -.RS 16n -Specifies the cpu to which the queue is attached. -.RE - -.sp -.ne 2 -.na -\fB\fIpriority\fR\fR -.ad -.RS 16n -The (global) dispatch priority of the thread. -.RE - -.sp -.ne 2 -.na -\fB\fIqueue_length\fR\fR -.ad -.RS 16n -The current length of the cpu's dispatch queue. -.RE - -.SS "Blocking" -.SS "\fBthread_block\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIreason\fR -\fBtnf_symbols\fR \fIstack\fR -.fi -.in -2 - -.sp -.LP -Thread blockage event. This probe captures a partial stack backtrace when the -current thread blocks. -.sp -.ne 2 -.na -\fB\fIreason\fR\fR -.ad -.RS 11n -The address of the object on which the thread is blocking. -.RE - -.sp -.ne 2 -.na -\fB\fIsymbols\fR\fR -.ad -.RS 11n -References a \fBTNF\fR array of kernel addresses representing the PCs on the -stack at the time the thread blocks. -.RE - -.SS "System Calls" -.SS "\fBsyscall_start\fR" -.in +2 -.nf -\fBtnf_sysnum\fR \fIsysnum\fR -.fi -.in -2 - -.sp -.LP -System call entry event. -.sp -.ne 2 -.na -\fB\fIsysnum\fR\fR -.ad -.RS 10n -The system call number. The writing thread implicitly enters the \fIsystem\fR -microstate with this event. -.RE - -.SS "\fBsyscall_end\fR" -.in +2 -.nf -\fBtnf_long\fR \fIrval1\fR -\fBtnf_long\fR \fIrval2\fR -\fBtnf_long\fR \fIerrno\fR -.fi -.in -2 - -.sp -.LP -System call exit event. -.sp -.ne 2 -.na -\fB\fIrval1\fR and \fIrval2\fR\fR -.ad -.RS 19n -The two return values of the system call -.RE - -.sp -.ne 2 -.na -\fB\fIerrno\fR\fR -.ad -.RS 19n -The error return. -.RE - -.sp -.LP -The writing thread implicitly enters the \fIuser\fR microstate with this event. -.SS "Page Faults" -.SS "\fBaddress_fault\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIaddress\fR -\fBtnf_fault_type\fR \fIfault_type\fR -\fBtnf_seg_access\fR \fIaccess\fR -.fi -.in -2 - -.sp -.LP -Address-space fault event. -.sp -.ne 2 -.na -\fB\fIaddress\fR\fR -.ad -.RS 14n -Gives the faulting virtual address. -.RE - -.sp -.ne 2 -.na -\fB\fIfault_type\fR\fR -.ad -.RS 14n -Gives the fault type: invalid page, protection fault, software requested -locking or unlocking. -.RE - -.sp -.ne 2 -.na -\fB\fIaccess\fR\fR -.ad -.RS 14n -Gives the desired access protection: read, write, execute or create. The values -for these two members are defined in <\fBvm/seg_enum.h\fR>. -.RE - -.SS "\fBmajor_fault\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIvnode\fR -\fBtnf_offset\fR \fIoffset\fR -.fi -.in -2 - -.sp -.LP -Major page fault event. The faulting page is mapped to the file given by the -\fIvnode\fR member, at the given \fIoffset\fR into the file. (The faulting -virtual address is in the most recent \fBaddress_fault\fR event for the writing -thread.) -.SS "\fBanon_private\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIaddress\fR -.fi -.in -2 - -.sp -.LP -Copy-on-write page fault event. -.sp -.ne 2 -.na -\fB\fIaddress\fR\fR -.ad -.RS 11n -The virtual address at which the new page is mapped. -.RE - -.SS "\fBanon_zero\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIaddress\fR -.fi -.in -2 - -.sp -.LP -Zero-fill page fault event. -.sp -.ne 2 -.na -\fB\fIaddress\fR\fR -.ad -.RS 11n -The virtual address at which the new page is mapped. -.RE - -.SS "\fBpage_unmap\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIvnode\fR -\fBtnf_offset\fR \fIoffset\fR -.fi -.in -2 - -.sp -.LP -Page unmapping event. This probe marks the unmapping of a file system page -from the system. -.sp -.ne 2 -.na -\fB\fIvnode\fR and \fIoffset\fR\fR -.ad -.RS 20n -Identifies the file and offset of the page being unmapped. -.RE - -.SS "Pageins and Pageouts" -.SS "\fBpagein\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIvnode\fR -\fBtnf_offset\fR \fIoffset\fR -\fBtnf_size\fR \fIsize\fR -.fi -.in -2 - -.sp -.LP -Pagein start event. This event signals the initiation of pagein I/O. -.sp -.ne 2 -.na -\fB\fIvnode\fR and \fIoffset\fR\fR -.ad -.RS 18n -Identifies the file and offset to be paged in. -.RE - -.sp -.ne 2 -.na -\fB\fIsize\fR\fR -.ad -.RS 18n -Specifies the number of bytes to be paged in. -.RE - -.SS "\fBpageout\fR" -.in +2 -.nf -\fBtnf_opaque\fR \fIvnode\fR -\fBtnf_ulong\fR \fIpages_pageout\fR -\fBtnf_ulong\fR \fIpages_freed\fR -\fBtnf_ulong\fR \fIpages_reclaimed\fR -.fi -.in -2 - -.sp -.LP -Pageout completion event. This event signals the completion of pageout I/O. -.sp -.ne 2 -.na -\fB\fIvnode\fR\fR -.ad -.RS 19n -Identifies the file of the pageout request. -.RE - -.sp -.ne 2 -.na -\fB\fIpages_pageout\fR\fR -.ad -.RS 19n -The number of pages written out. -.RE - -.sp -.ne 2 -.na -\fB\fIpages_freed\fR\fR -.ad -.RS 19n -The number of pages freed after being written out. -.RE - -.sp -.ne 2 -.na -\fB\fIpages_reclaimed\fR\fR -.ad -.RS 19n -The number of pages reclaimed after being written out. -.RE - -.SS "Page Daemon (Page Stealer)" -.SS "\fBpageout_scan_start\fR" -.in +2 -.nf -\fBtnf_ulong\fR \fIpages_free\fR -\fBtnf_ulong\fR \fIpages_needed\fR -.fi -.in -2 - -.sp -.LP -Page daemon scan start event. This event signals the beginning of one -iteration of the page daemon. -.sp -.ne 2 -.na -\fB\fIpages_free\fR\fR -.ad -.RS 16n -The number of free pages in the system. -.RE - -.sp -.ne 2 -.na -\fB\fIpages_needed\fR\fR -.ad -.RS 16n -The number of pages desired free. -.RE - -.SS "\fBpageout_scan_end\fR" -.in +2 -.nf -\fBtnf_ulong\fR \fIpages_free\fR -\fBtnf_ulong\fR \fIpages_scanned\fR -.fi -.in -2 - -.sp -.LP -Page daemon scan end event. This event signals the end of one iteration of the -page daemon. -.sp -.ne 2 -.na -\fB\fIpages_free\fR\fR -.ad -.RS 17n -The number of free pages in the system. -.RE - -.sp -.ne 2 -.na -\fB\fIpages_scanned\fR\fR -.ad -.RS 17n -The number of pages examined by the page daemon. (Potentially more pages will -be freed when any queued pageout requests complete.) -.RE - -.SS "Swapper" -.SS "\fBswapout_process\fR" -.in +2 -.nf -\fBtnf_pid\fR \fIpid\fR -\fBtnf_ulong\fR \fIpage_count\fR -.fi -.in -2 - -.sp -.LP -Address space swapout event. This event marks the swapping out of a process -address space. -.sp -.ne 2 -.na -\fB\fIpid\fR\fR -.ad -.RS 14n -Identifies the process. -.RE - -.sp -.ne 2 -.na -\fB\fIpage_count\fR\fR -.ad -.RS 14n -Reports the number of pages either freed or queued for pageout. -.RE - -.SS "\fBswapout_lwp\fR" -.in +2 -.nf -\fBtnf_pid\fR \fIpid\fR -\fBtnf_lwpid\fR \fIlwpid\fR -\fBtnf_kthread_id\fR \fItid\fR -\fBtnf_ulong\fR \fIpage_count\fR -.fi -.in -2 - -.sp -.LP -Light-weight process swapout event. This event marks the swapping out of an -\fBLWP\fR and its stack. -.sp -.ne 2 -.na -\fB\fIpid\fR\fR -.ad -.RS 14n -The \fBLWP's\fR process identifier -.RE - -.sp -.ne 2 -.na -\fB\fIlwpid\fR\fR -.ad -.RS 14n -The \fBLWP\fR identifier -.RE - -.sp -.ne 2 -.na -\fB\fItid\fR \fImember\fR\fR -.ad -.RS 14n -The \fBLWP's\fR kernel thread identifier. -.RE - -.sp -.ne 2 -.na -\fB\fIpage_count\fR\fR -.ad -.RS 14n -The number of pages swapped out. -.RE - -.SS "\fBswapin_lwp\fR" -.in +2 -.nf -\fBtnf_pid\fR \fIpid\fR -\fBtnf_lwpid\fR \fIlwpid\fR -\fBtnf_kthread_id\fR \fItid\fR -\fBtnf_ulong\fR \fIpage_count\fR -.fi -.in -2 - -.sp -.LP -Light-weight process swapin event. This event marks the swapping in of an -\fBLWP\fR and its stack. -.sp -.ne 2 -.na -\fB\fIpid\fR\fR -.ad -.RS 14n -The \fBLWP's\fR process identifier. -.RE - -.sp -.ne 2 -.na -\fB\fIlwpid\fR\fR -.ad -.RS 14n -The \fBLWP\fR identifier. -.RE - -.sp -.ne 2 -.na -\fB\fItid\fR\fR -.ad -.RS 14n -The \fBLWP's\fR kernel thread identifier. -.RE - -.sp -.ne 2 -.na -\fB\fIpage_count\fR\fR -.ad -.RS 14n -The number of pages swapped in. -.RE - -.SS "Local I/O" -.SS "\fBstrategy\fR" -.in +2 -.nf -\fBtnf_device\fR \fIdevice\fR -\fBtnf_diskaddr\fR \fIblock\fR -\fBtnf_size\fR \fIsize\fR -\fBtnf_opaque\fR \fIbuf\fR -\fBtnf_bioflags\fR \fI flags\fR -.fi -.in -2 - -.sp -.LP -Block I/O strategy event. This event marks a call to the \fBstrategy\fR(9E) -function of a block device driver. -.sp -.ne 2 -.na -\fB\fIdevice\fR\fR -.ad -.RS 10n -Contains the major and minor numbers of the device. -.RE - -.sp -.ne 2 -.na -\fB\fIblock\fR\fR -.ad -.RS 10n -The logical block number to be accessed on the device. -.RE - -.sp -.ne 2 -.na -\fB\fIsize\fR\fR -.ad -.RS 10n -The size of the I/O request. -.RE - -.sp -.ne 2 -.na -\fB\fIbuf\fR\fR -.ad -.RS 10n -The kernel address of the \fBbuf\fR(9S) structure associated with the transfer. -.RE - -.sp -.ne 2 -.na -\fB\fIflags\fR\fR -.ad -.RS 10n -The \fBbuf\fR(9S) flags associated with the transfer. -.RE - -.SS "\fBbiodone\fR" -.in +2 -.nf -\fBtnf_device\fR \fIdevice\fR -\fBtnf_diskaddr\fR \fIblock\fR -\fBtnf_opaque\fR \fIbuf\fR -.fi -.in -2 - -.sp -.LP -Buffered I/O completion event. This event marks calls to the \fBbiodone\fR(9F) -function. -.sp -.ne 2 -.na -\fB\fIdevice\fR\fR -.ad -.RS 10n -Contains the major and minor numbers of the device. -.RE - -.sp -.ne 2 -.na -\fB\fIblock\fR\fR -.ad -.RS 10n -The logical block number accessed on the device. -.RE - -.sp -.ne 2 -.na -\fB\fIbuf\fR\fR -.ad -.RS 10n -The kernel address of the \fBbuf\fR(9S) structure associated with the transfer. -.RE - -.SS "\fBphysio_start\fR" -.in +2 -.nf -\fBtnf_device\fR \fIdevice\fR -\fBtnf_offset\fR \fIoffset\fR -\fBtnf_size\fR \fIsize\fR -\fBtnf_bioflags\fR \fIrw\fR -.fi -.in -2 - -.sp -.LP -Raw I/O start event. This event marks entry into the \fBphysio\fR(9F) -function which performs unbuffered I/O. -.sp -.ne 2 -.na -\fB\fIdevice\fR\fR -.ad -.RS 10n -Contains the major and minor numbers of the device of the transfer. -.RE - -.sp -.ne 2 -.na -\fB\fIoffset\fR\fR -.ad -.RS 10n -The logical offset on the device for the transfer. -.RE - -.sp -.ne 2 -.na -\fB\fIsize\fR\fR -.ad -.RS 10n -The number of bytes to be transferred. -.RE - -.sp -.ne 2 -.na -\fB\fIrw\fR\fR -.ad -.RS 10n -The direction of the transfer: read or write (see \fBbuf\fR(9S)). -.RE - -.SS "\fBphysio_end\fR" -.in +2 -.nf -\fBtnf_device\fR \fIdevice\fR -.fi -.in -2 - -.sp -.LP -Raw I/O end event. This event marks exit from the \fBphysio\fR(9F) function. -.sp -.ne 2 -.na -\fB\fIdevice\fR\fR -.ad -.RS 10n -The major and minor numbers of the device of the transfer. -.RE - -.SH USAGE -Use the \fBprex\fR utility to control kernel probes. The standard \fBprex\fR -commands to list and manipulate probes are available to you, along with -commands to set up and manage kernel tracing. -.sp -.LP -Kernel probes write trace records into a kernel trace buffer. You must copy the -buffer into a TNF file for post-processing; use the \fBtnfxtract\fR utility for -this. -.sp -.LP -You use the \fBtnfdump\fR utility to examine a kernel trace file. This is -exactly the same as examining a user-level trace file. -.sp -.LP -The steps you typically follow to take a kernel trace are: -.RS +4 -.TP -1. -Become superuser (\fBsu\fR). -.RE -.RS +4 -.TP -2. -Allocate a kernel trace buffer of the desired size (\fBprex\fR). -.RE -.RS +4 -.TP -3. -Select the probes you want to trace and enable (\fBprex\fR). -.RE -.RS +4 -.TP -4. -Turn kernel tracing on (\fBprex\fR). -.RE -.RS +4 -.TP -5. -Run your application. -.RE -.RS +4 -.TP -6. -Turn kernel tracing off (\fBprex\fR). -.RE -.RS +4 -.TP -7. -Extract the kernel trace buffer (\fBtnfxtract\fR). -.RE -.RS +4 -.TP -8. -Disable all probes (\fBprex\fR). -.RE -.RS +4 -.TP -9. -Deallocate the kernel trace buffer (\fBprex\fR). -.RE -.RS +4 -.TP -10. -Examine the trace file (\fBtnfdump\fR). -.RE -.sp -.LP -A convenient way to follow these steps is to use two shell windows; run an -interactive \fBprex\fR session in one, and run your application and -\fBtnfxtract\fR in the other. -.SH SEE ALSO -.BR prex (1), -.BR tnfdump (1), -.BR tnfxtract (1), -.BR TNF_PROBE (3TNF), -.BR libtnfctl (3TNF), -.BR tracing (3TNF), -.BR strategy (9E), -.BR biodone (9F), -.BR physio (9F), -.BR buf (9S) |