NAME
ktrace —
process tracing
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#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);
DESCRIPTION
The
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.
RETURN VALUES
On successful completion a value of 0 is returned. Otherwise, a value of -1 is
returned and
errno is set to show the error.
ERRORS
ktrace() will fail if:
-
-
- [
EACCES
]
- Search permission is denied for a component of the path
prefix.
-
-
- [
EINVAL
]
- The pathname contains a character with the high-order bit
set.
-
-
- [
EIO
]
- An I/O error occurred while reading from or writing to the
file system.
-
-
- [
ELOOP
]
- Too many symbolic links were encountered in translating the
pathname.
-
-
- [
ENAMETOOLONG
]
- A component of a pathname exceeded
{
NAME_MAX
} characters, or an entire path name
exceeded {PATH_MAX
} characters.
-
-
- [
ENOENT
]
- The named tracefile does not exist.
-
-
- [
ENOTDIR
]
- A component of the path prefix is not a directory.
SEE ALSO
kdump(1),
ktrace(1)
HISTORY
A
ktrace function call first appeared in
4.4BSD.