xref: /openbsd-src/share/man/man9/ktrace.9 (revision a28daedfc357b214be5c701aa8ba8adb29a7f1c2)
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