document /dev/ksyms

1 files changed, 99 insertions, 0 deletions

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.