KTRACE(2) | System Calls Manual | KTRACE(2) |
ktrace
, fktrace
—
#include <sys/param.h>
#include <sys/ktrace.h>
int
ktrace
(const
char *tracefile, int
ops, int trpoints,
pid_t pid);
int
fktrace
(int
fd, int ops,
int trpoints,
pid_t pid);
ktrace
() function enables or disables tracing of one
or more processes. Users may only trace their own processes. Only the
super-user can trace setuid or setgid programs.
The tracefile gives the pathname of the file
to be used for tracing. The file must exist and be writable by the calling
process. All trace records are always appended to the file, so the file must
be truncated to zero length to discard previous trace data. If tracing
points are being disabled (see KTROP_CLEAR below),
tracefile may be NULL. If using
fktrace
() then instead of passing a filename as
tracefile, a file descriptor is passed as
fd and behaviour is otherwise the same.
The ops
parameter specifies the requested
ktrace operation. The defined operations are:
KTROP_SET | Enable trace points specified in trpoints. |
KTROP_CLEAR | Disable trace points specified in trpoints. |
KTROP_CLEARFILE | Stop all tracing. |
KTRFLAG_DESCEND | The tracing change should apply to the specified process and all its current children. |
The trpoints
parameter specifies the trace
points of interest. The defined trace points are:
KTRFAC_SYSCALL | Trace system calls. |
KTRFAC_SYSRET | Trace return values from system calls. |
KTRFAC_NAMEI | Trace name lookup operations. |
KTRFAC_GENIO | Trace all I/O (note that this option can generate much output). |
KTRFAC_PSIG | Trace posted signals. |
KTRFAC_CSW | Trace context switch points. |
KTRFAC_EMUL | Trace emulation changes. |
KTRFAC_INHERIT | Inherit tracing to future children. |
Each tracing event outputs a record composed of a generic header followed by a trace point specific structure. The generic header is:
struct ktr_header { int ktr_len; /* length of buf */ short ktr_type; /* trace record type */ short ktr_version; /* trace record version */ pid_t ktr_pid; /* process id */ char ktr_comm[MAXCOMLEN+1]; /* command name */ struct timespec ktr_time; /* timestamp */ lwpid_t ktr_lid; };
The ktr_len
field specifies the length of
the data that follows this header. The ktr_type
and
ktr_version
fields (whose ordering in the structure
depends on byte order) specify the format of this data. The
ktr_pid
, ktr_lid
, and
ktr_comm
fields specify the process and command
generating the record. The ktr_time
field gives the
time (with nanosecond resolution) that the record was generated.
The generic header is followed by ktr_len
bytes of a ktr_type
record of version
ktr_version
. The type specific records are defined
in the ⟨sys/ktrace.h⟩ include
file.
ktrace
() will fail if:
EACCES
]EINVAL
]EIO
]ELOOP
]ENAMETOOLONG
]NAME_MAX
}
characters, or an entire path name exceeded
{PATH_MAX
} characters.ENOENT
]ENOTDIR
]ktrace
function call first appeared in
4.4BSD.
March 19, 2016 | NetBSD 9.0 |