Kernel VM Library Functions                        kvm_open(3KVM)

NAME
     kvm_open, kvm_close - specify a kernel to examine

SYNOPSIS
     #include <kvm.h>
     #include <fcntl.h>

     kvm_t *kvm_open(char *namelist, char *corefile, char  *swap-
     file, int flag, char *errstr);

     int kvm_close(kvm_t *kd);

DESCRIPTION
  kvm_open()
     The kvm_open() function initializes a set of  file  descrip-
     tors to be used in subsequent calls to kernel virtual memory
     ( VM) routines.  It returns a pointer to a kernel identifier
     that must be used as the kd argument in subsequent kernel VM
     function calls.

     The namelist argument  specifies  an  unstripped  executable
     file  whose  symbol  table  will  be  used to locate various
     offsets in corefile. If namelist is NULL, the  symbol  table
     of the currently running kernel is used to determine offsets
     in the core image.  In this case, it is up to the  implemen-
     tation  to  select  an  appropriate  way to resolve symbolic
     references, for instance,  using  /dev/ksyms  as  a  default
     namelist file.

     The corefile argument specifies  a  file  that  contains  an
     image  of physical memory, for instance, a kernel crash dump
     file (see savecore(1M)) or the special device  /dev/mem.  If
     corefile  is NULL, the currently running kernel is accessed,
     using /dev/mem and /dev/kmem.

     The swapfile argument specifies a file that  represents  the
     swap  device.  If  both  corefile and swapfile are NULL, the
     swap device of the currently  running  kernel  is  accessed.
     Otherwise,  if  swapfile is NULL, kvm_open() may succeed but
     subsequent kvm_getu(3KVM) function calls  may  fail  if  the
     desired information is swapped out.

     The flag function is used to specify read  or  write  access
     for corefile and may have one of the following values:

     O_RDONLY
           open for reading

     O_RDWR
           open for reading and writing

SunOS 5.8            Last change: 9 Jan 1998                    1

Kernel VM Library Functions                        kvm_open(3KVM)

     The errstr argument is used to control error reporting.   If
     it  is a null pointer, no error messages will be printed. If
     it is non-null, it is assumed to be the address of a  string
     that  will  be  used  to  prefix error messages generated by
     kvm_open. Errors are printed to stderr. A  useful  value  to
     supply  for  errstr would be argv[0]. This has the effect of
     printing the process name in front of any error messages.

     Applications using  libkvm are dependent on  the  underlying
     data  model  of  the  kernel image, that is, whether it is a
     32-bit or 64-bit kernel.

     The data model of these applications  must  match  the  data
     model of the kernel in order to correctly interpret the size
     and offsets of  kernel  data  structures.   For  example,  a
     32-bit  application  that  uses  the  32-bit  version of the
     libkvm interfaces will fail to open a 64-bit  kernel  image.
     Similarly, a 64-bit application that uses the 64-bit version
     of the libkvm interfaces will fail to open a  32-bit  kernel
     image.

  kvm_close()
     The kvm_close() function closes all  file  descriptors  that
     were  associated  with  kd.  These  files are also closed on
     exit(2) and execve() (see exec(2)). kvm_close() also  resets
     the  proc  pointer  associated  with  kvm_nextproc(3KVM) and
     flushes any cached kernel data.

RETURN VALUES
     The kvm_open() function returns a  non-null  value  suitable
     for  use  with  subsequent  kernel  VM  function  calls.  On
     failure, it returns NULL and no files are opened.

     The kvm_close() function returns 0 on success -1 on failure.

FILES
     /dev/kmem

     /dev/ksyms

     /dev/mem

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Unsafe                      |
    |_____________________________|_____________________________|

SunOS 5.8            Last change: 9 Jan 1998                    2

Kernel VM Library Functions                        kvm_open(3KVM)

SEE ALSO
     savecore(1M), exec(2), exit(2), pathconf(2), getloadavg(3C),
     kstat(3KSTAT),      kvm_getu(3KVM),      kvm_nextproc(3KVM),
     kvm_nlist(3KVM), kvm_read(3KVM), sysconf(3C),  libkvm(3LIB),
     proc(4), attributes(5)

NOTES
     Kernel core dumps should be  examined  on  the  platform  on
     which  they were created. While a 32-bit application running
     on a 64-bit kernel can examine a 32-bit core dump, a  64-bit
     application running on a 64-bit kernel cannot examine a ker-
     nel core dump from the 32-bit system.

     Applications using  libkvm are likely to  be  platform-  and
     release-dependent.

     On 32-bit systems, applications that use  libkvm  to  access
     the  running  kernel must be 32-bit applications. On systems
     that support both 32-bit and 64-bit  applications,  applica-
     tions  that  use the libkvm interfaces to access the running
     kernel must themselves be 64-bit applications.

     Most of the traditional uses of libkvm have been  superseded
     by more stable interfaces that allow the same information to
     be extracted more efficiently, yet  independent of the  ker-
     nel  data  model.   For  examples, see sysconf(3C), proc(4),
     kstat(3KSTAT), getloadavg(3C), and pathconf(2).

SunOS 5.8            Last change: 9 Jan 1998                    3