lib/libkvm/kvm_getlwps.3

   1 .\"     $NetBSD: kvm_getlwps.3,v 1.4 2004/02/10 12:48:48 jmmv 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 .br
  44 .Ft struct kinfo_lwp *
  45 .Fn kvm_getlwps "kvm_t *kd" "int pid" "u_long procaddr" "int *elemsize" "int *cnt"
  46 .Sh DESCRIPTION
  47 .Fn kvm_getlwps
  48 returns the set of LWPs belonging to the process specified by
  49 .Fa pid
  50 or
  51 .Fa procaddr
  52 in the kernel indicated by
  53 .Fa kd .
  54 The number of LWPs found is returned in the reference parameter
  55 .Fa cnt .
  56 The LWPs are returned as a contiguous array of
  57 .Sy kinfo_lwp
  58 structures.
  59 This memory is locally allocated, and subsequent calls to
  60 .Fn kvm_getlwps
  61 and
  62 .Fn kvm_close
  63 will overwrite this storage.
  64 .Pp
  65 Only the first
  66 .Fa elemsize
  67 bytes of each array entry are returned.
  68 If the size of the
  69 .Sy kinfo_lwp
  70 structure increases in size in a future release of
  71 .Nx
  72 the kernel will only return the requested amount of data for
  73 each array entry and programs that use
  74 .Fn kvm_getlwps
  75 will continue to function without the need for recompilation.
  76 .Pp
  77 If called against an active kernel, the
  78 .Fn kvm_getlwps
  79 function will use the
  80 .Xr sysctl 3
  81 interface and return information about the process identified by
  82 .Fa pid ;
  83 otherwise the kernel memory device file or swap device will be
  84 accessed and the process is identified by the location passed in
  85 .Fa paddr .
  86 .Sh RETURN VALUES
  87 .Fn kvm_getlwps
  88 returns
  89 .Dv NULL
  90 on failure.
  91 .Sh SEE ALSO
  92 .Xr kvm 3 ,
  93 .Xr kvm_close 3 ,
  94 .Xr kvm_geterr 3 ,
  95 .Xr kvm_getproc2 3 ,
  96 .Xr kvm_getprocs 3 ,
  97 .Xr kvm_nlist 3 ,
  98 .Xr kvm_open 3 ,
  99 .Xr kvm_openfiles 3 ,
 100 .Xr kvm_read 3 ,
 101 .Xr kvm_write 3
 102 .Sh BUGS
 103 These routines do not belong in the kvm interface.