1.\" $OpenBSD: ktrace.9,v 1.6 2007/05/31 19:20:00 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 $Mdocdate: May 31 2007 $ 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.Fd #include <sys/param.h> 41.Fd #include <sys/proc.h> 42.Fd #include <sys/ktrace.h> 43.Fn KTRPOINT "struct proc *p" "int type" 44.Ft void 45.Fn ktrcsw "struct proc *p" "int out" "int user" 46.Ft void 47.Fn ktremul "struct proc *p" "char *emul" 48.Ft void 49.Fn ktrgenio "struct proc *p" "int fd" "enum uio_rw rw" "struct iovec *iov" "int len" "int error" 50.Ft void 51.Fn ktrnamei "struct proc *p" "char *path" 52.Ft void 53.Fn ktrpsig "struct proc *p" "int sig" "sig_t action" "int mask" "int code" "siginfo_t *si" 54.Ft void 55.Fn ktrsyscall "struct proc *p" "register_t code" "size_t argsize" "register_t args[]" 56.Ft void 57.Fn ktrsysret "struct proc *p" "register_t code" "int error" "register_t retval" 58.Sh DESCRIPTION 59This interface is meant for kernel subsystems and machine dependent code 60to inform the user about the events occurring to the process should 61tracing of such be enabled using the 62.Xr ktrace 2 63system call. 64Each of the functions (except for 65.Nm KTRPOINT ) 66is meant for a particular type of event and is described below. 67.Pp 68The 69.Fn KTRPOINT 70macro should be used before calling any of the other tracing functions 71to verify that tracing for that particular type of events has been enabled. 72Possible values for the 73.Fa type 74argument are a mask of the KTRFAC_ values described in 75.Xr ktrace 2 . 76.Pp 77.Fn ktrcsw 78is called during the context switching. 79The 80.Fa user 81argument is a boolean value specifying whether the process has 82been put into a waiting state (true) or placed onto a running queue (false). 83Furthermore the 84.Fa user 85argument indicates whether a voluntary (false) or an involuntary (true) 86switching has happened. 87.Pp 88.Fn ktremul 89should be called every time emulation for the execution environment 90is changed and thus the name of which is given in the 91.Fa name 92argument. 93.Pp 94.Fn ktrgenio 95should be called for each generic input/output transaction that is 96described by the 97.Fa fd 98file descriptor, 99.Fa rw 100transaction type (consult 101.Pa sys/sys/uio.h 102for the 103.Nm enum uio_rw 104definition), 105.Fa iov 106input/output data vector, 107.Fa len 108size of the 109.Fa iov 110vector, 111and, lastly, 112.Fa error 113status of the transaction. 114.Pp 115.Fn ktrnamei 116should be called every time a 117.Xr namei 9 118operation is performed over the 119.Fa path 120name. 121.Pp 122.Fn ktrpsig 123should be called for each signal 124.Fa sig 125posted for the traced process. 126The 127.Fa action 128taken is one of 129.Nm SIG_DFL , 130.Nm SIG_IGN , 131or 132.Nm SIG_ERR 133as described in the 134.Xr sigaction 2 135document. 136.Fa mask 137is the current traced process' signal mask. 138Signal-specific code and 139.Em siginfo_t 140structure as described in 141.Aq Pa sys/siginfo.h 142are given in the 143.Fa code 144and 145.Fa si 146arguments respectively. 147.Pp 148.Fn ktrsyscall 149should be called for each system call number 150.Fa code 151executed with arguments in 152.Fa args 153of total count of 154.Fa argsize . 155.Pp 156.Fn ktrsysret 157should be called for a return from each system call number 158.Fa code 159and error number of 160.Fa error 161as described in 162.Xr errno 2 163and a return value in 164.Fa retval 165that is syscall dependent. 166.Sh CODE REFERENCES 167The process tracing facility is implemented in 168.Pa sys/kern/kern_ktrace.c . 169.Sh SEE ALSO 170.Xr errno 2 , 171.Xr ktrace 2 , 172.Xr syscall 2 , 173.Xr namei 9 , 174.Xr syscall 9 175.Sh HISTORY 176The process tracing facility first appeared in 177.Bx 4.4 . 178.Pp 179The 180.Nm ktrace 181section manual page appeared in 182.Ox 3.4 . 183