lib/libprocstat/libprocstat.3

   1 .\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd July 12, 2011
  28 .Dt LIBPROCSTAT 3
  29 .Os
  30 .Sh NAME
  31 .Nm procstat_open_kvm ,
  32 .Nm procstat_open_sysctl ,
  33 .Nm procstat_close ,
  34 .Nm procstat_getfiles ,
  35 .Nm procstat_getprocs ,
  36 .Nm procstat_freefiles ,
  37 .Nm procstat_freeprocs ,
  38 .Nm procstat_get_pipe_info ,
  39 .Nm procstat_get_pts_info ,
  40 .Nm procstat_get_socket_info ,
  41 .Nm procstat_get_vnode_info
  42 .Nd library interface for file and process information retrieval
  43 .Sh LIBRARY
  44 .Lb libprocstat
  45 .Sh SYNOPSIS
  46 .In sys/param.h
  47 .In sys/queue.h
  48 .In libprocstat.h
  49 .Ft void
  50 .Fn procstat_close "struct procstat *procstat"
  51 .Ft void
  52 .Fo procstat_freefiles
  53 .Fa "struct procstat *procstat"
  54 .Fa "struct filestat_list *head"
  55 .Fc
  56 .Ft void
  57 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
  58 .Ft int
  59 .Fo procstat_get_pipe_info
  60 .Fa "struct procstat *procstat"
  61 .Fa "struct filestat *fst"
  62 .Fa "struct pipestat *pipe"
  63 .Fa "char *errbuf"
  64 .Fc
  65 .Ft int
  66 .Fo procstat_get_pts_info
  67 .Fa "struct procstat *procstat"
  68 .Fa "struct filestat *fst"
  69 .Fa "struct ptsstat *pts"
  70 .Fa "char *errbuf"
  71 .Fc
  72 .Ft int
  73 .Fo procstat_get_socket_info
  74 .Fa "struct procstat *procstat"
  75 .Fa "struct filestat *fst"
  76 .Fa "struct sockstat *sock"
  77 .Fa "char *errbuf"
  78 .Fc
  79 .Ft int
  80 .Fo procstat_get_vnode_info
  81 .Fa "struct procstat *procstat"
  82 .Fa "struct filestat *fst"
  83 .Fa "struct vnstat *vn"
  84 .Fa "char *errbuf"
  85 .Fc
  86 .Ft "struct filestat_list *"
  87 .Fo procstat_getfiles
  88 .Fa "struct procstat *procstat"
  89 .Fa "struct kinfo_proc *kp"
  90 .Fa "int mmapped"
  91 .Fc
  92 .Ft "struct kinfo_proc *"
  93 .Fo procstat_getprocs
  94 .Fa "struct procstat *procstat"
  95 .Fa "int what"
  96 .Fa "int arg"
  97 .Fa "unsigned int *count"
  98 .Fc
  99 .Ft "struct procstat *"
 100 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
 101 .Ft "struct procstat *"
 102 .Fn procstat_open_sysctl void
 103 .Sh DESCRIPTION
 104 The
 105 .Nm libprocstat
 106 library contains the API for runtime file and process information
 107 retrieval from the running kernel via the
 108 .Xr sysctl 3
 109 library backend, and for post-mortem analysis via the
 110 .Xr kvm 3
 111 library backend.
 112 .Pp
 113 The
 114 .Fn procstat_open_kvm
 115 and
 116 .Fn procstat_open_sysctl
 117 functions use the
 118 .Xr kvm 3
 119 or
 120 .Xr sysctl 3
 121 library routines, respectively, to access kernel state information
 122 used to retrieve processes and files states.
 123 The
 124 .Fa nlistf
 125 argument is the executable image of the kernel being examined.
 126 If this argument is
 127 .Dv NULL ,
 128 the currently running kernel is assumed.
 129 The
 130 .Fa memf
 131 argument is the kernel memory device file.
 132 If this argument is
 133 .Dv NULL ,
 134 then
 135 .Pa /dev/mem
 136 is assumed.
 137 See
 138 .Xr kvm_open 3
 139 for more details.
 140 Both functions dynamically allocate and return a
 141 .Vt procstat
 142 structure pointer used in the rest of the
 143 .Nm libprocstat
 144 library routines until the corresponding
 145 .Fn procstat_close
 146 call that cleans up the resources allocated by the
 147 .Fn procstat_open_*
 148 functions.
 149 .Pp
 150 The
 151 .Fn procstat_getprocs
 152 function gets a pointer to the
 153 .Vt procstat
 154 structure from one of the
 155 .Fn procstat_open_*
 156 functions and returns a dynamically allocated (sub-)set of active processes
 157 in the kernel filled in to array of
 158 .Vt kinfo_proc
 159 structures.
 160 The
 161 .Fa what
 162 and
 163 .Fa arg
 164 arguments constitute a filtering predicate as described in the
 165 .Xr kvm_getprocs 3
 166 function.
 167 The number of processes found is returned in the reference parameter
 168 .Fa cnt .
 169 The caller is responsible to free the allocated memory with a subsequent
 170 .Fn procstat_freeprocs
 171 function call.
 172 .Pp
 173 The
 174 .Fn procstat_getfiles
 175 function gets a pointer to the
 176 .Vt procstat
 177 structure initialized with one of the
 178 .Fn procstat_open_*
 179 functions, a pointer to
 180 .Vt kinfo_proc
 181 structure from the array obtained from the
 182 .Fn kvm_getprocs
 183 function, and returns a dynamically allocated linked list of filled in
 184 .Vt filestat_list
 185 structures using the STAILQ macros defined in
 186 .Xr queue 3 .
 187 The caller is responsible to free the allocated memory with a subsequent
 188 .Fn procstat_freefiles
 189 function call.
 190 .Pp
 191 The
 192 .Fn procstat_get_pipe_info ,
 193 .Fn procstat_get_pts_info ,
 194 .Fn procstat_get_socket_info
 195 and
 196 .Fn procstat_get_vnode_info
 197 functions are used to retrive information about pipes, pseudo-terminals,
 198 sockets, and vnodes, respectively.
 199 Each of them have a similar interface API.
 200 The
 201 .Fa procstat
 202 argument is a pointer obtained from one of
 203 .Fn procstat_open_*
 204 functions.
 205 The
 206 .Ft filestat Fa fst
 207 argument is an element of STAILQ linked list as obtained from the
 208 .Fn procstat_getfiles
 209 function.
 210 The
 211 .Ft filestat
 212 structure contains a
 213 .Fa fs_type
 214 field that specifies a file type and a corresponding function to be
 215 called among the
 216 .Nm procstat_get_*_info
 217 function family.
 218 The actual object is returned in the 3rd reference parameter.
 219 The
 220 .Fa errbuf
 221 argument indicates an actual error message in case of failure.
 222 .Pp
 223 .Bl -tag -width 20n -compact -offset indent
 224 .It Li PS_FST_TYPE_FIFO
 225 .Nm procstat_get_vnode_info
 226 .It Li PS_FST_TYPE_VNODE
 227 .Nm procstat_get_vnode_info
 228 .It Li PS_FST_TYPE_SOCKET
 229 .Nm procstat_get_socket_info
 230 .It Li PS_FST_TYPE_PIPE
 231 .Nm procstat_get_pipe_info
 232 .It Li PS_FST_TYPE_PTS
 233 .Nm procstat_get_pts_info
 234 .El
 235 .Sh SEE ALSO
 236 .Xr fstat 1 ,
 237 .Xr fuser 1 ,
 238 .Xr pipe 2 ,
 239 .Xr socket 2 ,
 240 .Xr kvm 3 ,
 241 .Xr queue 3 ,
 242 .Xr sysctl 3 ,
 243 .Xr pts 4 ,
 244 .Xr vnode 9
 245 .Sh HISTORY
 246 The
 247 .Nm libprocstat
 248 library appeared in
 249 .Fx 9.0 .
 250 .Sh AUTHORS
 251 .An -nosplit
 252 The
 253 .Nm libprocstat
 254 library was written by
 255 .An Stanislav Sedov Aq stas@FreeBSD.org .
 256 .Pp
 257 This manual page was written by
 258 .An Sergey Kandaurov Aq pluknet@FreeBSD.org .