1 .\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nm procstat_freeargv ,
33 .Nm procstat_freeauxv ,
34 .Nm procstat_freeenvv ,
35 .Nm procstat_freefiles ,
36 .Nm procstat_freegroups ,
37 .Nm procstat_freekstack ,
38 .Nm procstat_freeprocs ,
39 .Nm procstat_freevmmap ,
40 .Nm procstat_get_pipe_info ,
41 .Nm procstat_get_pts_info ,
42 .Nm procstat_get_sem_info ,
43 .Nm procstat_get_shm_info ,
44 .Nm procstat_get_socket_info ,
45 .Nm procstat_get_vnode_info ,
46 .Nm procstat_getargv ,
47 .Nm procstat_getauxv ,
48 .Nm procstat_getenvv ,
49 .Nm procstat_getfiles ,
50 .Nm procstat_getgroups ,
51 .Nm procstat_getkstack ,
52 .Nm procstat_getosrel ,
53 .Nm procstat_getpathname ,
54 .Nm procstat_getprocs ,
55 .Nm procstat_getrlimit ,
56 .Nm procstat_getumask ,
57 .Nm procstat_getvmmap ,
58 .Nm procstat_open_core ,
59 .Nm procstat_open_kvm ,
60 .Nm procstat_open_sysctl
61 .Nd library interface for file and process information retrieval
69 .Fn procstat_close "struct procstat *procstat"
72 .Fa "struct procstat *procstat"
76 .Fa "struct procstat *procstat"
77 .Fa "Elf_Auxinfo *auxv"
81 .Fa "struct procstat *procstat"
84 .Fo procstat_freefiles
85 .Fa "struct procstat *procstat"
86 .Fa "struct filestat_list *head"
89 .Fo procstat_freegroups
90 .Fa "struct procstat *procstat"
94 .Fo procstat_freekstack
95 .Fa "struct procstat *procstat"
96 .Fa "struct kinfo_kstack *kkstp"
99 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
101 .Fo procstat_freevmmap
102 .Fa "struct procstat *procstat"
103 .Fa "struct kinfo_vmentry *vmmap"
106 .Fo procstat_get_pipe_info
107 .Fa "struct procstat *procstat"
108 .Fa "struct filestat *fst"
109 .Fa "struct pipestat *pipe"
113 .Fo procstat_get_pts_info
114 .Fa "struct procstat *procstat"
115 .Fa "struct filestat *fst"
116 .Fa "struct ptsstat *pts"
120 .Fo procstat_get_sem_info
121 .Fa "struct procstat *procstat"
122 .Fa "struct filestat *fst"
123 .Fa "struct semstat *sem"
127 .Fo procstat_get_shm_info
128 .Fa "struct procstat *procstat"
129 .Fa "struct filestat *fst"
130 .Fa "struct shmstat *shm"
134 .Fo procstat_get_socket_info
135 .Fa "struct procstat *procstat"
136 .Fa "struct filestat *fst"
137 .Fa "struct sockstat *sock"
141 .Fo procstat_get_vnode_info
142 .Fa "struct procstat *procstat"
143 .Fa "struct filestat *fst"
144 .Fa "struct vnstat *vn"
149 .Fa "struct procstat *procstat"
150 .Fa "const struct kinfo_proc *kp"
156 .Fa "struct procstat *procstat"
157 .Fa "struct kinfo_proc *kp"
158 .Fa "unsigned int *count"
162 .Fa "struct procstat *procstat"
163 .Fa "const struct kinfo_proc *kp"
167 .Ft "struct filestat_list *"
168 .Fo procstat_getfiles
169 .Fa "struct procstat *procstat"
170 .Fa "struct kinfo_proc *kp"
174 .Fo procstat_getgroups
175 .Fa "struct procstat *procstat"
176 .Fa "struct kinfo_proc *kp"
177 .Fa "unsigned int *count"
179 .Ft "struct kinfo_kstack *"
180 .Fo procstat_getkstack
181 .Fa "struct procstat *procstat"
182 .Fa "struct kinfo_proc *kp"
183 .Fa "unsigned int *count"
186 .Fo procstat_getosrel
187 .Fa "struct procstat *procstat"
188 .Fa "struct kinfo_proc *kp"
192 .Fo procstat_getpathname
193 .Fa "struct procstat *procstat"
194 .Fa "struct kinfo_proc *kp"
198 .Ft "struct kinfo_proc *"
199 .Fo procstat_getprocs
200 .Fa "struct procstat *procstat"
203 .Fa "unsigned int *count"
206 .Fo procstat_getrlimit
207 .Fa "struct procstat *procstat"
208 .Fa "struct kinfo_proc *kp"
210 .Fa "struct rlimit* rlimit"
213 .Fo procstat_getumask
214 .Fa "struct procstat *procstat"
215 .Fa "struct kinfo_proc *kp"
216 .Fa "unsigned short *maskp"
218 .Ft "struct kinfo_vmentry *"
219 .Fo procstat_getvmmap
220 .Fa "struct procstat *procstat"
221 .Fa "struct kinfo_proc *kp"
222 .Fa "unsigned int *count"
224 .Ft "struct procstat *"
225 .Fn procstat_open_core "const char *filename"
226 .Ft "struct procstat *"
227 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
228 .Ft "struct procstat *"
229 .Fn procstat_open_sysctl void
233 library contains the API for runtime file and process information
234 retrieval from the running kernel via the
236 library backend, and for post-mortem analysis via the
238 library backend, or from the process
240 file, searching for statistics in special
245 .Fn procstat_open_kvm
247 .Fn procstat_open_sysctl
252 library routines, respectively, to access kernel state information
253 used to retrieve processes and files states.
255 .Fn procstat_open_core
258 routines to access statistics stored as a set of notes in a process
260 file, written by the kernel at the moment of the process abnormal termination.
263 argument is the process core file name.
266 argument is the executable image of the kernel being examined.
269 the currently running kernel is assumed.
272 argument is the kernel memory device file.
281 The functions dynamically allocate and return a
283 structure pointer used in the rest of the
285 library routines until the corresponding
287 call that cleans up the resources allocated by the
292 .Fn procstat_getprocs
293 function gets a pointer to the
295 structure from one of the
297 functions and returns a dynamically allocated (sub-)set of active processes
298 in the kernel filled in to array of
305 arguments constitute a filtering predicate as described in the
308 The number of processes found is returned in the reference parameter
310 The caller is responsible to free the allocated memory with a subsequent
311 .Fn procstat_freeprocs
316 function gets a pointer to the
318 structure from one of the
320 functions, a pointer to
322 structure from the array obtained from the
324 function, and returns a null-terminated argument vector that corresponds to
325 the command line arguments passed to the process.
328 argument indicates the maximum number of characters, including null bytes,
329 to use in building the strings.
330 If this amount is exceeded, the string causing the overflow is truncated and
331 the partial result is returned.
332 This is handy for programs that print only a one line summary of a
333 command and should not copy out large amounts of text only to ignore it.
336 is zero, no limit is imposed and all argument strings are returned.
337 The values of the returned argument vector refer the strings stored
341 A subsequent call of the function with the same
343 argument will reuse the buffer.
344 To free the allocated memory
345 .Fn procstat_freeargv
346 function call can be used, or it will be released on
351 function is similar to
353 but returns the vector of environment strings.
354 The caller may free the allocated memory with a subsequent
360 function gets a pointer to the
362 structure, a pointer to
364 structure, and returns the auxiliary vector as a dynamically allocated array of
367 The caller is responsible to free the allocated memory with a subsequent
368 .Fn procstat_freeauxv
372 .Fn procstat_getfiles
373 function gets a pointer to the
375 structure initialized with one of the
377 functions, a pointer to
379 structure from the array obtained from the
381 function, and returns a dynamically allocated linked list of filled in
383 structures using the STAILQ macros defined in
385 The caller is responsible to free the allocated memory with a subsequent
386 .Fn procstat_freefiles
390 .Fn procstat_getgroups
391 function gets a pointer to the
393 structure, a pointer to
395 structure, and returns the process groups as a dynamically allocated array of
398 The caller is responsible to free the allocated memory with a subsequent
399 .Fn procstat_freegroups
403 .Fn procstat_getkstack
404 function gets a pointer to the
406 structure initialized with one of the
408 functions, a pointer to
410 structure, and returns kernel stacks of the process as a dynamically allocated
414 The caller is responsible to free the allocated memory with a subsequent
415 .Fn procstat_freekstack
419 .Fn procstat_getosrel
420 function gets a pointer to the
422 structure, a pointer to
424 structure, and returns osrel date in the 3rd reference parameter.
427 .Fn procstat_getpathname
428 function gets a pointer to the
430 structure, a pointer to
432 structure, and copies the path of the process executable to
439 .Fn procstat_getrlimit
440 function gets a pointer to the
442 structure, a pointer to
444 structure, resource index
446 and returns the actual resource limit in the 4th reference parameter.
449 .Fn procstat_getumask
450 function gets a pointer to the
452 structure, a pointer to
454 structure, and returns the process umask in the 3rd reference parameter.
457 .Fn procstat_getvmmap
458 function gets a pointer to the
460 structure initialized with one of the
462 functions, a pointer to
464 structure, and returns VM layout of the process as a dynamically allocated
468 The caller is responsible to free the allocated memory with a subsequent
469 .Fn procstat_freevmmap
473 .Fn procstat_get_pipe_info ,
474 .Fn procstat_get_pts_info ,
475 .Fn procstat_get_sem_info ,
476 .Fn procstat_get_shm_info ,
477 .Fn procstat_get_socket_info
479 .Fn procstat_get_vnode_info
480 functions are used to retrieve information about pipes, pseudo-terminals,
481 semaphores, shared memory objects,
482 sockets, and vnodes, respectively.
483 Each of them have a similar interface API.
486 argument is a pointer obtained from one of
491 argument is an element of STAILQ linked list as obtained from the
492 .Fn procstat_getfiles
498 field that specifies a file type and a corresponding function to be
500 .Nm procstat_get_*_info
502 The actual object is returned in the 3rd reference parameter.
505 argument indicates an actual error message in case of failure.
507 .Bl -tag -width 20n -compact -offset indent
508 .It Li PS_FST_TYPE_FIFO
509 .Nm procstat_get_vnode_info
510 .It Li PS_FST_TYPE_VNODE
511 .Nm procstat_get_vnode_info
512 .It Li PS_FST_TYPE_SOCKET
513 .Nm procstat_get_socket_info
514 .It Li PS_FST_TYPE_PIPE
515 .Nm procstat_get_pipe_info
516 .It Li PS_FST_TYPE_PTS
517 .Nm procstat_get_pts_info
518 .It Li PS_FST_TYPE_SEM
519 .Nm procstat_get_sem_info
520 .It Li PS_FST_TYPE_SHM
521 .Nm procstat_get_shm_info
546 library was written by
547 .An Stanislav Sedov Aq Mt stas@FreeBSD.org .
549 This manual page was written by
550 .An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org .