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
31 .Nm procstat_open_core ,
32 .Nm procstat_open_kvm ,
33 .Nm procstat_open_sysctl ,
35 .Nm procstat_getargv ,
36 .Nm procstat_getauxv ,
37 .Nm procstat_getenvv ,
38 .Nm procstat_getfiles ,
39 .Nm procstat_getgroups ,
40 .Nm procstat_getkstack ,
41 .Nm procstat_getosrel ,
42 .Nm procstat_getpathname ,
43 .Nm procstat_getprocs ,
44 .Nm procstat_getumask ,
45 .Nm procstat_getvmmap ,
46 .Nm procstat_freeargv ,
47 .Nm procstat_freeauxv ,
48 .Nm procstat_freeenvv ,
49 .Nm procstat_freefiles ,
50 .Nm procstat_freegroups ,
51 .Nm procstat_freekstack ,
52 .Nm procstat_freeprocs ,
53 .Nm procstat_freevmmap ,
54 .Nm procstat_get_pipe_info ,
55 .Nm procstat_get_pts_info ,
56 .Nm procstat_get_sem_info ,
57 .Nm procstat_get_shm_info ,
58 .Nm procstat_get_socket_info ,
59 .Nm procstat_get_vnode_info
60 .Nd library interface for file and process information retrieval
68 .Fn procstat_close "struct procstat *procstat"
71 .Fa "struct procstat *procstat"
75 .Fa "struct procstat *procstat"
76 .Fa "Elf_Auxinfo *auxv"
80 .Fa "struct procstat *procstat"
83 .Fo procstat_freefiles
84 .Fa "struct procstat *procstat"
85 .Fa "struct filestat_list *head"
88 .Fo procstat_freegroups
89 .Fa "struct procstat *procstat"
93 .Fo procstat_freekstack
94 .Fa "struct procstat *procstat"
95 .Fa "struct kinfo_kstack *kkstp"
98 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
100 .Fo procstat_freevmmap
101 .Fa "struct procstat *procstat"
102 .Fa "struct kinfo_vmentry *vmmap"
105 .Fo procstat_get_pipe_info
106 .Fa "struct procstat *procstat"
107 .Fa "struct filestat *fst"
108 .Fa "struct pipestat *pipe"
112 .Fo procstat_get_pts_info
113 .Fa "struct procstat *procstat"
114 .Fa "struct filestat *fst"
115 .Fa "struct ptsstat *pts"
119 .Fo procstat_get_sem_info
120 .Fa "struct procstat *procstat"
121 .Fa "struct filestat *fst"
122 .Fa "struct semstat *sem"
126 .Fo procstat_get_shm_info
127 .Fa "struct procstat *procstat"
128 .Fa "struct filestat *fst"
129 .Fa "struct shmstat *shm"
133 .Fo procstat_get_socket_info
134 .Fa "struct procstat *procstat"
135 .Fa "struct filestat *fst"
136 .Fa "struct sockstat *sock"
140 .Fo procstat_get_vnode_info
141 .Fa "struct procstat *procstat"
142 .Fa "struct filestat *fst"
143 .Fa "struct vnstat *vn"
148 .Fa "struct procstat *procstat"
149 .Fa "const struct kinfo_proc *kp"
155 .Fa "struct procstat *procstat"
156 .Fa "struct kinfo_proc *kp"
157 .Fa "unsigned int *count"
161 .Fa "struct procstat *procstat"
162 .Fa "const struct kinfo_proc *kp"
166 .Ft "struct filestat_list *"
167 .Fo procstat_getfiles
168 .Fa "struct procstat *procstat"
169 .Fa "struct kinfo_proc *kp"
173 .Fo procstat_getgroups
174 .Fa "struct procstat *procstat"
175 .Fa "struct kinfo_proc *kp"
176 .Fa "unsigned int *count"
179 .Fo procstat_getosrel
180 .Fa "struct procstat *procstat"
181 .Fa "struct kinfo_proc *kp"
184 .Ft "struct kinfo_kstack *"
185 .Fo procstat_getkstack
186 .Fa "struct procstat *procstat"
187 .Fa "struct kinfo_proc *kp"
188 .Fa "unsigned int *count"
190 .Ft "struct kinfo_proc *"
191 .Fo procstat_getprocs
192 .Fa "struct procstat *procstat"
195 .Fa "unsigned int *count"
198 .Fo procstat_getpathname
199 .Fa "struct procstat *procstat"
200 .Fa "struct kinfo_proc *kp"
205 .Fo procstat_getrlimit
206 .Fa "struct procstat *procstat"
207 .Fa "struct kinfo_proc *kp"
209 .Fa "struct rlimit* rlimit"
212 .Fo procstat_getumask
213 .Fa "struct procstat *procstat"
214 .Fa "struct kinfo_proc *kp"
215 .Fa "unsigned short *maskp"
217 .Ft "struct kinfo_vmentry *"
218 .Fo procstat_getvmmap
219 .Fa "struct procstat *procstat"
220 .Fa "struct kinfo_proc *kp"
221 .Fa "unsigned int *count"
223 .Ft "struct procstat *"
224 .Fn procstat_open_core "const char *filename"
225 .Ft "struct procstat *"
226 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
227 .Ft "struct procstat *"
228 .Fn procstat_open_sysctl void
232 library contains the API for runtime file and process information
233 retrieval from the running kernel via the
235 library backend, and for post-mortem analysis via the
237 library backend, or from the process
239 file, searching for statistics in special
244 .Fn procstat_open_kvm
246 .Fn procstat_open_sysctl
251 library routines, respectively, to access kernel state information
252 used to retrieve processes and files states.
254 .Fn procstat_open_core
257 routines to access statistics stored as a set of notes in a process
259 file, written by the kernel at the moment of the process abnormal termination.
262 argument is the process core file name.
265 argument is the executable image of the kernel being examined.
268 the currently running kernel is assumed.
271 argument is the kernel memory device file.
280 The functions dynamically allocate and return a
282 structure pointer used in the rest of the
284 library routines until the corresponding
286 call that cleans up the resources allocated by the
291 .Fn procstat_getprocs
292 function gets a pointer to the
294 structure from one of the
296 functions and returns a dynamically allocated (sub-)set of active processes
297 in the kernel filled in to array of
304 arguments constitute a filtering predicate as described in the
307 The number of processes found is returned in the reference parameter
309 The caller is responsible to free the allocated memory with a subsequent
310 .Fn procstat_freeprocs
315 function gets a pointer to the
317 structure from one of the
319 functions, a pointer to
321 structure from the array obtained from the
323 function, and returns a null-terminated argument vector that corresponds to
324 the command line arguments passed to the process.
327 argument indicates the maximum number of characters, including null bytes,
328 to use in building the strings.
329 If this amount is exceeded, the string causing the overflow is truncated and
330 the partial result is returned.
331 This is handy for programs that print only a one line summary of a
332 command and should not copy out large amounts of text only to ignore it.
335 is zero, no limit is imposed and all argument strings are returned.
336 The values of the returned argument vector refer the strings stored
340 A subsequent call of the function with the same
342 argument will reuse the buffer.
343 To free the allocated memory
344 .Fn procstat_freeargv
345 function call can be used, or it will be released on
350 function is similar to
352 but returns the vector of environment strings.
353 The caller may free the allocated memory with a subsequent
359 function gets a pointer to the
361 structure, a pointer to
363 structure, and returns the auxiliary vector as a dynamically allocated array of
366 The caller is responsible to free the allocated memory with a subsequent
367 .Fn procstat_freeauxv
371 .Fn procstat_getfiles
372 function gets a pointer to the
374 structure initialized with one of the
376 functions, a pointer to
378 structure from the array obtained from the
380 function, and returns a dynamically allocated linked list of filled in
382 structures using the STAILQ macros defined in
384 The caller is responsible to free the allocated memory with a subsequent
385 .Fn procstat_freefiles
389 .Fn procstat_getgroups
390 function gets a pointer to the
392 structure, a pointer to
394 structure, and returns the process groups as a dynamically allocated array of
397 The caller is responsible to free the allocated memory with a subsequent
398 .Fn procstat_freegroups
402 .Fn procstat_getkstack
403 function gets a pointer to the
405 structure initialized with one of the
407 functions, a pointer to
409 structure, and returns kernel stacks of the process as a dynamically allocated
413 The caller is responsible to free the allocated memory with a subsequent
414 .Fn procstat_freekstack
418 .Fn procstat_getosrel
419 function gets a pointer to the
421 structure, a pointer to
423 structure, and returns osrel date in the 3rd reference parameter.
426 .Fn procstat_getpathname
427 function gets a pointer to the
429 structure, a pointer to
431 structure, and copies the path of the process executable to
438 .Fn procstat_getrlimit
439 function gets a pointer to the
441 structure, a pointer to
443 structure, resource index
445 and returns the actual resource limit in the 4th reference parameter.
448 .Fn procstat_getumask
449 function gets a pointer to the
451 structure, a pointer to
453 structure, and returns the process umask in the 3rd reference parameter.
456 .Fn procstat_getvmmap
457 function gets a pointer to the
459 structure initialized with one of the
461 functions, a pointer to
463 structure, and returns VM layout of the process as a dynamically allocated
467 The caller is responsible to free the allocated memory with a subsequent
468 .Fn procstat_freevmmap
472 .Fn procstat_get_pipe_info ,
473 .Fn procstat_get_pts_info ,
474 .Fn procstat_get_sem_info ,
475 .Fn procstat_get_shm_info ,
476 .Fn procstat_get_socket_info
478 .Fn procstat_get_vnode_info
479 functions are used to retrieve information about pipes, pseudo-terminals,
480 semaphores, shared memory objects,
481 sockets, and vnodes, respectively.
482 Each of them have a similar interface API.
485 argument is a pointer obtained from one of
490 argument is an element of STAILQ linked list as obtained from the
491 .Fn procstat_getfiles
497 field that specifies a file type and a corresponding function to be
499 .Nm procstat_get_*_info
501 The actual object is returned in the 3rd reference parameter.
504 argument indicates an actual error message in case of failure.
506 .Bl -tag -width 20n -compact -offset indent
507 .It Li PS_FST_TYPE_FIFO
508 .Nm procstat_get_vnode_info
509 .It Li PS_FST_TYPE_VNODE
510 .Nm procstat_get_vnode_info
511 .It Li PS_FST_TYPE_SOCKET
512 .Nm procstat_get_socket_info
513 .It Li PS_FST_TYPE_PIPE
514 .Nm procstat_get_pipe_info
515 .It Li PS_FST_TYPE_PTS
516 .Nm procstat_get_pts_info
517 .It Li PS_FST_TYPE_SEM
518 .Nm procstat_get_sem_info
519 .It Li PS_FST_TYPE_SHM
520 .Nm procstat_get_shm_info
545 library was written by
546 .An Stanislav Sedov Aq stas@FreeBSD.org .
548 This manual page was written by
549 .An Sergey Kandaurov Aq pluknet@FreeBSD.org .