xref: /openbsd/lib/libc/sys/ktrace.2 (revision cecf84d4) 
1.\"	$OpenBSD: ktrace.2,v 1.27 2015/01/19 15:54:11 millert Exp $
2.\"	$NetBSD: ktrace.2,v 1.2 1995/02/27 12:33:58 cgd Exp $
3.\"
4.\" Copyright (c) 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.\" 3. 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.2	8.1 (Berkeley) 6/4/93
32.\"
33.Dd $Mdocdate: January 19 2015 $
34.Dt KTRACE 2
35.Os
36.Sh NAME
37.Nm ktrace
38.Nd process tracing
39.Sh SYNOPSIS
40.In sys/types.h
41.In sys/param.h
42.In sys/uio.h
43.In sys/ktrace.h
44.Ft int
45.Fn ktrace "const char *tracefile" "int ops" "int trpoints" "pid_t pid"
46.Sh DESCRIPTION
47The
48.Fn ktrace
49function enables or disables tracing of one or more processes.
50Users may only trace their own processes.
51Only the superuser can trace setuid or setgid programs.
52.Fn ktrace
53is only available on kernels compiled with the
54.Cm KTRACE
55option.
56.Pp
57.Fa tracefile
58gives the pathname of the file to be used for tracing.
59The file must exist, be writable by the calling process, and
60not be a symbolic link.
61All trace records are always appended to the file,
62so the file must be truncated to zero length to discard
63previous trace data.
64If tracing points are being disabled (see
65.Dv KTROP_CLEAR
66below),
67.Fa tracefile
68may be
69.Dv NULL .
70.Pp
71The
72.Fa ops
73parameter specifies the requested ktrace operation.
74The defined operations are:
75.Pp
76.Bl -tag -width KTRFLAG_DESCEND -offset indent -compact
77.It Dv KTROP_SET
78Enable trace points specified in
79.Fa trpoints .
80.It Dv KTROP_CLEAR
81Disable trace points specified in
82.Fa trpoints .
83.It Dv KTROP_CLEARFILE
84Stop all tracing.
85.It Dv KTRFLAG_DESCEND
86The tracing change should apply to the
87specified process and all its current children.
88.El
89.Pp
90The
91.Fa trpoints
92parameter specifies the trace points of interest.
93The defined trace points are:
94.Pp
95.Bl -tag -width KTRFAC_INHERIT -offset indent -compact
96.It Dv KTRFAC_SYSCALL
97Trace system calls.
98.It Dv KTRFAC_SYSRET
99Trace return values from system calls.
100.It Dv KTRFAC_NAMEI
101Trace name lookup operations.
102.It Dv KTRFAC_GENIO
103Trace all I/O
104(note that this option can generate much output).
105.It Dv KTRFAC_PSIG
106Trace posted signals.
107.It Dv KTRFAC_EMUL
108Trace emulation changes.
109.It Dv KTRFAC_CSW
110Trace context switch points.
111.It Dv KTRFAC_STRUCT
112Trace various structs
113.It Dv KTRFAC_USER
114Trace user data coming from
115.Xr utrace 2
116calls.
117.It Dv KTRFAC_INHERIT
118Inherit tracing to future children.
119.El
120.Pp
121The
122.Fa pid
123parameter refers to a process ID.
124If it is negative,
125it refers to a process group ID.
126.Pp
127Each tracing event outputs a record composed of a generic header
128followed by a trace point specific structure.
129The generic header is:
130.Bd -literal
131struct ktr_header {
132	uint	ktr_type;		/* trace record type */
133	pid_t	ktr_pid;		/* process id */
134	pid_t	ktr_tid;		/* thread id */
135	struct	timespec ktr_time;	/* timestamp */
136	char	ktr_comm[MAXCOMLEN+1];	/* command name */
137	size_t	ktr_len;		/* length of buf */
138};
139.Ed
140.Pp
141The
142.Fa ktr_len
143field specifies the length of the
144.Fa ktr_type
145data that follows this header.
146The
147.Fa ktr_pid , ktr_tid ,
148and
149.Fa ktr_comm
150fields specify the process, thread, and command generating the record.
151The
152.Fa ktr_time
153field gives the time (with nanosecond resolution)
154that the record was generated.
155.Pp
156The generic header is followed by
157.Fa ktr_len
158bytes of a
159.Fa ktr_type
160record.
161The type specific records are defined in the
162.In sys/ktrace.h
163include file.
164.Sh RETURN VALUES
165.Rv -std
166.Sh ERRORS
167.Fn ktrace
168will fail if:
169.Bl -tag -width ENAMETOOLONGAA
170.It Bq Er ENOTDIR
171A component of the path prefix is not a directory.
172.It Bq Er EINVAL
173No trace points were selected.
174.It Bq Er ENAMETOOLONG
175A component of a pathname exceeded
176.Dv NAME_MAX
177characters, or an entire pathname (including the terminating NUL)
178exceeded
179.Dv PATH_MAX
180bytes.
181.It Bq Er ENOENT
182The named tracefile does not exist.
183.It Bq Er EACCES
184Search permission is denied for a component of the path prefix or the
185path refers to a symbolic link.
186.It Bq Er ELOOP
187Too many symbolic links were encountered in translating the pathname.
188.It Bq Er EIO
189An I/O error occurred while reading from or writing to the file system.
190.It Bq Er ESRCH
191No process can be found corresponding to that specified by
192.Fa pid .
193.El
194.Sh SEE ALSO
195.Xr kdump 1 ,
196.Xr ktrace 1 ,
197.Xr utrace 2
198.Sh HISTORY
199A
200.Fn ktrace
201function call first appeared in
202.Bx 4.4 .
203