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_freeadvlock ,
33 .Nm procstat_freeargv ,
34 .Nm procstat_freeauxv ,
35 .Nm procstat_freeenvv ,
36 .Nm procstat_freefiles ,
37 .Nm procstat_freegroups ,
38 .Nm procstat_freekstack ,
39 .Nm procstat_freeprocs ,
40 .Nm procstat_freeptlwpinfo ,
41 .Nm procstat_freevmmap ,
42 .Nm procstat_get_pipe_info ,
43 .Nm procstat_get_pts_info ,
44 .Nm procstat_get_sem_info ,
45 .Nm procstat_get_shm_info ,
46 .Nm procstat_get_socket_info ,
47 .Nm procstat_get_vnode_info ,
48 .Nm procstat_getadvlock ,
49 .Nm procstat_getargv ,
50 .Nm procstat_getauxv ,
51 .Nm procstat_getenvv ,
52 .Nm procstat_getfiles ,
53 .Nm procstat_getgroups ,
54 .Nm procstat_getkstack ,
55 .Nm procstat_getosrel ,
56 .Nm procstat_getpathname ,
57 .Nm procstat_getprocs ,
58 .Nm procstat_getptlwpinfo ,
59 .Nm procstat_getrlimit ,
60 .Nm procstat_getumask ,
61 .Nm procstat_getvmmap ,
62 .Nm procstat_open_core ,
63 .Nm procstat_open_kvm ,
64 .Nm procstat_open_sysctl
65 .Nd library interface for file and process information retrieval
74 .Fn procstat_close "struct procstat *procstat"
76 .Fn procstat_freeadvlock "struct procstat *procstat" "struct advlock_list *list"
79 .Fa "struct procstat *procstat"
83 .Fa "struct procstat *procstat"
84 .Fa "Elf_Auxinfo *auxv"
88 .Fa "struct procstat *procstat"
91 .Fo procstat_freefiles
92 .Fa "struct procstat *procstat"
93 .Fa "struct filestat_list *head"
96 .Fo procstat_freegroups
97 .Fa "struct procstat *procstat"
101 .Fo procstat_freekstack
102 .Fa "struct procstat *procstat"
103 .Fa "struct kinfo_kstack *kkstp"
106 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
108 .Fo procstat_freevmmap
109 .Fa "struct procstat *procstat"
110 .Fa "struct kinfo_vmentry *vmmap"
113 .Fo procstat_freeptlwpinfo
114 .Fa "struct procstat *procstat"
115 .Fa "struct ptrace_lwpinfo *pl"
118 .Fo procstat_get_pipe_info
119 .Fa "struct procstat *procstat"
120 .Fa "struct filestat *fst"
121 .Fa "struct pipestat *pipe"
125 .Fo procstat_get_pts_info
126 .Fa "struct procstat *procstat"
127 .Fa "struct filestat *fst"
128 .Fa "struct ptsstat *pts"
132 .Fo procstat_get_sem_info
133 .Fa "struct procstat *procstat"
134 .Fa "struct filestat *fst"
135 .Fa "struct semstat *sem"
139 .Fo procstat_get_shm_info
140 .Fa "struct procstat *procstat"
141 .Fa "struct filestat *fst"
142 .Fa "struct shmstat *shm"
146 .Fo procstat_get_socket_info
147 .Fa "struct procstat *procstat"
148 .Fa "struct filestat *fst"
149 .Fa "struct sockstat *sock"
153 .Fo procstat_get_vnode_info
154 .Fa "struct procstat *procstat"
155 .Fa "struct filestat *fst"
156 .Fa "struct vnstat *vn"
159 .Ft "struct advlock_list *"
160 .Fo procstat_getadvlock
161 .Fa "struct procstat *procstat"
165 .Fa "struct procstat *procstat"
166 .Fa "const struct kinfo_proc *kp"
171 .Fa "struct procstat *procstat"
172 .Fa "struct kinfo_proc *kp"
173 .Fa "unsigned int *count"
177 .Fa "struct procstat *procstat"
178 .Fa "const struct kinfo_proc *kp"
181 .Ft "struct filestat_list *"
182 .Fo procstat_getfiles
183 .Fa "struct procstat *procstat"
184 .Fa "struct kinfo_proc *kp"
188 .Fo procstat_getgroups
189 .Fa "struct procstat *procstat"
190 .Fa "struct kinfo_proc *kp"
191 .Fa "unsigned int *count"
193 .Ft "struct kinfo_kstack *"
194 .Fo procstat_getkstack
195 .Fa "struct procstat *procstat"
196 .Fa "struct kinfo_proc *kp"
197 .Fa "unsigned int *count"
200 .Fo procstat_getosrel
201 .Fa "struct procstat *procstat"
202 .Fa "struct kinfo_proc *kp"
206 .Fo procstat_getpathname
207 .Fa "struct procstat *procstat"
208 .Fa "struct kinfo_proc *kp"
212 .Ft "struct kinfo_proc *"
213 .Fo procstat_getprocs
214 .Fa "struct procstat *procstat"
217 .Fa "unsigned int *count"
219 .Ft "struct ptrace_lwpinfo *"
220 .Fo procstat_getptlwpinfo
221 .Fa "struct procstat *procstat"
222 .Fa "unsigned int *count"
225 .Fo procstat_getrlimit
226 .Fa "struct procstat *procstat"
227 .Fa "struct kinfo_proc *kp"
229 .Fa "struct rlimit* rlimit"
232 .Fo procstat_getumask
233 .Fa "struct procstat *procstat"
234 .Fa "struct kinfo_proc *kp"
235 .Fa "unsigned short *maskp"
237 .Ft "struct kinfo_vmentry *"
238 .Fo procstat_getvmmap
239 .Fa "struct procstat *procstat"
240 .Fa "struct kinfo_proc *kp"
241 .Fa "unsigned int *count"
243 .Ft "struct procstat *"
244 .Fn procstat_open_core "const char *filename"
245 .Ft "struct procstat *"
246 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
247 .Ft "struct procstat *"
248 .Fn procstat_open_sysctl void
252 library contains the API for runtime file and process information
253 retrieval from the running kernel via the
255 library backend, and for post-mortem analysis via the
257 library backend, or from the process
259 file, searching for statistics in special
264 .Fn procstat_open_kvm
266 .Fn procstat_open_sysctl
271 library routines, respectively, to access kernel state information
272 used to retrieve processes and files states.
274 .Fn procstat_open_core
277 routines to access statistics stored as a set of notes in a process
279 file, written by the kernel at the moment of the process abnormal termination.
282 argument is the process core file name.
285 argument is the executable image of the kernel being examined.
288 the currently running kernel is assumed.
291 argument is the kernel memory device file.
300 The functions dynamically allocate and return a
302 structure pointer used in the rest of the
304 library routines until the corresponding
306 call that cleans up the resources allocated by the
311 .Fn procstat_getprocs
312 function gets a pointer to the
314 structure from one of the
316 functions and returns a dynamically allocated (sub-)set of active processes
317 in the kernel filled in to array of
324 arguments constitute a filtering predicate as described in the
327 The number of processes found is returned in the reference parameter
329 The caller is responsible to free the allocated memory with a subsequent
330 .Fn procstat_freeprocs
334 .Fn procstat_getptlwpinfo
335 function gets a pointer to the
338 .Fn procstat_open_core
339 function and returns a dynamically allocated set of signals intercepted by a
340 process in the process's core file.
341 The number of processes found is returned in the reference parameter
343 The caller is responsible to free the allocated memory with a subsequent
344 .Fn procstat_freeptlwpinfo
349 function gets a pointer to the
351 structure from one of the
353 functions, a pointer to
355 structure from the array obtained from the
356 .Fn procstat_getprocs
357 function, and returns a null-terminated argument vector that corresponds to
358 the command line arguments passed to the process.
361 argument indicates the maximum number of characters, including null bytes,
362 to use in building the strings.
363 If this amount is exceeded, the string causing the overflow is truncated and
364 the partial result is returned.
365 This is handy for programs that print only a one line summary of a
366 command and should not copy out large amounts of text only to ignore it.
369 is zero, no limit is imposed and all argument strings are returned.
370 The values of the returned argument vector refer the strings stored
374 A subsequent call of the function with the same
376 argument will reuse the buffer.
377 To free the allocated memory
378 .Fn procstat_freeargv
379 function call can be used, or it will be released on
384 function is similar to
386 but returns the vector of environment strings.
387 The caller may free the allocated memory with a subsequent
388 .Fn procstat_freeenvv
393 function gets a pointer to the
395 structure, a pointer to
397 structure, and returns the auxiliary vector as a dynamically allocated array of
400 The caller is responsible to free the allocated memory with a subsequent
401 .Fn procstat_freeauxv
405 .Fn procstat_getfiles
406 function gets a pointer to the
408 structure initialized with one of the
410 functions, a pointer to
412 structure from the array obtained from the
413 .Fn procstat_getprocs
414 function, and returns a dynamically allocated linked list of filled in
416 structures using the STAILQ macros defined in
418 The caller is responsible to free the allocated memory with a subsequent
419 .Fn procstat_freefiles
423 .Fn procstat_getgroups
424 function gets a pointer to the
426 structure, a pointer to
428 structure, and returns the process groups as a dynamically allocated array of
431 The caller is responsible to free the allocated memory with a subsequent
432 .Fn procstat_freegroups
436 .Fn procstat_getkstack
437 function gets a pointer to the
439 structure initialized with one of the
441 functions, a pointer to
443 structure, and returns kernel stacks of the process as a dynamically allocated
447 The caller is responsible to free the allocated memory with a subsequent
448 .Fn procstat_freekstack
452 .Fn procstat_getosrel
453 function gets a pointer to the
455 structure, a pointer to
457 structure, and returns osrel date in the 3rd reference parameter.
460 .Fn procstat_getpathname
461 function gets a pointer to the
463 structure, a pointer to
465 structure, and copies the path of the process executable to
472 .Fn procstat_getrlimit
473 function gets a pointer to the
475 structure, a pointer to
477 structure, resource index
479 and returns the actual resource limit in the 4th reference parameter.
482 .Fn procstat_getumask
483 function gets a pointer to the
485 structure, a pointer to
487 structure, and returns the process umask in the 3rd reference parameter.
490 .Fn procstat_getvmmap
491 function gets a pointer to the
493 structure initialized with one of the
495 functions, a pointer to
497 structure, and returns VM layout of the process as a dynamically allocated
501 The caller is responsible to free the allocated memory with a subsequent
502 .Fn procstat_freevmmap
506 .Fn procstat_getadvlock
507 function returns a dynamically allocated list of
509 structures, providing a snapshot of the currently
510 acquired advisory locks in the system.
511 Both locally acquired POSIX (
515 locks are reported, as well as locks established by remote file
517 For each lock, unique identifiers for the locked file and its mount point
518 are guaranteed to be provided.
519 If a path for the locked file can be reconstructed, it is provided as well.
520 The returned list must be freed with the
521 .Fn procstat_freeadvlock
525 .Fn procstat_get_pipe_info ,
526 .Fn procstat_get_pts_info ,
527 .Fn procstat_get_sem_info ,
528 .Fn procstat_get_shm_info ,
529 .Fn procstat_get_socket_info
531 .Fn procstat_get_vnode_info
532 functions are used to retrieve information about pipes, pseudo-terminals,
533 semaphores, shared memory objects,
534 sockets, and vnodes, respectively.
535 Each of them have a similar interface API.
538 argument is a pointer obtained from one of
543 argument is an element of STAILQ linked list as obtained from the
544 .Fn procstat_getfiles
550 field that specifies a file type and a corresponding function to be
552 .Nm procstat_get_*_info
554 The actual object is returned in the 3rd reference parameter.
557 argument indicates an actual error message in case of failure.
559 .Bl -tag -width 20n -compact -offset indent
560 .It Li PS_FST_TYPE_FIFO
561 .Nm procstat_get_vnode_info
562 .It Li PS_FST_TYPE_VNODE
563 .Nm procstat_get_vnode_info
564 .It Li PS_FST_TYPE_SOCKET
565 .Nm procstat_get_socket_info
566 .It Li PS_FST_TYPE_PIPE
567 .Nm procstat_get_pipe_info
568 .It Li PS_FST_TYPE_PTS
569 .Nm procstat_get_pts_info
570 .It Li PS_FST_TYPE_SEM
571 .Nm procstat_get_sem_info
572 .It Li PS_FST_TYPE_SHM
573 .Nm procstat_get_shm_info
598 library was written by
599 .An Stanislav Sedov Aq Mt stas@FreeBSD.org .
601 This manual page was written by
602 .An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org .