.\" 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_getprocs.3	8.1 (Berkeley) 6/4/93
.\" %FreeBSD: src/lib/libkvm/kvm_getprocs.3,v 1.6.2.6 2001/12/17 10:08:30 ru Exp %
.\"
.\" $FreeBSD$
.Dd June 4, 1993
.Dt KVM_GETPROCS 3
.Os
.Sh 名称
.Nm kvm_getprocs ,
.Nm kvm_getargv ,
.Nm kvm_getenvv
.Nd ユーザプロセス状態にアクセスする
.Sh ライブラリ
.Lb libkvm
.Sh 書式
.In kvm.h
.In sys/param.h
.In sys/sysctl.h
.\" .Fa kvm_t *kd
.Ft struct kinfo_proc *
.Fn kvm_getprocs "kvm_t *kd" "int op" "int arg" "int *cnt"
.Ft char **
.Fn kvm_getargv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
.Ft char **
.Fn kvm_getenvv "kvm_t *kd" "const struct kinfo_proc *p" "int nchr"
.Sh 解説
.Fn kvm_getprocs
は
.Fa kd
が指示するカーネルの動作中のプロセスの (サブ) 集合を返します。
.Fa op
と
.Fa arg
の引数は,返されるプロセスの集合を制限する属性を構成します。
.Fa op
の値は以下のフィルタリング属性を記述しています :
.Pp
.Bl -tag -width 20n -offset indent -compact
.It Sy KERN_PROC_ALL
すべてのプロセス
.It Sy KERN_PROC_PID
プロセス ID
.Fa arg
を持つプロセス
.It Sy KERN_PROC_PGRP
プロセスグループ
.Fa arg
を持つプロセス
.It Sy KERN_PROC_SESSION
セッション
.Fa arg
を持つプロセス
.It Sy KERN_PROC_TTY
tty
.Fa arg
を持つプロセス
.It Sy KERN_PROC_UID
実効ユーザ ID
.Fa arg
を持つプロセス
.It Sy KERN_PROC_RUID
実ユーザ ID
.Fa arg
を持つプロセス
.El
.Pp
見つけたプロセス数は参照パラメータ
.Fa cnt
で返されます。
プロセスは kinfo_proc 構造体の連続配列として返されます。
このメモリは局所的に割り当てられ、
.Fn kvm_getprocs
と
.Fn kvm_close
に引き続く呼び出しはこの記憶域に上書きします。
.Pp
.Fn kvm_getargv
はヌルで終了する引数ベクタを返します。
このベクタは
.Fa p
が示すプロセスに渡されたコマンドライン引数に対応します。
おそらく、これらの引数はプロセス生成時の
.Xr exec 3
に渡された値に相当します。
しかしながら、この情報は、
故意にプロセス自身のコントロール下にあります。
オリジナルのコマンド名は、
.Fn kvm_getprocs
によって返されたプロセス構造体の p_comm フィールドに、
変更されていない状態で見つけることができます。
.Pp
.Fa nchr
引数はヌルバイトを含めた最大の文字数を示し、
文字列の構築に使います。
もしもこの量を超えてしまえば、
オーバフローの原因となる文字列は切り捨てられ、
結果が部分的に返されます。これは
.Xr ps 1
や
.Xr w 1
のようなプログラムにとっては簡便な方法です。
これらのプログラムにおいては、
コマンドの 1 行要約のみを印字しますので、
無視するためのみに多量のテキストを複写すべきではありません。
.Fa nchr
が 0 ならば、なんら制限は課されませんし、
すべての引数の文字列はそっくりそのまま返されます。
.Pp
argv ポインタと文字列記憶域に割り当てられたメモリは、
kvm ライブラリによって所有されます。引き続く
.Fn kvm_getprocs
と
.Xr kvm_close 3
呼び出しはこの記憶域を容赦なく使います。
.Pp
.Fn kvm_getenvv
関数は
.Fn kvm_getargv
に類似していますが、環境文字列のベクタを返します。
このデータはまたプロセスにより変更可能です。
.Sh 戻り値
.Fn kvm_getprocs ,
.Fn kvm_getargv ,
および
.Fn kvm_getenvv
はすべて異常終了時に
.Dv NULL
を返します。
.Sh バグ
これらのルーチンは kvm インタフェースに属していません。
.Sh 関連項目
.Xr kvm 3 ,
.Xr kvm_close 3 ,
.Xr kvm_geterr 3 ,
.Xr kvm_nlist 3 ,
.Xr kvm_open 3 ,
.Xr kvm_openfiles 3 ,
.Xr kvm_read 3 ,
.Xr kvm_write 3