Sat Mar 19 17:15:13 2016 UTC ()
Sync documentation of struct ktr_header with reality:
   - there is a ktr_version field
   - the ordering of ktr_type and ktr_version is byte-order dependent
   - ktr_time is now a timespec, not a timeval
   - there's now a ktr_lid field
   - there is no such thing as a ktr_buf field and it's certainly not
     a caddr_t.

XXX: I would appreciate it if someone who knows how this stuff works
XXX: could review this file in case it's still lying in some more
XXX: subtle way.


(dholland)
diff -r1.19 -r1.20 src/lib/libc/sys/ktrace.2
cvs diff -r1.19 -r1.20 src/lib/libc/sys/ktrace.2 (expand / switch to unified diff)

--- src/lib/libc/sys/ktrace.2 2016/03/19 17:05:36 1.19
+++ src/lib/libc/sys/ktrace.2 2016/03/19 17:15:13 1.20
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: ktrace.2,v 1.19 2016/03/19 17:05:36 dholland Exp $ 1.\" $NetBSD: ktrace.2,v 1.20 2016/03/19 17:15:13 dholland Exp $
2.\" 2.\"
3.\" Copyright (c) 1993 3.\" Copyright (c) 1993
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" Redistribution and use in source and binary forms, with or without 6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions 7.\" modification, are permitted provided that the following conditions
8.\" are met: 8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright 9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer. 10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the 12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution. 13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors 14.\" 3. Neither the name of the University nor the names of its contributors
@@ -94,56 +94,60 @@ generate much output). @@ -94,56 +94,60 @@ generate much output).
94.It KTRFAC_PSIG Trace posted signals. 94.It KTRFAC_PSIG Trace posted signals.
95.It KTRFAC_CSW Trace context switch points. 95.It KTRFAC_CSW Trace context switch points.
96.It KTRFAC_EMUL Trace emulation changes. 96.It KTRFAC_EMUL Trace emulation changes.
97.It KTRFAC_INHERIT Inherit tracing to future children. 97.It KTRFAC_INHERIT Inherit tracing to future children.
98.El 98.El
99.Pp 99.Pp
100Each tracing event outputs a record composed of a generic header 100Each tracing event outputs a record composed of a generic header
101followed by a trace point specific structure. 101followed by a trace point specific structure.
102The generic header is: 102The generic header is:
103.Bd -literal 103.Bd -literal
104struct ktr_header { 104struct ktr_header {
105 int ktr_len; /* length of buf */ 105 int ktr_len; /* length of buf */
106 short ktr_type; /* trace record type */ 106 short ktr_type; /* trace record type */
 107 short ktr_version; /* trace record version */
107 pid_t ktr_pid; /* process id */ 108 pid_t ktr_pid; /* process id */
108 char ktr_comm[MAXCOMLEN+1]; /* command name */ 109 char ktr_comm[MAXCOMLEN+1]; /* command name */
109 struct timeval ktr_time; /* timestamp */ 110 struct timespec ktr_time; /* timestamp */
110 caddr_t ktr_buf; 111 lwpid_t ktr_lid;
111}; 112};
112.Ed 113.Ed
113.Pp 114.Pp
114The 115The
115.Nm ktr_len 116.Nm ktr_len
116field specifies the length of the 117field specifies the length of the data that follows this header.
 118The
117.Nm ktr_type 119.Nm ktr_type
118data that follows this header. 120and
 121.Nm ktr_version
 122fields (whose ordering in the structure depends on byte order)
 123specify the format of this data.
119The 124The
120.Nm ktr_pid 125.Nm ktr_pid ,
 126.Nm ktr_lid ,
121and 127and
122.Nm ktr_comm 128.Nm ktr_comm
123fields specify the process and command generating the record. 129fields specify the process and command generating the record.
124The 130The
125.Nm ktr_time 131.Nm ktr_time
126field gives the time (with microsecond resolution) 132field gives the time (with nanosecond resolution)
127that the record was generated. 133that the record was generated.
128The 
129.Nm ktr_buf 
130is an internal kernel pointer and is not useful. 
131.Pp 134.Pp
132The generic header is followed by 135The generic header is followed by
133.Nm ktr_len 136.Nm ktr_len
134bytes of a 137bytes of a
135.Nm ktr_type 138.Nm ktr_type
136record. 139record of version
 140.Nm ktr_version .
137The type specific records are defined in the 141The type specific records are defined in the
138.Pa \*[Lt]sys/ktrace.h\*[Gt] 142.Pa \*[Lt]sys/ktrace.h\*[Gt]
139include file. 143include file.
140.Sh RETURN VALUES 144.Sh RETURN VALUES
141On successful completion a value of 0 is returned. 145On successful completion a value of 0 is returned.
142Otherwise, a value of \-1 is returned and 146Otherwise, a value of \-1 is returned and
143.Va errno 147.Va errno
144is set to show the error. 148is set to show the error.
145.Sh ERRORS 149.Sh ERRORS
146.Fn ktrace 150.Fn ktrace
147will fail if: 151will fail if:
148.Bl -tag -width ENAMETOOLONGAA 152.Bl -tag -width ENAMETOOLONGAA
149.It Bq Er ENOTDIR 153.It Bq Er ENOTDIR