.\" Copyright (c) 1992, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software developed by the Computer Systems
.\" Engineering group at Lawrence Berkeley Laboratory under DARPA contract
.\" BG 91-66 and contributed to Berkeley.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)kvm_open.3	8.3 (Berkeley) 4/19/94
.\" %FreeBSD: src/lib/libkvm/kvm_open.3,v 1.5.2.3 2001/01/16 10:33:29 ru Exp %
.\"
.\" $FreeBSD$
.Dd April 19, 1994
.Dt KVM_OPEN 3
.Os
.Sh 名称
.Nm kvm_open ,
.Nm kvm_openfiles ,
.Nm kvm_close
.Nd カーネル仮想メモリアクセスの初期化
.Sh ライブラリ
.Lb libkvm
.Sh 書式
.Fd #include <fcntl.h>
.Fd #include <kvm.h>
.Ft kvm_t *
.Fn kvm_open "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "const char *errstr"
.Ft kvm_t *
.Fn kvm_openfiles "const char *execfile" "const char *corefile" "const char *swapfile" "int flags" "char *errbuf"
.Ft int
.Fn kvm_close "kvm_t *kd"
.Sh 解説
.Fn kvm_open
と
.Fn kvm_openfiles
の各関数は
.Xr kvm 3
ライブラリルーチンを介しカーネル仮想メモリに
アクセスするために使われる記述子を返します。
作動中カーネルとクラッシュダンプの双方とも、
このインタフェース経由でアクセス可能です。
.Pp
.Fa execfile
は、検証されるカーネルの実行可能イメージです。
このファイルにはシンボルテーブルが含まれる必要があります。
この引数が
.Dv NULL
のとき、現在実行中のシステムと仮定して
.Xr getbootfile 3
から決定されます。
.Pp
.Fa corefile
はカーネルメモリデバイスファイルで、/dev/mem か
.Xr savecore 8
が生成するクラッシュダンプコアのいずれかです。
.Fa corefile
が
.Dv NULL
のとき、<paths.h> が指示するデフォルト値
.Dv _PATH_MEM
が使われます。
.Pp
.Fa swapfile
はスワップデバイスを指示します。
.Dv NULL
のとき、<paths.h> の
.Dv _PATH_DRUM
が使われます。
.Pp
.Fa flags
引数は、
.Xr open 2
同様に読取り / 書込みアクセスフラグを示し、
コアファイルに限定して適用します。
.Dv O_RDONLY ,
.Dv O_WRONLY ,
.Dv O_RDWR
だけが許可されます。
.Pp
オープンルーチンは 2 個あり、
その違いはエラー機構だけです。
一方は SunOS kvm ライブラリと後方互換性があり、
他方は改善されたエラー報告フレームワークを提供します。
.Pp
.Fn kvm_open
関数は Sun kvm と互換のオープン呼び出しです。
ここでは、
.Fa errstr
引数はエラーの処理方法を示します。
.Dv NULL
のとき、エラーは報告されず、
アプリケーションプログラムは kvm
呼び出しが失敗した原因は知らされません。
.Dv NULL
でなければ、
.Xr perror 3
同様に、
前に
.Fa errstr
が付加されたメッセージが stderr に印字されます。
通常、プログラム名が使われます。
少なくとも対応する
.Fn kvm_close
呼び出しまでは、この文字列は変わらないものと仮定されます。
.Pp
.Fn kvm_openfiles
関数は BSD 様式のエラー報告を行います。
ライブラリは、エラーメッセージを印字しません。
代わりに、アプリケーションが
.Fn kvm_geterr
.Xr (kvm_geterr 3
参照) を使用して、
一番最後の kvm library 呼び出しに該当するエラーメッセージを獲得します。
最後の kvm 呼び出しが正常であれば、結果は未定義となります。
.Fn kvm_geterr
は kvm 記述子を要求しますが、
オープンルーチンはオープン失敗のときには
.Dv NULL
を返しますので、オープンに失敗したときには、
.Fn kvm_geterr
を使ってエラーメッセージを獲得できません。
このような事情があるため、
.Fn kvm_openfiles
は任意のエラーメッセージを
.Fa errbuf
引数中に置きます。
このバッファの大きさは _POSIX2_LINE_MAX 文字分必要です
(<limits.h> より)。
.Sh 戻り値
.Fn kvm_open
と
.Fn kvm_openfiles
の関数は、その後のすべての kvm ライブラリ呼び出しで
使用するための記述子を返します。
ライブラリは完全に再入可能です。
異常終了時には
.Dv NULL
が返されますが、この場合、
.Fn kvm_openfiles
はエラーメッセージを
.Fa errbuf
に書き込みます。
.Pp
.Fn kvm_close
関数は正常終了時に 0 を返し、
異常終了時には -1 を返します。
.Sh バグ
オープン呼び出しが 2 種類ある現状は望ましくありません。
Sun ライブラリのエラーセマンティクスが誤って定義されていたこと、
BSD において後方互換ライブラリを持ちたかったことは、
選択の余地をほとんど残しませんでした。
.Sh 関連項目
.Xr open 2 ,
.Xr kvm 3 ,
.Xr kvm_getargv 3 ,
.Xr kvm_getenvv 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_getprocs 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3