BSD 4.4 Lite Lib Sources

1 files changed, 162 insertions, 0 deletions

diff --git a/lib/libc/sys/ktrace.2 b/lib/libc/sys/ktrace.2
new file mode 100644
index 0000000..9fe61f8
--- /dev/null
+++ b/lib/libc/sys/ktrace.2
@@ -0,0 +1,162 @@
+.\" Copyright (c) 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)ktrace.2	8.1 (Berkeley) 6/4/93
+.\"
+.Dd June 4, 1993
+.Dt KTRACE 2
+.Os BSD 4
+.Sh NAME
+.Nm ktrace
+.Nd process tracing
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/ktrace.h>
+.Ft int
+.Fn ktrace "const char *tracefile" "int ops" "int trpoints" "int pid"
+.Sh DESCRIPTION
+The
+.Fn 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.
+.Pp
+The
+.Ar 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),
+.Ar tracefile
+may be NULL.
+.Pp
+The
+.Nm ops
+parameter specifies the requested ktrace operation.
+The defined operations are:
+.Bl -column KTRFLAG_DESCENDXXX -offset indent
+.It KTROP_SET	Enable trace points specified in Ar trpoints .
+.It KTROP_CLEAR	Disable trace points specified in Ar trpoints .
+.It KTROP_CLEARFILE	Stop all tracing.
+.It KTRFLAG_DESCEND	The tracing change should apply to the
+specified process and all its current children.
+.El
+.Pp
+The
+.Nm trpoints
+parameter specifies the trace points of interest.
+The defined trace points are:
+.Bl -column KTRFAC_SYSCALLXXX -offset indent
+.It KTRFAC_SYSCALL	Trace system calls.
+.It KTRFAC_SYSRET	Trace return values from system calls.
+.It KTRFAC_NAMEI	Trace name lookup operations.
+.It KTRFAC_GENIO	Trace all I/O (note that this option can
+generate much output).
+.It KTRFAC_PSIG	Trace posted signals.
+.It KTRFAC_CSW	Trace context switch points.
+.It KTRFAC_INHERIT	Inherit tracing to future children.
+.El
+.Pp
+Each tracing event outputs a record composed of a generic header
+followed by a trace point specific structure.
+The generic header is:
+.Bd -literal
+struct ktr_header {
+	int	ktr_len;		/* length of buf */
+	short	ktr_type;		/* trace record type */
+	pid_t	ktr_pid;		/* process id */
+	char	ktr_comm[MAXCOMLEN+1];	/* command name */
+	struct	timeval ktr_time;	/* timestamp */
+	caddr_t	ktr_buf;
+};
+.Ed
+.Pp
+The
+.Nm ktr_len
+field specifies the length of the 
+.Nm ktr_type
+data that follows this header.
+The
+.Nm ktr_pid
+and
+.Nm ktr_comm
+fields specify the process and command generating the record.
+The
+.Nm ktr_time
+field gives the time (with microsecond resolution)
+that the record was generated.
+The
+.Nm ktr_buf
+is an internal kernel pointer and is not useful.
+.Pp
+The generic header is followed by 
+.Nm ktr_len
+bytes of a
+.Nm ktr_type
+record.
+The type specific records are defined in the
+.Pa <sys/ktrace.h>
+include file.
+.Sh RETURN VALUES
+On successful completion a value of 0 is returned.
+Otherwise, a value of -1 is returned and
+.Va errno
+is set to show the error.
+.Sh ERRORS
+.Fn Ktrace
+will fail if:
+.Bl -tag -width ENAMETOOLONGAA
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.It Bq Er EINVAL
+The pathname contains a character with the high-order bit set.
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded 255 characters,
+or an entire path name exceeded 1023 characters.
+.It Bq Er ENOENT
+The named tracefile does not exist.
+.It Bq Er EACCES
+Search permission is denied for a component of the path prefix.
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.El
+.Sh SEE ALSO
+.Xr ktrace 1 ,
+.Xr kdump 1
+.Sh HISTORY
+A
+.Nm ktrace
+function call first appeared in
+.Bx 4.4 .