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_freeptlwpinfo ,
40 .Nm procstat_freevmmap ,
41 .Nm procstat_get_pipe_info ,
42 .Nm procstat_get_pts_info ,
43 .Nm procstat_get_sem_info ,
44 .Nm procstat_get_shm_info ,
45 .Nm procstat_get_socket_info ,
46 .Nm procstat_get_vnode_info ,
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"
75 .Fa "struct procstat *procstat"
79 .Fa "struct procstat *procstat"
80 .Fa "Elf_Auxinfo *auxv"
84 .Fa "struct procstat *procstat"
87 .Fo procstat_freefiles
88 .Fa "struct procstat *procstat"
89 .Fa "struct filestat_list *head"
92 .Fo procstat_freegroups
93 .Fa "struct procstat *procstat"
97 .Fo procstat_freekstack
98 .Fa "struct procstat *procstat"
99 .Fa "struct kinfo_kstack *kkstp"
102 .Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
104 .Fo procstat_freevmmap
105 .Fa "struct procstat *procstat"
106 .Fa "struct kinfo_vmentry *vmmap"
109 .Fo procstat_freeptlwpinfo
110 .Fa "struct procstat *procstat"
111 .Fa "struct ptrace_lwpinfo *pl"
114 .Fo procstat_get_pipe_info
115 .Fa "struct procstat *procstat"
116 .Fa "struct filestat *fst"
117 .Fa "struct pipestat *pipe"
121 .Fo procstat_get_pts_info
122 .Fa "struct procstat *procstat"
123 .Fa "struct filestat *fst"
124 .Fa "struct ptsstat *pts"
128 .Fo procstat_get_sem_info
129 .Fa "struct procstat *procstat"
130 .Fa "struct filestat *fst"
131 .Fa "struct semstat *sem"
135 .Fo procstat_get_shm_info
136 .Fa "struct procstat *procstat"
137 .Fa "struct filestat *fst"
138 .Fa "struct shmstat *shm"
142 .Fo procstat_get_socket_info
143 .Fa "struct procstat *procstat"
144 .Fa "struct filestat *fst"
145 .Fa "struct sockstat *sock"
149 .Fo procstat_get_vnode_info
150 .Fa "struct procstat *procstat"
151 .Fa "struct filestat *fst"
152 .Fa "struct vnstat *vn"
157 .Fa "struct procstat *procstat"
158 .Fa "const struct kinfo_proc *kp"
163 .Fa "struct procstat *procstat"
164 .Fa "struct kinfo_proc *kp"
165 .Fa "unsigned int *count"
169 .Fa "struct procstat *procstat"
170 .Fa "const struct kinfo_proc *kp"
173 .Ft "struct filestat_list *"
174 .Fo procstat_getfiles
175 .Fa "struct procstat *procstat"
176 .Fa "struct kinfo_proc *kp"
180 .Fo procstat_getgroups
181 .Fa "struct procstat *procstat"
182 .Fa "struct kinfo_proc *kp"
183 .Fa "unsigned int *count"
185 .Ft "struct kinfo_kstack *"
186 .Fo procstat_getkstack
187 .Fa "struct procstat *procstat"
188 .Fa "struct kinfo_proc *kp"
189 .Fa "unsigned int *count"
192 .Fo procstat_getosrel
193 .Fa "struct procstat *procstat"
194 .Fa "struct kinfo_proc *kp"
198 .Fo procstat_getpathname
199 .Fa "struct procstat *procstat"
200 .Fa "struct kinfo_proc *kp"
204 .Ft "struct kinfo_proc *"
205 .Fo procstat_getprocs
206 .Fa "struct procstat *procstat"
209 .Fa "unsigned int *count"
211 .Ft "struct ptrace_lwpinfo *"
212 .Fo procstat_getptlwpinfo
213 .Fa "struct procstat *procstat"
214 .Fa "unsigned int *count"
217 .Fo procstat_getrlimit
218 .Fa "struct procstat *procstat"
219 .Fa "struct kinfo_proc *kp"
221 .Fa "struct rlimit* rlimit"
224 .Fo procstat_getumask
225 .Fa "struct procstat *procstat"
226 .Fa "struct kinfo_proc *kp"
227 .Fa "unsigned short *maskp"
229 .Ft "struct kinfo_vmentry *"
230 .Fo procstat_getvmmap
231 .Fa "struct procstat *procstat"
232 .Fa "struct kinfo_proc *kp"
233 .Fa "unsigned int *count"
235 .Ft "struct procstat *"
236 .Fn procstat_open_core "const char *filename"
237 .Ft "struct procstat *"
238 .Fn procstat_open_kvm "const char *nlistf" "const char *memf"
239 .Ft "struct procstat *"
240 .Fn procstat_open_sysctl void
244 library contains the API for runtime file and process information
245 retrieval from the running kernel via the
247 library backend, and for post-mortem analysis via the
249 library backend, or from the process
251 file, searching for statistics in special
256 .Fn procstat_open_kvm
258 .Fn procstat_open_sysctl
263 library routines, respectively, to access kernel state information
264 used to retrieve processes and files states.
266 .Fn procstat_open_core
269 routines to access statistics stored as a set of notes in a process
271 file, written by the kernel at the moment of the process abnormal termination.
274 argument is the process core file name.
277 argument is the executable image of the kernel being examined.
280 the currently running kernel is assumed.
283 argument is the kernel memory device file.
292 The functions dynamically allocate and return a
294 structure pointer used in the rest of the
296 library routines until the corresponding
298 call that cleans up the resources allocated by the
303 .Fn procstat_getprocs
304 function gets a pointer to the
306 structure from one of the
308 functions and returns a dynamically allocated (sub-)set of active processes
309 in the kernel filled in to array of
316 arguments constitute a filtering predicate as described in the
319 The number of processes found is returned in the reference parameter
321 The caller is responsible to free the allocated memory with a subsequent
322 .Fn procstat_freeprocs
326 .Fn procstat_getptlwpinfo
327 function gets a pointer to the
330 .Fn procstat_open_core
331 function and returns a dynamically allocated set of signals intercepted by a
332 process in the process's core file.
333 The number of processes found is returned in the reference parameter
335 The caller is responsible to free the allocated memory with a subsequent
336 .Fn procstat_freeptlwpinfo
341 function gets a pointer to the
343 structure from one of the
345 functions, a pointer to
347 structure from the array obtained from the
349 function, and returns a null-terminated argument vector that corresponds to
350 the command line arguments passed to the process.
353 argument indicates the maximum number of characters, including null bytes,
354 to use in building the strings.
355 If this amount is exceeded, the string causing the overflow is truncated and
356 the partial result is returned.
357 This is handy for programs that print only a one line summary of a
358 command and should not copy out large amounts of text only to ignore it.
361 is zero, no limit is imposed and all argument strings are returned.
362 The values of the returned argument vector refer the strings stored
366 A subsequent call of the function with the same
368 argument will reuse the buffer.
369 To free the allocated memory
370 .Fn procstat_freeargv
371 function call can be used, or it will be released on
376 function is similar to
378 but returns the vector of environment strings.
379 The caller may free the allocated memory with a subsequent
380 .Fn procstat_freeenvv
385 function gets a pointer to the
387 structure, a pointer to
389 structure, and returns the auxiliary vector as a dynamically allocated array of
392 The caller is responsible to free the allocated memory with a subsequent
393 .Fn procstat_freeauxv
397 .Fn procstat_getfiles
398 function gets a pointer to the
400 structure initialized with one of the
402 functions, a pointer to
404 structure from the array obtained from the
406 function, and returns a dynamically allocated linked list of filled in
408 structures using the STAILQ macros defined in
410 The caller is responsible to free the allocated memory with a subsequent
411 .Fn procstat_freefiles
415 .Fn procstat_getgroups
416 function gets a pointer to the
418 structure, a pointer to
420 structure, and returns the process groups as a dynamically allocated array of
423 The caller is responsible to free the allocated memory with a subsequent
424 .Fn procstat_freegroups
428 .Fn procstat_getkstack
429 function gets a pointer to the
431 structure initialized with one of the
433 functions, a pointer to
435 structure, and returns kernel stacks of the process as a dynamically allocated
439 The caller is responsible to free the allocated memory with a subsequent
440 .Fn procstat_freekstack
444 .Fn procstat_getosrel
445 function gets a pointer to the
447 structure, a pointer to
449 structure, and returns osrel date in the 3rd reference parameter.
452 .Fn procstat_getpathname
453 function gets a pointer to the
455 structure, a pointer to
457 structure, and copies the path of the process executable to
464 .Fn procstat_getrlimit
465 function gets a pointer to the
467 structure, a pointer to
469 structure, resource index
471 and returns the actual resource limit in the 4th reference parameter.
474 .Fn procstat_getumask
475 function gets a pointer to the
477 structure, a pointer to
479 structure, and returns the process umask in the 3rd reference parameter.
482 .Fn procstat_getvmmap
483 function gets a pointer to the
485 structure initialized with one of the
487 functions, a pointer to
489 structure, and returns VM layout of the process as a dynamically allocated
493 The caller is responsible to free the allocated memory with a subsequent
494 .Fn procstat_freevmmap
498 .Fn procstat_get_pipe_info ,
499 .Fn procstat_get_pts_info ,
500 .Fn procstat_get_sem_info ,
501 .Fn procstat_get_shm_info ,
502 .Fn procstat_get_socket_info
504 .Fn procstat_get_vnode_info
505 functions are used to retrieve information about pipes, pseudo-terminals,
506 semaphores, shared memory objects,
507 sockets, and vnodes, respectively.
508 Each of them have a similar interface API.
511 argument is a pointer obtained from one of
516 argument is an element of STAILQ linked list as obtained from the
517 .Fn procstat_getfiles
523 field that specifies a file type and a corresponding function to be
525 .Nm procstat_get_*_info
527 The actual object is returned in the 3rd reference parameter.
530 argument indicates an actual error message in case of failure.
532 .Bl -tag -width 20n -compact -offset indent
533 .It Li PS_FST_TYPE_FIFO
534 .Nm procstat_get_vnode_info
535 .It Li PS_FST_TYPE_VNODE
536 .Nm procstat_get_vnode_info
537 .It Li PS_FST_TYPE_SOCKET
538 .Nm procstat_get_socket_info
539 .It Li PS_FST_TYPE_PIPE
540 .Nm procstat_get_pipe_info
541 .It Li PS_FST_TYPE_PTS
542 .Nm procstat_get_pts_info
543 .It Li PS_FST_TYPE_SEM
544 .Nm procstat_get_sem_info
545 .It Li PS_FST_TYPE_SHM
546 .Nm procstat_get_shm_info
571 library was written by
572 .An Stanislav Sedov Aq Mt stas@FreeBSD.org .
574 This manual page was written by
575 .An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org .