BSD 4_4 development

[unix-history] / usr / share / man / cat3 / kvm_openfiles.0

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

N\bNA\bAM\bME\bE
    k\bkv\bvm\bm_\b_o\bop\bpe\ben\bn, k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs, k\bkv\bvm\bm_\b_c\bcl\blo\bos\bse\be - initialize kernel virtual memory ac-
    cess

S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
    #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<f\bfc\bcn\bnt\btl\bl.\b.h\bh>\b>
    #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<k\bkv\bvm\bm.\b.h\bh>\b>

    _\bk_\bv_\bm_\b__\bt _\b*
    k\bkv\bvm\bm_\b_o\bop\bpe\ben\bn(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\be_\bx_\be_\bc_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bc_\bo_\br_\be_\bf_\bi_\bl_\be, _\bc_\bh_\ba_\br _\b*_\bs_\bw_\ba_\bp_\bf_\bi_\bl_\be,
            _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\be_\br_\br_\bs_\bt_\br);

    _\bk_\bv_\bm_\b__\bt _\b*
    k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\be_\bx_\be_\bc_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bc_\bo_\br_\be_\bf_\bi_\bl_\be, _\bc_\bh_\ba_\br _\b*_\bs_\bw_\ba_\bp_\bf_\bi_\bl_\be,
            _\bi_\bn_\bt _\bf_\bl_\ba_\bg_\bs, _\bc_\bh_\ba_\br _\b*_\be_\br_\br_\bb_\bu_\bf);

    _\bi_\bn_\bt
    k\bkv\bvm\bm_\b_c\bcl\blo\bos\bse\be(_\bk_\bv_\bm_\b__\bt _\b*_\bk_\bd);

D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
    The functions k\bkv\bvm\bm_\b_o\bop\bpe\ben\bn() and k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs() 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.

    _\be_\bx_\be_\bc_\bf_\bi_\bl_\be 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>.

    _\bc_\bo_\br_\be_\bf_\bi_\bl_\be is the kernel memory device file.  It can be either /dev/mem or
    a crash dump core generated by savecore(8).  If _\bc_\bo_\br_\be_\bf_\bi_\bl_\be is NULL, the de-
    fault indicated by _PATH_MEM from <paths.h> is used.

    _\bs_\bw_\ba_\bp_\bf_\bi_\bl_\be should indicate the swap device.  If NULL, _PATH_DRUM from
    <paths.h> is used.

    The _\bf_\bl_\ba_\bg_\bs 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 k\bkv\bvm\bm_\b_o\bop\bpe\ben\bn() function is the Sun kvm compatible open call.  Here, the
    _\be_\br_\br_\bs_\bt_\br 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 _\be_\br_\br_\bs_\bt_\br 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 k\bkv\bvm\bm_\b_c\bcl\blo\bos\bse\be() call.

    The k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs() 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 k\bkv\bvm\bm_\b_g\bge\bet\bte\ber\brr\br() (see kvm_geterr(3)).  The results are unde-
    fined if the most recent kvm call did not produce an error.  Since
    k\bkv\bvm\bm_\b_g\bge\bet\bte\ber\brr\br() requires a kvm descriptor, but the open routines return NULL
    on failure, k\bkv\bvm\bm_\b_g\bge\bet\bte\ber\brr\br() cannot be used to get the error message if open
    fails.  Thus, k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs() will place any error message in the _\be_\br_\br_\bb_\bu_\bf
    argument.  This buffer should be _POSIX2_LINE_MAX characters large (from
    <limits.h>).

R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS
    The k\bkv\bvm\bm_\b_o\bop\bpe\ben\bn() and k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs() 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 k\bkv\bvm\bm_\b_o\bop\bpe\ben\bnf\bfi\bil\ble\bes\bs()
    writes the error message into _\be_\br_\br_\bb_\bu_\bf.

    The k\bkv\bvm\bm_\b_c\bcl\blo\bos\bse\be() function returns 0 on sucess and -1 on failure.

B\bBU\bUG\bGS\bS
    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.

S\bSE\bEE\bE A\bAL\bLS\bSO\bO
    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