Document fktrace(2) more completely, including separation of errors.

Add a few errors that were previously undocumented.

ok jmc@

1 files changed, 69 insertions, 19 deletions

diff --git a/lib/libc/sys/ktrace.2 b/lib/libc/sys/ktrace.2
index 9a8bd417021..da5d5fd090a 100644
--- a/lib/libc/sys/ktrace.2
+++ b/lib/libc/sys/ktrace.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ktrace.2,v 1.33 2017/10/07 06:36:27 guenther Exp $
+.\"	$OpenBSD: ktrace.2,v 1.34 2017/10/08 19:21:10 guenther Exp $
 .\"	$NetBSD: ktrace.2,v 1.2 1995/02/27 12:33:58 cgd Exp $
 .\"
 .\" Copyright (c) 1993
@@ -30,7 +30,7 @@
 .\"
 .\"     @(#)ktrace.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd $Mdocdate: October 7 2017 $
+.Dd $Mdocdate: October 8 2017 $
 .Dt KTRACE 2
 .Os
 .Sh NAME
@@ -49,25 +49,26 @@
 .Sh DESCRIPTION
 The
 .Fn ktrace
-function enables or disables tracing of one or more processes.
+and
+.Fn fktrace
+functions enable or disable tracing of one or more processes.
 Users may only trace their own processes.
 Only the superuser can trace setuid or setgid programs.
-.Fn ktrace
-is only available on kernels compiled with the
+These functions are only available on kernels compiled with the
 .Cm KTRACE
 option.
 .Pp
+For
+.Fn ktrace ,
 .Fa tracefile
 gives the pathname of the file to be used for tracing.
 The file must exist, be writable by the calling process, and
 not be a symbolic link.
-An existing file descriptor
+For
+.Fn fktrace ,
+an existing file descriptor
 .Fa tracefd
-may be used with
-.Fn fktrace .
-All trace records are always appended to the file,
-so the file must be truncated to zero length to discard
-previous trace data.
+gives the open file descriptor to which the trace records are written.
 If tracing points are being disabled (see
 .Dv KTROP_CLEAR
 below),
@@ -78,6 +79,10 @@ or
 .Fa tracefd
 may be -1.
 .Pp
+Trace records are always appended to the file, ignoring the file offset,
+so the caller will usually want to truncate the file before calling
+these functions.
+.Pp
 The
 .Fa ops
 parameter specifies the requested ktrace operation.
@@ -91,7 +96,7 @@ Enable trace points specified in
 Disable trace points specified in
 .Fa trpoints .
 .It Dv KTROP_CLEARFILE
-Stop all tracing.
+Stop all tracing to the trace file.
 .It Dv KTRFLAG_DESCEND
 The tracing change should apply to the
 specified process and all its current children.
@@ -183,12 +188,40 @@ include file.
 .Rv -std
 .Sh ERRORS
 .Fn ktrace
+and
+.Fn fktrace
+will fail if:
+.Bl -tag -width EINVALAA
+.It Bq Er EINVAL
+No trace points were selected.
+.It Bq Er EPERM
+The tracing process is not the superuser and either its effective
+user ID does not match the real user ID of the receiving process,
+its effective group ID does not match the real group ID of the
+receiving process,
+the receiving process is currently being traced by the superuser,
+or the receiving process has changed its UIDs or GIDs.
+When tracing multiple processes,
+this error is returned if none of the targetted processes could be traced.
+When clearing a trace file with
+.Dv KTROP_CLEARFILE ,
+this error is returned if it could not stop tracing any of the processes
+tracing to the file.
+.It Bq Er ESRCH
+No process can be found corresponding to that specified by
+.Fa pid .
+.It Bq Er EACCES
+The named file is a device or FIFO.
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.El
+.Pp
+Additionally,
+.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
-No trace points were selected.
 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded
 .Dv NAME_MAX
@@ -203,11 +236,20 @@ Search permission is denied for a component of the path prefix or the
 path refers to a symbolic link.
 .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.
-.It Bq Er ESRCH
-No process can be found corresponding to that specified by
-.Fa pid .
+.It Bq Er EFAULT
+.Fa tracefile
+points outside the process's allocated address space.
+.El
+.Pp
+.Fn fktrace
+will fail if:
+.Bl -tag -width EINVALAA
+.It Bq Er EBADF
+.Fa tracefd
+does not refer to a valid descriptor open for writing.
+.It Bq Er EINVAL
+.Fa tracefd
+refers to a socket, pipe, or kqueue, not a file.
 .El
 .Sh SEE ALSO
 .Xr kdump 1 ,
@@ -218,3 +260,11 @@ A
 .Fn ktrace
 function call first appeared in
 .Bx 4.4 .
+The
+.Fn fktrace
+function first appeared in
+.Nx 1.4 .
+It was added to
+.Ox
+in
+.Ox 6.2 .