document /dev/ksyms

2 files changed, 102 insertions, 3 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 19e1782e12b..b0e04e23c82 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,10 +1,10 @@
-#	$OpenBSD: Makefile,v 1.40 1998/08/22 02:03:03 csapuntz Exp $
+#	$OpenBSD: Makefile,v 1.41 1998/08/25 02:50:57 millert Exp $
 #	$NetBSD: Makefile,v 1.22.4.2 1996/07/18 00:51:10 jtc Exp $
 
 MAN=	atalk.4 audio.4 acd.4 ahc.4 bpf.4 ccd.4 cd.4 ch.4 clnp.4 cltp.4 ddb.4 \
 	de.4 drum.4 eap.4 esis.4 fd.4 ffs_softupdates.4 fpa.4 fxp.4 icmp.4 \
-	idp.4 imp.4 inet.4 ip.4 ipl.4 ipsec.4 isapnp.4 iso.4 isp.4 lkm.4 lo.4 \
-	mtio.4 ncr.4 netintro.4 ns.4 \
+	idp.4 imp.4 inet.4 ip.4 ipl.4 ipsec.4 isapnp.4 iso.4 isp.4 ksyms.4 \
+	lkm.4 lo.4 mtio.4 ncr.4 netintro.4 ns.4 \
 	nsip.4 null.4 options.4 pty.4 random.4 route.4 scsi.4 sd.4 sl.4 \
 	spp.4 st.4 sv.4 \
 	tb.4 tcp.4 termios.4 tty.4 tp.4 tun.4 udp.4 uk.4 unix.4 vnd.4 wd.4 ym.4
diff --git a/share/man/man4/ksyms.4 b/share/man/man4/ksyms.4
new file mode 100644
index 00000000000..b60deeb77f2
--- /dev/null
+++ b/share/man/man4/ksyms.4
@@ -0,0 +1,99 @@
+.\" $OpenBSD: ksyms.4,v 1.1 1998/08/25 02:50:56 millert Exp $
+.\"
+.\" Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com>
+.\" 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. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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.
+.\"
+.Dd August 24, 1998
+.Dt KSYMS 4
+.Os OpenBSD
+.Sh NAME
+.Nm ksyms
+.Nd kernel symbol table device
+.Sh SYNOPSIS
+.Sy pseudo-device Nm ksyms 1
+.Sh DESCRIPTION
+The
+.Nm ksyms
+device masquerades as an
+.Em a.out
+executable with the symbols from the running kernel as its
+symbol segment.  Use of
+.Nm
+requires that the boot loader preserve the kernel symbols and place
+them at the end of the kernel's address space.  Any port that is capable
+of using the
+.Em DDB
+debugger does this, even if
+.Em DDB
+is not configured into the kernel.
+.Pp
+The
+.Nm
+device is used to look up the symbol table name list from the running
+kernel.  Because it represents the running kernel it is guaranteed
+to always be up to date even if the kernel file has been changed (or
+is even non-existent).  It is most useful when used in conjuction with
+.Xr nlist 3
+or the
+.Xr kvm 3
+routines (note that
+.Xr kvm_open 3
+and
+.Xr kvm_openfiles 3
+will try
+.Nm
+automatically if the first parameter to them is the
+.Dv NULL
+pointer).
+.Sh ERRORS
+device will 
+An open of
+.Nm
+will fail if:
+.Bl -tag -width Er
+.It Bq Er EPERM
+An open was attempted with write permissions.
+.It Bq Er ENXIO
+No kernel symbols were saved by the boot loader (usually because
+they were removed with
+.Xr strip 1).
+.El
+.Sh SEE ALSO
+.Xr kvm 3 ,
+.Xr nlist 3
+.Sh HISTORY
+The
+.Nm
+device appeared in
+.Ox 2.4 .
+.Sh BUGS
+It is not possible to
+.Xr mmap 2
+.Nm
+because the boot loader does not load the symbol table onto a page
+boundary (so it is not page aligned).  If all the boot loaders were
+fixed,
+.Xr mmap 2
+support would be trivial.