1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)ktrace.2 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt KTRACE 2 10.Os BSD 4 11.Sh NAME 12.Nm ktrace 13.Nd process tracing 14.Sh SYNOPSIS 15.Fd #include <sys/types.h> 16.Fd #include <sys/ktrace.h> 17.Ft int 18.Fn ktrace "const char *tracefile" "int ops" "int trpoints" "int pid" 19.Sh DESCRIPTION 20The 21.Fn ktrace 22function enables or disables tracing of one or more processes. 23Users may only trace their own processes. 24Only the super-user can trace setuid or setgid programs. 25.Pp 26The 27.Ar tracefile 28gives the pathname of the file to be used for tracing. 29The file must exist and be writable by the calling process. 30All trace records are always appended to the file, 31so the file must be truncated to zero length to discard 32previous trace data. 33If tracing points are being disabled (see KTROP_CLEAR below), 34.Ar tracefile 35may be NULL. 36.Pp 37The 38.Nm ops 39parameter specifies the requested ktrace operation. 40The defined operations are: 41.Bl -column KTRFLAG_DESCENDXXX -offset indent 42.It KTROP_SET Enable trace points specified in Ar trpoints . 43.It KTROP_CLEAR Disable trace points specified in Ar trpoints . 44.It KTROP_CLEARFILE Stop all tracing. 45.It KTRFLAG_DESCEND The tracing change should apply to the 46specified process and all its current children. 47.El 48.Pp 49The 50.Nm trpoints 51parameter specifies the trace points of interest. 52The defined trace points are: 53.Bl -column KTRFAC_SYSCALLXXX -offset indent 54.It KTRFAC_SYSCALL Trace system calls. 55.It KTRFAC_SYSRET Trace return values from system calls. 56.It KTRFAC_NAMEI Trace name lookup operations. 57.It KTRFAC_GENIO Trace all I/O (note that this option can 58generate much output). 59.It KTRFAC_PSIG Trace posted signals. 60.It KTRFAC_CSW Trace context switch points. 61.It KTRFAC_INHERIT Inherit tracing to future children. 62.El 63.Pp 64Each tracing event outputs a record composed of a generic header 65followed by a trace point specific structure. 66The generic header is: 67.Bd -literal 68struct ktr_header { 69 int ktr_len; /* length of buf */ 70 short ktr_type; /* trace record type */ 71 pid_t ktr_pid; /* process id */ 72 char ktr_comm[MAXCOMLEN+1]; /* command name */ 73 struct timeval ktr_time; /* timestamp */ 74 caddr_t ktr_buf; 75}; 76.Ed 77.Pp 78The 79.Nm ktr_len 80field specifies the length of the 81.Nm ktr_type 82data that follows this header. 83The 84.Nm ktr_pid 85and 86.Nm ktr_comm 87fields specify the process and command generating the record. 88The 89.Nm ktr_time 90field gives the time (with microsecond resolution) 91that the record was generated. 92The 93.Nm ktr_buf 94is an internal kernel pointer and is not useful. 95.Pp 96The generic header is followed by 97.Nm ktr_len 98bytes of a 99.Nm ktr_type 100record. 101The type specific records are defined in the 102.Pa <sys/ktrace.h> 103include file. 104.Sh RETURN VALUES 105On successful completion a value of 0 is returned. 106Otherwise, a value of -1 is returned and 107.Va errno 108is set to show the error. 109.Sh ERRORS 110.Fn Ktrace 111will fail if: 112.Bl -tag -width ENAMETOOLONGAA 113.It Bq Er ENOTDIR 114A component of the path prefix is not a directory. 115.It Bq Er EINVAL 116The pathname contains a character with the high-order bit set. 117.It Bq Er ENAMETOOLONG 118A component of a pathname exceeded 255 characters, 119or an entire path name exceeded 1023 characters. 120.It Bq Er ENOENT 121The named tracefile does not exist. 122.It Bq Er EACCES 123Search permission is denied for a component of the path prefix. 124.It Bq Er ELOOP 125Too many symbolic links were encountered in translating the pathname. 126.It Bq Er EIO 127An I/O error occurred while reading from or writing to the file system. 128.El 129.Sh SEE ALSO 130.Xr ktrace 1 , 131.Xr kdump 1 132.Sh HISTORY 133A 134.Nm ktrace 135function call first appeared in 136.Bx 4.4 . 137