4.4BSD/usr/share/man/cat3/kvm_open.0

KVM_OPEN(3)                 BSD Programmer's Manual                KVM_OPEN(3)

NNAAMMEE
     kkvvmm__ooppeenn, kkvvmm__ooppeennffiilleess, kkvvmm__cclloossee - initialize kernel virtual memory ac-
     cess

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ffccnnttll..hh>>
     ##iinncclluuddee <<kkvvmm..hh>>

     _k_v_m___t _*
     kkvvmm__ooppeenn(_c_o_n_s_t _c_h_a_r _*_e_x_e_c_f_i_l_e, _c_o_n_s_t _c_h_a_r _*_c_o_r_e_f_i_l_e, _c_h_a_r _*_s_w_a_p_f_i_l_e,
             _i_n_t _f_l_a_g_s, _c_o_n_s_t _c_h_a_r _*_e_r_r_s_t_r);

     _k_v_m___t _*
     kkvvmm__ooppeennffiilleess(_c_o_n_s_t _c_h_a_r _*_e_x_e_c_f_i_l_e, _c_o_n_s_t _c_h_a_r _*_c_o_r_e_f_i_l_e, _c_h_a_r _*_s_w_a_p_f_i_l_e,
             _i_n_t _f_l_a_g_s, _c_h_a_r _*_e_r_r_b_u_f);

     _i_n_t
     kkvvmm__cclloossee(_k_v_m___t _*_k_d);

DDEESSCCRRIIPPTTIIOONN
     The functions kkvvmm__ooppeenn() and kkvvmm__ooppeennffiilleess() return a descriptor used to
     access kernel virtual memory via the kvm(3) library routines.  Both ac-
     tive kernels and crash dumps are accessible through this interface.

     _e_x_e_c_f_i_l_e is the executable image of the kernel being examined.  This file
     must contain a symbol table.  If this argument is NULL, the currently
     running system is assumed, which is indicated by _PATH_UNIX in <paths.h>.

     _c_o_r_e_f_i_l_e is the kernel memory device file.  It can be either /dev/mem or
     a crash dump core generated by savecore(8).  If _c_o_r_e_f_i_l_e is NULL, the de-
     fault indicated by _PATH_MEM from <paths.h> is used.

     _s_w_a_p_f_i_l_e should indicate the swap device.  If NULL, _PATH_DRUM from
     <paths.h> is used.

     The _f_l_a_g_s argument indicates read/write access as in open(2) and applies
     to only the core file.  Only O_RDONLY, O_WRONLY, and O_RDWR are permit-
     ted.

     There are two open routines which differ only with respect to the error
     mechanism.  One provides backward compatibility with the SunOS kvm li-
     brary, while the other provides an improved error reporting framework.

     The kkvvmm__ooppeenn() function is the Sun kvm compatible open call.  Here, the
     _e_r_r_s_t_r argument indicates how errors should be handled.  If it is NULL,
     no errors are reported and the application cannot know the specific na-
     ture of the failed kvm call.  If it is not NULL, errors are printed to
     stderr with _e_r_r_s_t_r prepended to the message, as in perror(3).  Normally,
     the name of the program is used here.  The string is assumed to persist
     at least until the corresponding kkvvmm__cclloossee() call.

     The kkvvmm__ooppeennffiilleess() function provides BSD style error reporting.  Here,
     error messages are not printed out by the library.  Instead, the applica-
     tion obtains the error message corresponding to the most recent kvm li-
     brary call using kkvvmm__ggeetteerrrr() (see kvm_geterr(3)).  The results are unde-
     fined if the most recent kvm call did not produce an error.  Since
     kkvvmm__ggeetteerrrr() requires a kvm descriptor, but the open routines return NULL
     on failure, kkvvmm__ggeetteerrrr() cannot be used to get the error message if open
     fails.  Thus, kkvvmm__ooppeennffiilleess() will place any error message in the _e_r_r_b_u_f
     argument.  This buffer should be _POSIX2_LINE_MAX characters large (from
     <limits.h>).

RREETTUURRNN VVAALLUUEESS
     The kkvvmm__ooppeenn() and kkvvmm__ooppeennffiilleess() functions both return a descriptor to
     be used in all subsequent kvm library calls.  The library is fully re-
     entrant.  On failure, NULL is returned, in which case kkvvmm__ooppeennffiilleess()
     writes the error message into _e_r_r_b_u_f.

     The kkvvmm__cclloossee() function returns 0 on sucess and -1 on failure.

BBUUGGSS
     There should not be two open calls.  The ill-defined error semantics of
     the Sun library and the desire to have a backward-compatible library for
     BSD left little choice.

SSEEEE AALLSSOO
     open(2),  kvm(3),  kvm_getargv(3),  kvm_getenvv(3),  kvm_geterr(3),
     kvm_getprocs(3),  kvm_nlist(3),  kvm_read(3),  kvm_write(3)

4.4BSD                           June 4, 1993                                2