.\" 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
.\"
.\" jpman %Id%
.\"
.Dd April 19, 1994
.Dt KVM_OPEN 3
.Os
.Sh 名称
.Nm kvm_open ,
.Nm kvm_openfiles ,
.Nm kvm_close
.Nd カーネル仮想メモリ・アクセスの初期化
.Sh 書式
.Fd #include <fcntl.h>
.Fd #include <kvm.h>
.br
.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 ヌル
のとき、現在実行中のシステムと仮定して
.Xr getbootfile 3
から決定されます。
.Pp
.Fa corefile
はカーネル・メモリ・デバイスファイルで、/dev/mem にも
.Xr savecore 8
が生成するクラッシュダンプコアにもなります。
.Fa corefile
が
.Dv ヌル
のとき、<paths.h> が指示するデフォルト値
.Dv _PATH_MEM
が使われます。
.Pp
.Fa swapfile
はスワップ・デバイスを指示します。
.Dv ヌル
のとき、<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 ヌル
のとき、エラーは報告されず、
アプリケーション・プログラムは kvm
呼び出しが失敗した原因は知らされません。
結果が
.Dv ヌル
でなければ、
.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 ヌル
を戻し、オープンに失敗したときには、
.Fn kvm_geterr
を使ってエラー・メッセージを獲得できません。
したがって、
.Fn kvm_openfiles
は任意のエラー・メッセージを
.Fa errbuf
引数中に置きます。
このバッファの大きさは _POSIX2_LINE_MAX キャラクタ分必要です
(<limits.h>より)。
.Sh 戻り値
.Fn kvm_open
と
.Fn kvm_openfiles
関数は、その後のすべての kvm ライブラリ呼び出しで
使用するための記述子を返します。
ライブラリは完全に再入可能です。
異常終了時には
.Dv ヌル
が返されますが、この場合、
.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