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: head/lib/libprocstat/libprocstat.3 235286 2012-05-11 20:06:46Z gjb $
|
25.\" $FreeBSD: head/lib/libprocstat/libprocstat.3 249666 2013-04-20 07:47:26Z trociny $ |
26.\" 27.Dd April 1, 2012 28.Dt LIBPROCSTAT 3 29.Os 30.Sh NAME
|
31.Nm procstat_open_core , |
32.Nm procstat_open_kvm , 33.Nm procstat_open_sysctl , 34.Nm procstat_close , 35.Nm procstat_getfiles , 36.Nm procstat_getprocs , 37.Nm procstat_freefiles , 38.Nm procstat_freeprocs , 39.Nm procstat_get_pipe_info , 40.Nm procstat_get_pts_info , 41.Nm procstat_get_shm_info , 42.Nm procstat_get_socket_info , 43.Nm procstat_get_vnode_info 44.Nd library interface for file and process information retrieval 45.Sh LIBRARY 46.Lb libprocstat 47.Sh SYNOPSIS 48.In sys/param.h 49.In sys/queue.h 50.In libprocstat.h 51.Ft void 52.Fn procstat_close "struct procstat *procstat" 53.Ft void 54.Fo procstat_freefiles 55.Fa "struct procstat *procstat" 56.Fa "struct filestat_list *head" 57.Fc 58.Ft void 59.Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p" 60.Ft int 61.Fo procstat_get_pipe_info 62.Fa "struct procstat *procstat" 63.Fa "struct filestat *fst" 64.Fa "struct pipestat *pipe" 65.Fa "char *errbuf" 66.Fc 67.Ft int 68.Fo procstat_get_pts_info 69.Fa "struct procstat *procstat" 70.Fa "struct filestat *fst" 71.Fa "struct ptsstat *pts" 72.Fa "char *errbuf" 73.Fc 74.Ft int 75.Fo procstat_get_shm_info 76.Fa "struct procstat *procstat" 77.Fa "struct filestat *fst" 78.Fa "struct shmstat *shm" 79.Fa "char *errbuf" 80.Fc 81.Ft int 82.Fo procstat_get_socket_info 83.Fa "struct procstat *procstat" 84.Fa "struct filestat *fst" 85.Fa "struct sockstat *sock" 86.Fa "char *errbuf" 87.Fc 88.Ft int 89.Fo procstat_get_vnode_info 90.Fa "struct procstat *procstat" 91.Fa "struct filestat *fst" 92.Fa "struct vnstat *vn" 93.Fa "char *errbuf" 94.Fc 95.Ft "struct filestat_list *" 96.Fo procstat_getfiles 97.Fa "struct procstat *procstat" 98.Fa "struct kinfo_proc *kp" 99.Fa "int mmapped" 100.Fc 101.Ft "struct kinfo_proc *" 102.Fo procstat_getprocs 103.Fa "struct procstat *procstat" 104.Fa "int what" 105.Fa "int arg" 106.Fa "unsigned int *count" 107.Fc 108.Ft "struct procstat *"
|
109.Fn procstat_open_core "const char *filename" 110.Ft "struct procstat *" |
111.Fn procstat_open_kvm "const char *nlistf" "const char *memf" 112.Ft "struct procstat *" 113.Fn procstat_open_sysctl void 114.Sh DESCRIPTION 115The 116.Nm libprocstat 117library contains the API for runtime file and process information 118retrieval from the running kernel via the 119.Xr sysctl 3 120library backend, and for post-mortem analysis via the 121.Xr kvm 3
|
119library backend.
|
122library backend, or from the process 123.Xr core 5 124file, searching for statistics in special 125.Xr elf 3 126note sections. |
127.Pp 128The 129.Fn procstat_open_kvm 130and 131.Fn procstat_open_sysctl 132functions use the 133.Xr kvm 3 134or 135.Xr sysctl 3 136library routines, respectively, to access kernel state information 137used to retrieve processes and files states. 138The
|
139.Fn procstat_open_core 140uses 141.Xr elf 3 142routines to access statistics stored as a set of notes in a process 143.Xr core 5 144file, written by the kernel at the moment of the process abnormal termination. 145The 146.Fa filename 147argument is the process core file name. 148The |
149.Fa nlistf 150argument is the executable image of the kernel being examined. 151If this argument is 152.Dv NULL , 153the currently running kernel is assumed. 154The 155.Fa memf 156argument is the kernel memory device file. 157If this argument is 158.Dv NULL , 159then 160.Pa /dev/mem 161is assumed. 162See 163.Xr kvm_open 3 164for more details.
|
148Both functions dynamically allocate and return a
|
165The functions dynamically allocate and return a |
166.Vt procstat 167structure pointer used in the rest of the 168.Nm libprocstat 169library routines until the corresponding 170.Fn procstat_close 171call that cleans up the resources allocated by the 172.Fn procstat_open_* 173functions. 174.Pp 175The 176.Fn procstat_getprocs 177function gets a pointer to the 178.Vt procstat 179structure from one of the 180.Fn procstat_open_* 181functions and returns a dynamically allocated (sub-)set of active processes 182in the kernel filled in to array of 183.Vt kinfo_proc 184structures. 185The 186.Fa what 187and 188.Fa arg 189arguments constitute a filtering predicate as described in the 190.Xr kvm_getprocs 3 191function. 192The number of processes found is returned in the reference parameter 193.Fa cnt . 194The caller is responsible to free the allocated memory with a subsequent 195.Fn procstat_freeprocs 196function call. 197.Pp 198The 199.Fn procstat_getfiles 200function gets a pointer to the 201.Vt procstat 202structure initialized with one of the 203.Fn procstat_open_* 204functions, a pointer to 205.Vt kinfo_proc 206structure from the array obtained from the 207.Fn kvm_getprocs 208function, and returns a dynamically allocated linked list of filled in 209.Vt filestat_list 210structures using the STAILQ macros defined in 211.Xr queue 3 . 212The caller is responsible to free the allocated memory with a subsequent 213.Fn procstat_freefiles 214function call. 215.Pp 216The 217.Fn procstat_get_pipe_info , 218.Fn procstat_get_pts_info , 219.Fn procstat_get_shm_info , 220.Fn procstat_get_socket_info 221and 222.Fn procstat_get_vnode_info 223functions are used to retrieve information about pipes, pseudo-terminals, 224shared memory objects, 225sockets, and vnodes, respectively. 226Each of them have a similar interface API. 227The 228.Fa procstat 229argument is a pointer obtained from one of 230.Fn procstat_open_* 231functions. 232The 233.Ft filestat Fa fst 234argument is an element of STAILQ linked list as obtained from the 235.Fn procstat_getfiles 236function. 237The 238.Ft filestat 239structure contains a 240.Fa fs_type 241field that specifies a file type and a corresponding function to be 242called among the 243.Nm procstat_get_*_info 244function family. 245The actual object is returned in the 3rd reference parameter. 246The 247.Fa errbuf 248argument indicates an actual error message in case of failure. 249.Pp 250.Bl -tag -width 20n -compact -offset indent 251.It Li PS_FST_TYPE_FIFO 252.Nm procstat_get_vnode_info 253.It Li PS_FST_TYPE_VNODE 254.Nm procstat_get_vnode_info 255.It Li PS_FST_TYPE_SOCKET 256.Nm procstat_get_socket_info 257.It Li PS_FST_TYPE_PIPE 258.Nm procstat_get_pipe_info 259.It Li PS_FST_TYPE_PTS 260.Nm procstat_get_pts_info 261.It Li PS_FST_TYPE_SHM 262.Nm procstat_get_shm_info 263.El 264.Sh SEE ALSO 265.Xr fstat 1 , 266.Xr fuser 1 , 267.Xr pipe 2 , 268.Xr shm_open 2 , 269.Xr socket 2 ,
|
270.Xr elf 3 , |
271.Xr kvm 3 , 272.Xr queue 3 , 273.Xr sysctl 3 , 274.Xr pts 4 ,
|
275.Xr core 5 , |
276.Xr vnode 9 277.Sh HISTORY 278The 279.Nm libprocstat 280library appeared in 281.Fx 9.0 . 282.Sh AUTHORS 283.An -nosplit 284The 285.Nm libprocstat 286library was written by 287.An Stanislav Sedov Aq stas@FreeBSD.org . 288.Pp 289This manual page was written by 290.An Sergey Kandaurov Aq pluknet@FreeBSD.org .
|