ktrace.h revision 330897 
1/*-
2 * SPDX-License-Identifier: BSD-3-Clause
3 *
4 * Copyright (c) 1988, 1993
5 *	The Regents of the University of California.  All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 *    notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 *    notice, this list of conditions and the following disclaimer in the
14 *    documentation and/or other materials provided with the distribution.
15 * 4. Neither the name of the University nor the names of its contributors
16 *    may be used to endorse or promote products derived from this software
17 *    without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 * SUCH DAMAGE.
30 *
31 *	@(#)ktrace.h	8.1 (Berkeley) 6/2/93
32 * $FreeBSD: stable/11/sys/sys/ktrace.h 330897 2018-03-14 03:19:51Z eadler $
33 */
34
35#ifndef _SYS_KTRACE_H_
36#define _SYS_KTRACE_H_
37
38#include <sys/caprights.h>
39
40/*
41 * operations to ktrace system call  (KTROP(op))
42 */
43#define KTROP_SET		0	/* set trace points */
44#define KTROP_CLEAR		1	/* clear trace points */
45#define KTROP_CLEARFILE		2	/* stop all tracing to file */
46#define	KTROP(o)		((o)&3)	/* macro to extract operation */
47/*
48 * flags (ORed in with operation)
49 */
50#define KTRFLAG_DESCEND		4	/* perform op on all children too */
51
52/*
53 * ktrace record header
54 */
55struct ktr_header {
56	int	ktr_len;		/* length of buf */
57	short	ktr_type;		/* trace record type */
58	pid_t	ktr_pid;		/* process id */
59	char	ktr_comm[MAXCOMLEN + 1];/* command name */
60	struct	timeval ktr_time;	/* timestamp */
61	intptr_t	ktr_tid;	/* was ktr_buffer */
62};
63
64/*
65 * Test for kernel trace point (MP SAFE).
66 *
67 * KTRCHECK() just checks that the type is enabled and is only for
68 * internal use in the ktrace subsystem.  KTRPOINT() checks against
69 * ktrace recursion as well as checking that the type is enabled and
70 * is the public interface.
71 */
72#define	KTRCHECK(td, type)	((td)->td_proc->p_traceflag & (1 << type))
73#define KTRPOINT(td, type)						\
74	(KTRCHECK((td), (type)) && !((td)->td_pflags & TDP_INKTRACE))
75#define	KTRCHECKDRAIN(td)	(!(STAILQ_EMPTY(&(td)->td_proc->p_ktr)))
76#define	KTRUSERRET(td) do {						\
77	if (KTRCHECKDRAIN(td))						\
78		ktruserret(td);						\
79} while (0)
80
81/*
82 * ktrace record types
83 */
84
85/*
86 * KTR_SYSCALL - system call record
87 */
88#define KTR_SYSCALL	1
89struct ktr_syscall {
90	short	ktr_code;		/* syscall number */
91	short	ktr_narg;		/* number of arguments */
92	/*
93	 * followed by ktr_narg register_t
94	 */
95	register_t	ktr_args[1];
96};
97
98/*
99 * KTR_SYSRET - return from system call record
100 */
101#define KTR_SYSRET	2
102struct ktr_sysret {
103	short	ktr_code;
104	short	ktr_eosys;
105	int	ktr_error;
106	register_t	ktr_retval;
107};
108
109/*
110 * KTR_NAMEI - namei record
111 */
112#define KTR_NAMEI	3
113	/* record contains pathname */
114
115/*
116 * KTR_GENIO - trace generic process i/o
117 */
118#define KTR_GENIO	4
119struct ktr_genio {
120	int	ktr_fd;
121	enum	uio_rw ktr_rw;
122	/*
123	 * followed by data successfully read/written
124	 */
125};
126
127/*
128 * KTR_PSIG - trace processed signal
129 */
130#define	KTR_PSIG	5
131struct ktr_psig {
132	int	signo;
133	sig_t	action;
134	int	code;
135	sigset_t mask;
136};
137
138/*
139 * KTR_CSW - trace context switches
140 */
141#define KTR_CSW		6
142struct ktr_csw_old {
143	int	out;	/* 1 if switch out, 0 if switch in */
144	int	user;	/* 1 if usermode (ivcsw), 0 if kernel (vcsw) */
145};
146
147struct ktr_csw {
148	int	out;	/* 1 if switch out, 0 if switch in */
149	int	user;	/* 1 if usermode (ivcsw), 0 if kernel (vcsw) */
150	char	wmesg[8];
151};
152
153/*
154 * KTR_USER - data coming from userland
155 */
156#define KTR_USER_MAXLEN	2048	/* maximum length of passed data */
157#define KTR_USER	7
158
159/*
160 * KTR_STRUCT - misc. structs
161 */
162#define KTR_STRUCT	8
163	/*
164	 * record contains null-terminated struct name followed by
165	 * struct contents
166	 */
167struct sockaddr;
168struct stat;
169struct sysentvec;
170
171/*
172 * KTR_SYSCTL - name of a sysctl MIB
173 */
174#define	KTR_SYSCTL	9
175	/* record contains null-terminated MIB name */
176
177/*
178 * KTR_PROCCTOR - trace process creation (multiple ABI support)
179 */
180#define KTR_PROCCTOR	10
181struct ktr_proc_ctor {
182	u_int	sv_flags;	/* struct sysentvec sv_flags copy */
183};
184
185/*
186 * KTR_PROCDTOR - trace process destruction (multiple ABI support)
187 */
188#define KTR_PROCDTOR	11
189
190/*
191 * KTR_CAPFAIL - trace capability check failures
192 */
193#define KTR_CAPFAIL	12
194enum ktr_cap_fail_type {
195	CAPFAIL_NOTCAPABLE,	/* insufficient capabilities in cap_check() */
196	CAPFAIL_INCREASE,	/* attempt to increase capabilities */
197	CAPFAIL_SYSCALL,	/* disallowed system call */
198	CAPFAIL_LOOKUP,		/* disallowed VFS lookup */
199};
200struct ktr_cap_fail {
201	enum ktr_cap_fail_type cap_type;
202	cap_rights_t	cap_needed;
203	cap_rights_t	cap_held;
204};
205
206/*
207 * KTR_FAULT - page fault record
208 */
209#define KTR_FAULT	13
210struct ktr_fault {
211	vm_offset_t vaddr;
212	int type;
213};
214
215/*
216 * KTR_FAULTEND - end of page fault record
217 */
218#define KTR_FAULTEND	14
219struct ktr_faultend {
220	int result;
221};
222
223/*
224 * KTR_STRUCT_ARRAY - array of misc. structs
225 */
226#define	KTR_STRUCT_ARRAY 15
227struct ktr_struct_array {
228	size_t struct_size;
229	/*
230	 * Followed by null-terminated structure name and then payload
231	 * contents.
232	 */
233};
234
235/*
236 * KTR_DROP - If this bit is set in ktr_type, then at least one event
237 * between the previous record and this record was dropped.
238 */
239#define	KTR_DROP	0x8000
240
241/*
242 * kernel trace points (in p_traceflag)
243 */
244#define KTRFAC_MASK	0x00ffffff
245#define KTRFAC_SYSCALL	(1<<KTR_SYSCALL)
246#define KTRFAC_SYSRET	(1<<KTR_SYSRET)
247#define KTRFAC_NAMEI	(1<<KTR_NAMEI)
248#define KTRFAC_GENIO	(1<<KTR_GENIO)
249#define	KTRFAC_PSIG	(1<<KTR_PSIG)
250#define KTRFAC_CSW	(1<<KTR_CSW)
251#define KTRFAC_USER	(1<<KTR_USER)
252#define KTRFAC_STRUCT	(1<<KTR_STRUCT)
253#define KTRFAC_SYSCTL	(1<<KTR_SYSCTL)
254#define KTRFAC_PROCCTOR	(1<<KTR_PROCCTOR)
255#define KTRFAC_PROCDTOR	(1<<KTR_PROCDTOR)
256#define KTRFAC_CAPFAIL	(1<<KTR_CAPFAIL)
257#define KTRFAC_FAULT	(1<<KTR_FAULT)
258#define KTRFAC_FAULTEND	(1<<KTR_FAULTEND)
259#define	KTRFAC_STRUCT_ARRAY (1<<KTR_STRUCT_ARRAY)
260
261/*
262 * trace flags (also in p_traceflags)
263 */
264#define KTRFAC_ROOT	0x80000000	/* root set this trace */
265#define KTRFAC_INHERIT	0x40000000	/* pass trace flags to children */
266#define	KTRFAC_DROP	0x20000000	/* last event was dropped */
267
268#ifdef	_KERNEL
269void	ktrnamei(char *);
270void	ktrcsw(int, int, const char *);
271void	ktrpsig(int, sig_t, sigset_t *, int);
272void	ktrfault(vm_offset_t, int);
273void	ktrfaultend(int);
274void	ktrgenio(int, enum uio_rw, struct uio *, int);
275void	ktrsyscall(int, int narg, register_t args[]);
276void	ktrsysctl(int *name, u_int namelen);
277void	ktrsysret(int, int, register_t);
278void	ktrprocctor(struct proc *);
279void	ktrprocexec(struct proc *, struct ucred **, struct vnode **);
280void	ktrprocexit(struct thread *);
281void	ktrprocfork(struct proc *, struct proc *);
282void	ktruserret(struct thread *);
283void	ktrstruct(const char *, const void *, size_t);
284void	ktrstructarray(const char *, enum uio_seg, const void *, int, size_t);
285void	ktrcapfail(enum ktr_cap_fail_type, const cap_rights_t *,
286	    const cap_rights_t *);
287#define ktrcaprights(s) \
288	ktrstruct("caprights", (s), sizeof(cap_rights_t))
289#define	ktritimerval(s) \
290	ktrstruct("itimerval", (s), sizeof(struct itimerval))
291#define ktrsockaddr(s) \
292	ktrstruct("sockaddr", (s), ((struct sockaddr *)(s))->sa_len)
293#define ktrstat(s) \
294	ktrstruct("stat", (s), sizeof(struct stat))
295extern u_int ktr_geniosize;
296#else
297
298#include <sys/cdefs.h>
299
300__BEGIN_DECLS
301int	ktrace(const char *, int, int, pid_t);
302int	utrace(const void *, size_t);
303__END_DECLS
304
305#endif
306
307#endif
308