1.\" $OpenBSD: ktrace.9,v 1.12 2016/06/19 21:41:51 guenther 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: June 19 2016 $ 27.Dt KTRACE 9 28.Os 29.Sh NAME 30.Nm ktrgenio , 31.Nm ktrnamei , 32.Nm ktrpsig , 33.Nm ktrsyscall , 34.Nm ktrsysret , 35.Nm KTRPOINT 36.Nd process tracing kernel interface 37.Sh SYNOPSIS 38.In sys/param.h 39.In sys/proc.h 40.In sys/ktrace.h 41.Fn KTRPOINT "struct proc *p" "int type" 42.Ft void 43.Fn ktrgenio "struct proc *p" "int fd" "enum uio_rw rw" "struct iovec *iov" "int len" "int error" 44.Ft void 45.Fn ktrnamei "struct proc *p" "char *path" 46.Ft void 47.Fn ktrpsig "struct proc *p" "int sig" "sig_t action" "int mask" "int code" "siginfo_t *si" 48.Ft void 49.Fn ktrsyscall "struct proc *p" "register_t code" "size_t argsize" "register_t args[]" 50.Ft void 51.Fn ktrsysret "struct proc *p" "register_t code" "int error" "register_t retval" 52.Sh DESCRIPTION 53This interface is meant for kernel subsystems and machine dependent code 54to inform the user about the events occurring to the process should 55tracing of such be enabled using the 56.Xr ktrace 2 57system call. 58Each of the functions (except for 59.Nm KTRPOINT ) 60is meant for a particular type of event and is described below. 61.Pp 62The 63.Fn KTRPOINT 64macro should be used before calling any of the other tracing functions 65to verify that tracing for that particular type of events has been enabled. 66.Fa type 67must be a KTR_ value corresponding to a KTRFAC_ value described in 68.Xr ktrace 2 . 69.Pp 70.Fn ktrgenio 71should be called for each generic input/output transaction that is 72described by the 73.Fa fd 74file descriptor, 75.Fa rw 76transaction type (consult 77.Pa sys/sys/uio.h 78for the 79.Nm enum uio_rw 80definition), 81.Fa iov 82input/output data vector, 83.Fa len 84size of the 85.Fa iov 86vector, 87and, lastly, 88.Fa error 89status of the transaction. 90.Pp 91.Fn ktrnamei 92should be called every time a 93.Xr namei 9 94operation is performed over the 95.Fa path 96name. 97.Pp 98.Fn ktrpsig 99should be called for each signal 100.Fa sig 101posted for the traced process. 102The 103.Fa action 104taken is one of 105.Nm SIG_DFL , 106.Nm SIG_IGN , 107or 108.Nm SIG_ERR 109as described in the 110.Xr sigaction 2 111document. 112.Fa mask 113is the current traced process' signal mask. 114Signal-specific code and 115.Em siginfo_t 116structure as described in 117.In sys/siginfo.h 118are given in the 119.Fa code 120and 121.Fa si 122arguments respectively. 123.Pp 124.Fn ktrsyscall 125should be called for each system call number 126.Fa code 127executed with arguments in 128.Fa args 129of total count of 130.Fa argsize . 131.Pp 132.Fn ktrsysret 133should be called for a return from each system call number 134.Fa code 135and error number of 136.Fa error 137as described in 138.Xr errno 2 139and a return value in 140.Fa retval 141that is syscall dependent. 142.Sh CODE REFERENCES 143The process tracing facility is implemented in 144.Pa sys/kern/kern_ktrace.c . 145.Sh SEE ALSO 146.Xr errno 2 , 147.Xr ktrace 2 , 148.Xr syscall 2 , 149.Xr namei 9 , 150.Xr syscall 9 151.Sh HISTORY 152The process tracing facility first appeared in 153.Bx 4.4 . 154.Pp 155The 156.Nm ktrace 157section manual page appeared in 158.Ox 3.4 . 159