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
30 .Nm procstat_freeadvlock ,
31 .Nm procstat_freeargv ,
32 .Nm procstat_freeauxv ,
33 .Nm procstat_freeenvv ,
34 .Nm procstat_freefiles ,
35 .Nm procstat_freegroups ,
36 .Nm procstat_freekstack ,
37 .Nm procstat_freeprocs ,
38 .Nm procstat_freeptlwpinfo ,
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_getadvlock ,
47 .Nm procstat_getargv ,
48 .Nm procstat_getauxv ,
49 .Nm procstat_getenvv ,
50 .Nm procstat_getfiles ,
51 .Nm procstat_getgroups ,
52 .Nm procstat_getkstack ,
53 .Nm procstat_getosrel ,
54 .Nm procstat_getpathname ,
55 .Nm procstat_getprocs ,
56 .Nm procstat_getptlwpinfo ,
57 .Nm procstat_getrlimit ,
58 .Nm procstat_getumask ,
59 .Nm procstat_getvmmap ,
60 .Nm procstat_open_core ,
61 .Nm procstat_open_kvm ,
62 .Nm procstat_open_sysctl
63 .Nd library interface for file and process information retrieval
72 .Fn procstat_close "struct procstat *procstat"
74 .Fn procstat_freeadvlock "struct procstat *procstat" "struct advlock_list *list"
77 .Fa "struct procstat *procstat"
81 .Fa "struct procstat *procstat"
82 .Fa "Elf_Auxinfo *auxv"
86 .Fa "struct procstat *procstat"
89 .Fo procstat_freefiles
90 .Fa "struct procstat *procstat"
91 .Fa "struct filestat_list *head"
94 .Fo procstat_freegroups
95 .Fa "struct procstat *procstat"
99 .Fo procstat_freekstack
100 .Fa "struct procstat *procstat"
101 .Fa "struct kinfo_kstack *kkstp"
104 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
106 .Fo procstat_freevmmap
107 .Fa "struct procstat *procstat"
108 .Fa "struct kinfo_vmentry *vmmap"
111 .Fo procstat_freeptlwpinfo
112 .Fa "struct procstat *procstat"
113 .Fa "struct ptrace_lwpinfo *pl"
116 .Fo procstat_get_pipe_info
117 .Fa "struct procstat *procstat"
118 .Fa "struct filestat *fst"
119 .Fa "struct pipestat *pipe"
123 .Fo procstat_get_pts_info
124 .Fa "struct procstat *procstat"
125 .Fa "struct filestat *fst"
126 .Fa "struct ptsstat *pts"
130 .Fo procstat_get_sem_info
131 .Fa "struct procstat *procstat"
132 .Fa "struct filestat *fst"
133 .Fa "struct semstat *sem"
137 .Fo procstat_get_shm_info
138 .Fa "struct procstat *procstat"
139 .Fa "struct filestat *fst"
140 .Fa "struct shmstat *shm"
144 .Fo procstat_get_socket_info
145 .Fa "struct procstat *procstat"
146 .Fa "struct filestat *fst"
147 .Fa "struct sockstat *sock"
151 .Fo procstat_get_vnode_info
152 .Fa "struct procstat *procstat"
153 .Fa "struct filestat *fst"
154 .Fa "struct vnstat *vn"
157 .Ft "struct advlock_list *"
158 .Fo procstat_getadvlock
159 .Fa "struct procstat *procstat"
163 .Fa "struct procstat *procstat"
164 .Fa "const struct kinfo_proc *kp"
169 .Fa "struct procstat *procstat"
170 .Fa "struct kinfo_proc *kp"
171 .Fa "unsigned int *count"
175 .Fa "struct procstat *procstat"
176 .Fa "const struct kinfo_proc *kp"
179 .Ft "struct filestat_list *"
180 .Fo procstat_getfiles
181 .Fa "struct procstat *procstat"
182 .Fa "struct kinfo_proc *kp"
186 .Fo procstat_getgroups
187 .Fa "struct procstat *procstat"
188 .Fa "struct kinfo_proc *kp"
189 .Fa "unsigned int *count"
191 .Ft "struct kinfo_kstack *"
192 .Fo procstat_getkstack
193 .Fa "struct procstat *procstat"
194 .Fa "struct kinfo_proc *kp"
195 .Fa "unsigned int *count"
198 .Fo procstat_getosrel
199 .Fa "struct procstat *procstat"
200 .Fa "struct kinfo_proc *kp"
204 .Fo procstat_getpathname
205 .Fa "struct procstat *procstat"
206 .Fa "struct kinfo_proc *kp"
210 .Ft "struct kinfo_proc *"
211 .Fo procstat_getprocs
212 .Fa "struct procstat *procstat"
215 .Fa "unsigned int *count"
217 .Ft "struct ptrace_lwpinfo *"
218 .Fo procstat_getptlwpinfo
219 .Fa "struct procstat *procstat"
220 .Fa "unsigned int *count"
223 .Fo procstat_getrlimit
224 .Fa "struct procstat *procstat"
225 .Fa "struct kinfo_proc *kp"
227 .Fa "struct rlimit* rlimit"
230 .Fo procstat_getumask
231 .Fa "struct procstat *procstat"
232 .Fa "struct kinfo_proc *kp"
233 .Fa "unsigned short *maskp"
235 .Ft "struct kinfo_vmentry *"
236 .Fo procstat_getvmmap
237 .Fa "struct procstat *procstat"
238 .Fa "struct kinfo_proc *kp"
239 .Fa "unsigned int *count"
241 .Ft "struct procstat *"
242 .Fn procstat_open_core "const char *filename"
243 .Ft "struct procstat *"
244 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
245 .Ft "struct procstat *"
246 .Fn procstat_open_sysctl void
250 library contains the API for runtime file and process information
251 retrieval from the running kernel via the
253 library backend, and for post-mortem analysis via the
255 library backend, or from the process
257 file, searching for statistics in special
262 .Fn procstat_open_kvm
264 .Fn procstat_open_sysctl
269 library routines, respectively, to access kernel state information
270 used to retrieve processes and files states.
272 .Fn procstat_open_core
275 routines to access statistics stored as a set of notes in a process
277 file, written by the kernel at the moment of the process abnormal termination.
280 argument is the process core file name.
283 argument is the executable image of the kernel being examined.
286 the currently running kernel is assumed.
289 argument is the kernel memory device file.
298 The functions dynamically allocate and return a
300 structure pointer used in the rest of the
302 library routines until the corresponding
304 call that cleans up the resources allocated by the
309 .Fn procstat_getprocs
310 function gets a pointer to the
312 structure from one of the
314 functions and returns a dynamically allocated (sub-)set of active processes
315 in the kernel filled in to array of
322 arguments constitute a filtering predicate as described in the
325 The number of processes found is returned in the reference parameter
327 The caller is responsible to free the allocated memory with a subsequent
328 .Fn procstat_freeprocs
332 .Fn procstat_getptlwpinfo
333 function gets a pointer to the
336 .Fn procstat_open_core
337 function and returns a dynamically allocated set of signals intercepted by a
338 process in the process's core file.
339 The number of processes found is returned in the reference parameter
341 The caller is responsible to free the allocated memory with a subsequent
342 .Fn procstat_freeptlwpinfo
347 function gets a pointer to the
349 structure from one of the
351 functions, a pointer to
353 structure from the array obtained from the
354 .Fn procstat_getprocs
355 function, and returns a null-terminated argument vector that corresponds to
356 the command line arguments passed to the process.
359 argument indicates the maximum number of characters, including null bytes,
360 to use in building the strings.
361 If this amount is exceeded, the string causing the overflow is truncated and
362 the partial result is returned.
363 This is handy for programs that print only a one line summary of a
364 command and should not copy out large amounts of text only to ignore it.
367 is zero, no limit is imposed and all argument strings are returned.
368 The values of the returned argument vector refer the strings stored
372 A subsequent call of the function with the same
374 argument will reuse the buffer.
375 To free the allocated memory
376 .Fn procstat_freeargv
377 function call can be used, or it will be released on
382 function is similar to
384 but returns the vector of environment strings.
385 The caller may free the allocated memory with a subsequent
386 .Fn procstat_freeenvv
391 function gets a pointer to the
393 structure, a pointer to
395 structure, and returns the auxiliary vector as a dynamically allocated array of
398 The caller is responsible to free the allocated memory with a subsequent
399 .Fn procstat_freeauxv
403 .Fn procstat_getfiles
404 function gets a pointer to the
406 structure initialized with one of the
408 functions, a pointer to
410 structure from the array obtained from the
411 .Fn procstat_getprocs
412 function, and returns a dynamically allocated linked list of filled in
414 structures using the STAILQ macros defined in
416 The caller is responsible to free the allocated memory with a subsequent
417 .Fn procstat_freefiles
421 .Fn procstat_getgroups
422 function gets a pointer to the
424 structure, a pointer to
426 structure, and returns the process groups as a dynamically allocated array of
429 The caller is responsible to free the allocated memory with a subsequent
430 .Fn procstat_freegroups
434 .Fn procstat_getkstack
435 function gets a pointer to the
437 structure initialized with one of the
439 functions, a pointer to
441 structure, and returns kernel stacks of the process as a dynamically allocated
445 The caller is responsible to free the allocated memory with a subsequent
446 .Fn procstat_freekstack
450 .Fn procstat_getosrel
451 function gets a pointer to the
453 structure, a pointer to
455 structure, and returns osrel date in the 3rd reference parameter.
458 .Fn procstat_getpathname
459 function gets a pointer to the
461 structure, a pointer to
463 structure, and copies the path of the process executable to
470 .Fn procstat_getrlimit
471 function gets a pointer to the
473 structure, a pointer to
475 structure, resource index
477 and returns the actual resource limit in the 4th reference parameter.
480 .Fn procstat_getumask
481 function gets a pointer to the
483 structure, a pointer to
485 structure, and returns the process umask in the 3rd reference parameter.
488 .Fn procstat_getvmmap
489 function gets a pointer to the
491 structure initialized with one of the
493 functions, a pointer to
495 structure, and returns VM layout of the process as a dynamically allocated
499 The caller is responsible to free the allocated memory with a subsequent
500 .Fn procstat_freevmmap
504 .Fn procstat_getadvlock
505 function returns a dynamically allocated list of
507 structures, providing a snapshot of the currently
508 acquired advisory locks in the system.
509 Both locally acquired POSIX (
513 locks are reported, as well as locks established by remote file
515 For each lock, unique identifiers for the locked file and its mount point
516 are guaranteed to be provided.
517 If a path for the locked file can be reconstructed, it is provided as well.
518 The returned list must be freed with the
519 .Fn procstat_freeadvlock
523 .Fn procstat_get_pipe_info ,
524 .Fn procstat_get_pts_info ,
525 .Fn procstat_get_sem_info ,
526 .Fn procstat_get_shm_info ,
527 .Fn procstat_get_socket_info
529 .Fn procstat_get_vnode_info
530 functions are used to retrieve information about pipes, pseudo-terminals,
531 semaphores, shared memory objects,
532 sockets, and vnodes, respectively.
533 Each of them have a similar interface API.
536 argument is a pointer obtained from one of
541 argument is an element of STAILQ linked list as obtained from the
542 .Fn procstat_getfiles
548 field that specifies a file type and a corresponding function to be
550 .Nm procstat_get_*_info
552 The actual object is returned in the 3rd reference parameter.
555 argument indicates an actual error message in case of failure.
557 .Bl -tag -width 20n -compact -offset indent
558 .It Li PS_FST_TYPE_FIFO
559 .Nm procstat_get_vnode_info
560 .It Li PS_FST_TYPE_VNODE
561 .Nm procstat_get_vnode_info
562 .It Li PS_FST_TYPE_SOCKET
563 .Nm procstat_get_socket_info
564 .It Li PS_FST_TYPE_PIPE
565 .Nm procstat_get_pipe_info
566 .It Li PS_FST_TYPE_PTS
567 .Nm procstat_get_pts_info
568 .It Li PS_FST_TYPE_SEM
569 .Nm procstat_get_sem_info
570 .It Li PS_FST_TYPE_SHM
571 .Nm procstat_get_shm_info
596 library was written by
597 .An Stanislav Sedov Aq Mt stas@FreeBSD.org .
599 This manual page was written by
600 .An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org .