share/man/man3kvm/kvm_nextproc.3kvm

   1 '\" te
   2 .\"  Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH KVM_NEXTPROC 3KVM "May 2, 2002"
   7 .SH NAME
   8 kvm_nextproc, kvm_getproc, kvm_setproc \- read system process structures
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lkvm\fR [ \fIlibrary\fR\&.\|.\|.]
  13 #include <kvm.h>
  14 #include <sys/param.h>
  15 #include <sys/time.h>
  16 #include <sys/proc.h>
  17
  18 \fBstruct proc *\fR\fBkvm_nextproc\fR(\fBkvm_t *\fR\fIkd\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBkvm_setproc\fR(\fBkvm_t *\fR\fIkd\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBstruct proc *\fR\fBkvm_getproc\fR(\fBkvm_t *\fR\fIkd\fR, \fBpid_t\fR \fIpid\fR);
  29 .fi
  30
  31 .SH DESCRIPTION
  32 .sp
  33 .LP
  34 The \fBkvm_nextproc()\fR function reads sequentially all of the system process
  35 structures from the kernel identified by \fIkd\fR (see \fBkvm_open\fR(3KVM)).
  36 Each call to \fBkvm_nextproc()\fR returns a pointer to the static memory area
  37 that contains a copy of the next valid process table entry. There is no
  38 guarantee that the data will remain valid across calls to \fBkvm_nextproc()\fR,
  39 \fBkvm_setproc()\fR, or \fBkvm_getproc()\fR. If the process structure must be
  40 saved, it should be copied to non-volatile storage.
  41 .sp
  42 .LP
  43 For performance reasons, many implementations will cache a set of system
  44 process structures. Since the system state is liable to change between calls to
  45 \fBkvm_nextproc()\fR, and since the cache may contain obsolete information,
  46 there is no guarantee that every process structure returned refers to an active
  47 process, nor is it certain that all processes will be reported.
  48 .sp
  49 .LP
  50 The \fBkvm_setproc()\fR function rewinds the process list, enabling
  51 \fBkvm_nextproc()\fR to rescan from the beginning of the system process table.
  52 This function will always flush the process structure cache, allowing an
  53 application to re-scan the process table of a running system.
  54 .sp
  55 .LP
  56 The \fBkvm_getproc()\fR function locates the \fBproc\fR structure of the
  57 process specified by \fIpid\fR and returns a pointer to it.  Although this
  58 function does not interact with the process table pointer manipulated by
  59 \fBkvm_nextproc()\fR, the restrictions regarding the validity of the data still
  60 apply.
  61 .SH RETURN VALUES
  62 .sp
  63 .LP
  64 On success, \fBkvm_nextproc()\fR returns a pointer to a copy of the next valid
  65 process table entry. On failure, it returns \fINULL\fR.
  66 .sp
  67 .LP
  68 On success, \fBkvm_getproc()\fR returns a pointer to the \fIproc\fR structure
  69 of the process specified by \fIpid\fR. On failure, it returns \fINULL\fR.
  70 .sp
  71 .LP
  72 The \fBkvm_setproc()\fR function returns 0 on success and \(mi1 on failure.
  73 .SH ATTRIBUTES
  74 .sp
  75 .LP
  76 See \fBattributes\fR(5) for descriptions of the following attributes:
  77 .sp
  78
  79 .sp
  80 .TS
  81 box;
  82 c | c
  83 l | l .
  84 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  85 _
  86 Interface Stability     Stable
  87 _
  88 MT-Level        Unsafe
  89 .TE
  90
  91 .SH SEE ALSO
  92 .sp
  93 .LP
  94 \fBkvm_getu\fR(3KVM), \fBkvm_open\fR(3KVM), \fBkvm_kread\fR(3KVM),
  95 \fBattributes\fR(5)