1.\" $OpenBSD: ktrace.9,v 1.2 2003/07/24 22:08:56 jmc Exp $ 2.\" 3.\" Copyright (c) 2003 Michael Shalayeff 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF MIND, USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 21, 2003 27.Dt KTRACE 9 28.Os 29.Sh NAME 30.Nm ktrcsw , 31.Nm ktremul , 32.Nm ktrgenio , 33.Nm ktrnamei , 34.Nm ktrpsig , 35.Nm ktrsyscall , 36.Nm ktrsysret , 37.Nm KTRPOINT 38.Nd "process tracing kernel interface" 39.Sh SYNOPSIS 40.In sys/ktrace.h 41.Fn KTRPOINT "struct proc *p" "int type" 42.Ft void 43.Fn ktrcsw "struct proc *p" "int out" "int user" 44.Ft void 45.Fn ktremul "struct proc *p" "char *emul" 46.Ft void 47.Fn ktrgenio "struct proc *p" "int fd" "enum uio_rw rw" "struct iovec *iov" "int len" "int error" 48.Ft void 49.Fn ktrnamei "struct proc *p" "char *path" 50.Ft void 51.Fn ktrpsig "struct proc *p" "int sig" "sig_t action" "int mask" "int code" "siginfo_t *si" 52.Ft void 53.Fn ktrsyscall "struct proc *p" "register_t code" "size_t argsize" "register_t args[]" 54.Ft void 55.Fn ktrsysret "struct proc *p" "register_t code" "int error" "register_t retval" 56.Sh DESCRIPTION 57This interface is meant for kernel subsystems and machine dependent code 58to inform the user about the events occuring to the process should 59tracing of such be enabled using the 60.Xr ktrace 2 61system call. 62Each of the functions (except for 63.Nm KTRPOINT ) 64is meant for a particular type of event and is described below. 65.Pp 66The 67.Fn KTRPOINT 68macro should be used before calling any of the other tracing functions 69to verify that tracing for that particular type of events has been enabled. 70Possible values for the 71.Fa type 72argument are a mask of the KTRFAC_ values described in 73.Xr ktrace 2 . 74.Pp 75.Fn ktrcsw 76is called during the context switching. 77The 78.Fa user 79argument is a boolean value specifying whether the process has 80been put into a waiting state (true) or placed onto a running queue (false). 81Furthemore the 82.Fa user 83argument indicates whether a voluntary (false) or an involuntary (true) 84switching has happened. 85.Pp 86.Fn ktremul 87should be called every time emulation for the execution environment 88is changed and thus the name of which is given in the 89.Fa name 90argument. 91.Pp 92.Fn ktrgenio 93should be called for each generic input/output transaction that is 94described by the 95.Fa fd 96file descriptor, 97.Fa rw 98transaction type (consult 99.Pa sys/sys/uio.h 100for the 101.Nm enum uio_rw 102definition), 103.Fa iov 104input/output data vector, 105.Fa len 106size of the 107.Fa iov 108vector, 109and, lastly, 110.Fa error 111status of the transaction. 112.Pp 113.Fn ktrnamei 114should be called every time a 115.Xr namei 9 116operation is performed over the 117.Fa path 118name. 119.Pp 120.Fn ktrpsig 121should be called for each signal 122.Fa sig 123posted for the traced process. 124The 125.Fa action 126taken is one of 127.Nm SIG_DFL , 128.Nm SIG_IGN , 129or 130.Nm SIG_ERR 131as described in the 132.Xr sigaction 2 133document. 134.Fa mask 135is the current traced process' signal mask. 136Signal-specific code and 137.Em siginfo_t 138structure as described in 139.Aq Pa sys/siginfo.h 140are given in the 141.Fa code 142and 143.Fa si 144arguments respectively. 145.Pp 146.Fn ktrsyscall 147should be called for each system call number 148.Fa code 149executed with arguments in 150.Fa args 151of total count of 152.Fa argsize . 153.Pp 154.Fn ktrsysret 155should be called for a return from each system call number 156.Fa code 157and error number of 158.Fa error 159as described in 160.Xr errno 2 161and a return value in 162.Fa retval 163that is syscall dependent. 164.Sh CODE REFERENCES 165The process tracing facility is implemented in 166.Pa sys/kern/kern_ktrace.c . 167.Sh SEE ALSO 168.Xr errno 2 , 169.Xr ktrace 2 , 170.Xr syscall 2 , 171.Xr namei 9 , 172.Xr syscall 9 173.Sh HISTORY 174The process tracing facility first appeared in 175.Bx 4.4 . 176.Pp 177The 178.Nm ktrace 179section manual page appeared in 180.Ox 3.4 . 181