lib/libkvm/kvm_getlwps.3

   1 .\"     $NetBSD: kvm_getlwps.3,v 1.5 2008/04/30 13:10:51 martin Exp $
   2 .\"
   3 .\"Copyright (c) 2002 The NetBSD Foundation, Inc.
   4 .\"All rights reserved.
   5 .\"
   6 .\"This code is derived from software contributed to The NetBSD Foundation
   7 .\"by Nathan J. Williams.
   8 .\"
   9 .\"Redistribution and use in source and binary forms, with or without
  10 .\"modification, are permitted provided that the following conditions
  11 .\"are met:
  12 .\"1. Redistributions of source code must retain the above copyright
  13 .\"   notice, this list of conditions and the following disclaimer.
  14 .\"2. Redistributions in binary form must reproduce the above copyright
  15 .\"   notice, this list of conditions and the following disclaimer in the
  16 .\"   documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\"THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\"``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\"TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\"PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\"BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\"CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\"SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\"INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\"CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\"ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\"POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd February 10, 2004
  31 .Dt KVM_GETLWPS 3
  32 .Os
  33 .Sh NAME
  34 .Nm kvm_getlwps
  35 .Nd access state of LWPs belonging to a user process
  36 .Sh LIBRARY
  37 .Lb libkvm
  38 .Sh SYNOPSIS
  39 .In kvm.h
  40 .In sys/param.h
  41 .In sys/sysctl.h
  42 .\" .Fa kvm_t *kd
  43 .Ft struct kinfo_lwp *
  44 .Fn kvm_getlwps "kvm_t *kd" "int pid" "u_long procaddr" "int *elemsize" "int *cnt"
  45 .Sh DESCRIPTION
  46 .Fn kvm_getlwps
  47 returns the set of LWPs belonging to the process specified by
  48 .Fa pid
  49 or
  50 .Fa procaddr
  51 in the kernel indicated by
  52 .Fa kd .
  53 The number of LWPs found is returned in the reference parameter
  54 .Fa cnt .
  55 The LWPs are returned as a contiguous array of
  56 .Sy kinfo_lwp
  57 structures.
  58 This memory is locally allocated, and subsequent calls to
  59 .Fn kvm_getlwps
  60 and
  61 .Fn kvm_close
  62 will overwrite this storage.
  63 .Pp
  64 Only the first
  65 .Fa elemsize
  66 bytes of each array entry are returned.
  67 If the size of the
  68 .Sy kinfo_lwp
  69 structure increases in size in a future release of
  70 .Nx
  71 the kernel will only return the requested amount of data for
  72 each array entry and programs that use
  73 .Fn kvm_getlwps
  74 will continue to function without the need for recompilation.
  75 .Pp
  76 If called against an active kernel, the
  77 .Fn kvm_getlwps
  78 function will use the
  79 .Xr sysctl 3
  80 interface and return information about the process identified by
  81 .Fa pid ;
  82 otherwise the kernel memory device file or swap device will be
  83 accessed and the process is identified by the location passed in
  84 .Fa paddr .
  85 .Sh RETURN VALUES
  86 .Fn kvm_getlwps
  87 returns
  88 .Dv NULL
  89 on failure.
  90 .Sh SEE ALSO
  91 .Xr kvm 3 ,
  92 .Xr kvm_close 3 ,
  93 .Xr kvm_geterr 3 ,
  94 .Xr kvm_getproc2 3 ,
  95 .Xr kvm_getprocs 3 ,
  96 .Xr kvm_nlist 3 ,
  97 .Xr kvm_open 3 ,
  98 .Xr kvm_openfiles 3 ,
  99 .Xr kvm_read 3 ,
 100 .Xr kvm_write 3
 101 .Sh BUGS
 102 These routines do not belong in the kvm interface.