share/man/man4/ksyms.4

   1 .\" $NetBSD: ksyms.4,v 1.5 2008/04/30 13:10:54 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\" POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd November 12, 2008
  28 .Dt KSYMS 4
  29 .Os
  30 .Sh NAME
  31 .Nm ksyms
  32 .Nd kernel symbol table interface
  33 .Sh SYNOPSIS
  34 .Cd "pseudo-device ksyms"
  35 .Sh DESCRIPTION
  36 The
  37 .Pa /dev/ksyms
  38 character device provides a read-only interface to the current
  39 kernel symbol table.
  40 It can be accessed either as a sequential
  41 file, where it looks like an executable file but with zero-sized
  42 text and data segments, or via
  43 .Xr ioctl 2 .
  44 .Pp
  45 .Pa /dev/ksyms
  46 represents the symbol table at the time when the device is opened,
  47 and may not change until it is closed.
  48 .Pp
  49 The in-kernel symbol manager is designed to be able to handle
  50 any type of symbol table.
  51 However, only
  52 .Xr elf 5
  53 symbol tables are currently dealt with.
  54 .Sh IOCTLS
  55 The
  56 .Xr ioctl 2
  57 command codes below are defined in
  58 .Aq Pa sys/ksyms.h .
  59 .Pp
  60 The (third) argument to the
  61 .Xr ioctl 2
  62 should be a pointer to the type indicated.
  63 .Bl -tag -width indent -offset indent
  64 .It Dv KIOCGSIZE (int)
  65 Returns the total size of the current symbol table.
  66 This should be used when allocating a buffer to read in the
  67 whole symbol table to memory.
  68 .It Dv KIOCGVALUE (struct ksyms_gsymbol)
  69 Returns the value for the given symbol name in a symtab-independent
  70 fashion.
  71 .Bd -literal -offset indent
  72 struct ksyms_gsymbol {
  73         const char *kg_name;
  74         unsigned long *kg_value;
  75 };
  76 .Ed
  77 .Pp
  78 The struct element
  79 .Va kg_name
  80 should be set to the name of the requested value, and the address that
  81 .Va kg_value
  82 points to will receive the symbol value.
  83 .It Dv KIOCGSYMBOL (struct ksyms_gsymbol)
  84 Returns the complete symbol for the given symbol name.
  85 .Bd -literal -offset indent
  86 struct ksyms_gsymbol {
  87         const char *kg_name;
  88         void *kg_sym;
  89 };
  90 .Ed
  91 .Pp
  92 The struct element
  93 .Va kg_name
  94 should be set to the name of the requested symbol, and the found
  95 symbol will be written to the
  96 .Va kg_sym
  97 address.
  98 It is the callers responsibility to ensure that enough space
  99 for the symbol is allocated.
 100 .El
 101 .Sh FILES
 102 .Bl -tag -width /dev/ksymsX
 103 .It Pa /dev/ksyms
 104 .El
 105 .Sh SEE ALSO
 106 .Xr ioctl 2 ,
 107 .Xr nlist 3 ,
 108 .Xr elf 5
 109 .Sh HISTORY
 110 A
 111 .Nm
 112 device exists in many different operating systems.
 113 This implementation is modelled in function after Solaris
 114 .Nm .
 115 This
 116 .Nm
 117 driver was written by Anders Magnusson for
 118 .Nx .
 119 .Pp
 120 The
 121 .Nm
 122 driver first appeared in
 123 .Nx 2.0 .