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