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