share/man/man7d/ksyms.7d

   1 '\" te
   2 .\"  Copyright (c) 2000 Sun Microsystems, Inc.
   3 .\"  All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH KSYMS 7D "Dec 11, 2000"
   8 .SH NAME
   9 ksyms \- kernel symbols
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/dev/ksyms\fR
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The file  \fB/dev/ksyms\fR is a character special file that allows read-only
  20 access to an  \fBELF\fR format image containing two sections: a symbol table
  21 and a corresponding string table. The contents of the symbol table reflect the
  22 symbol state of the currently running kernel. You can determine the size  of
  23 the image with the \fBfstat\fR(\|) system call. The recommended method for
  24 accessing the  \fB/dev/ksyms\fR file is by using the  \fBELF\fR access library.
  25 See \fBelf\fR(3ELF) for details.  If you are not familiar with  \fBELF\fR
  26 format, see \fBa.out\fR(4).
  27 .sp
  28 .LP
  29 \fB/dev/ksyms\fR is an executable for the processor on which you are accessing
  30 it. It contains  \fBELF\fR program headers which describe the text and data
  31 segment(s) in kernel memory. Since  \fB/dev/ksyms\fR has no text or data, the
  32 fields specific to file attributes are initialized to \fINULL\fR. The remaining
  33 fields describe the text or data segment(s) in kernel memory.
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fBSymbol table\fR\fR
  38 .ad
  39 .RS 16n
  40 The  \fBSYMTAB\fR section contains the symbol table entries present in the
  41 currently running kernel. This section is ordered as defined by the \fBELF\fR
  42 definition with locally-defined symbols first, followed by globally-defined
  43 symbols. Within symbol type, the symbols are ordered by kernel module load
  44 time. For example, the kernel file symbols are first, followed by the first
  45 module's symbols, and so on, ending with the symbols from the last module
  46 loaded.
  47 .sp
  48 The section header index (st_shndx) field of each symbol entry in the symbol
  49 table is set to  \fBSHN_ABS,\fR because any necessary symbol relocations are
  50 performed by the kernel link editor at module load time.
  51 .RE
  52
  53 .sp
  54 .ne 2
  55 .na
  56 \fB\fBString table\fR\fR
  57 .ad
  58 .RS 16n
  59 The  \fBSTRTAB\fR section contains the symbol name strings that the symbol
  60 table entries reference.
  61 .RE
  62
  63 .SH SEE ALSO
  64 .sp
  65 .LP
  66 \fBkernel\fR(8), \fBstat\fR(2), \fBelf\fR(3ELF), \fBkvm_open\fR(3KVM),
  67 \fBa.out\fR(4), \fBmem\fR(7D)
  68 .SH WARNINGS
  69 .sp
  70 .LP
  71 The kernel is dynamically configured. It loads kernel modules when necessary.
  72 Because of this aspect of the system, the symbol information present in the
  73 running system can vary from time to time, as kernel modules are loaded and
  74 unloaded.
  75 .sp
  76 .LP
  77 When you open the  \fB/dev/ksyms\fR file, you have access to an  \fBELF\fR
  78 image which represents a snapshot of the state of the kernel symbol information
  79 at that instant in time. While the \fB/dev/ksyms\fR file remains open, kernel
  80 module autounloading is disabled, so that you are protected from the
  81 possibility of acquiring stale symbol data.  Note that new modules can still be
  82 loaded, however. If kernel modules are loaded while you have the
  83 \fB/dev/ksyms\fR file open, the snapshot held by you will not be updated. In
  84 order to have access to the symbol information of the newly loaded modules, you
  85 must first close and then reopen the  \fB/dev/ksyms\fR file. Be aware that the
  86 size of the \fB/dev/ksyms\fR file will have changed. You will need to use the
  87 \fBfstat()\fR function (see \fBstat\fR(2)) to determine the new size of the
  88 file.
  89 .sp
  90 .LP
  91 Avoid keeping the  \fB/dev/ksyms\fR file open for extended periods of time,
  92 either by using \fBkvm_open\fR(3KVM) of the default namelist file or with a
  93 direct open. There are two reasons why you should not hold  \fB/dev/ksyms\fR
  94 open. First, the system's ability to dynamically configure itself is partially
  95 disabled by the locking down of loaded modules. Second, the snapshot of symbol
  96 information held by you will not reflect the symbol information of modules
  97 loaded after your initial open of  \fB/dev/ksyms\fR.
  98 .sp
  99 .LP
 100 Note that the  \fBksyms\fR driver is a loadable module, and that the kernel
 101 driver modules are only loaded during an open system call. Thus it is possible
 102 to run \fBstat\fR(2) on the  \fB/dev/ksyms\fR file without causing the
 103 \fBksyms\fR driver to be loaded. In this case, the file size returned is
 104 \fBUNKNOWN_SIZE\fR.  A solution for this behavior is to first open the
 105 \fB/dev/ksyms\fR file, causing the  \fBksyms\fR driver to be loaded (if
 106 necessary). You can then use the file descriptor from this open in a
 107 \fBfstat\fR(\|) system call to get the file's size.
 108 .SH NOTES
 109 .sp
 110 .LP
 111 The kernel virtual memory access library (\fBlibkvm\fR) routines use
 112 \fB/dev/ksyms\fR as the default namelist file. See \fBkvm_open\fR(3KVM) for
 113 details.