1.\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/lib/libprocstat/libprocstat.3 249681 2013-04-20 08:10:47Z trociny $
26.\"
27.Dd April 1, 2012
28.Dt LIBPROCSTAT 3
29.Os
30.Sh NAME
31.Nm procstat_open_core ,
32.Nm procstat_open_kvm ,
33.Nm procstat_open_sysctl ,
34.Nm procstat_close ,
35.Nm procstat_getargv ,
36.Nm procstat_getauxv ,
37.Nm procstat_getenvv ,
38.Nm procstat_getfiles ,
39.Nm procstat_getgroups ,
40.Nm procstat_getosrel ,
41.Nm procstat_getpathname ,
42.Nm procstat_getprocs ,
43.Nm procstat_getumask ,
44.Nm procstat_getvmmap ,
45.Nm procstat_freeargv ,
46.Nm procstat_freeauxv ,
47.Nm procstat_freeenvv ,
48.Nm procstat_freefiles ,
49.Nm procstat_freegroups ,
50.Nm procstat_freeprocs ,
51.Nm procstat_freevmmap ,
52.Nm procstat_get_pipe_info ,
53.Nm procstat_get_pts_info ,
54.Nm procstat_get_shm_info ,
55.Nm procstat_get_socket_info ,
56.Nm procstat_get_vnode_info
57.Nd library interface for file and process information retrieval
58.Sh LIBRARY
59.Lb libprocstat
60.Sh SYNOPSIS
61.In sys/param.h
62.In sys/queue.h
63.In libprocstat.h
64.Ft void
65.Fn procstat_close "struct procstat *procstat"
66.Fc
67.Ft void
68.Fo procstat_freeargv
69.Fa "struct procstat *procstat"
70.Fc
71.Ft void
72.Fo procstat_freeauxv
73.Fa "struct procstat *procstat"
74.Fa "Elf_Auxinfo *auxv"
75.Fc
76.Ft void
77.Fo procstat_freeenvv
78.Fa "struct procstat *procstat"
79.Fc
80.Ft void
81.Fo procstat_freefiles
82.Fa "struct procstat *procstat"
83.Fa "struct filestat_list *head"
84.Fc
85.Ft void
86.Fo procstat_freegroups
87.Fa "struct procstat *procstat"
88.Fa "gid_t *groups"
89.Fc
90.Ft void
91.Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
92.Ft void
93.Fo procstat_freevmmap
94.Fa "struct procstat *procstat"
95.Fa "struct kinfo_vmentry *vmmap"
96.Fc
97.Ft int
98.Fo procstat_get_pipe_info
99.Fa "struct procstat *procstat"
100.Fa "struct filestat *fst"
101.Fa "struct pipestat *pipe"
102.Fa "char *errbuf"
103.Fc
104.Ft int
105.Fo procstat_get_pts_info
106.Fa "struct procstat *procstat"
107.Fa "struct filestat *fst"
108.Fa "struct ptsstat *pts"
109.Fa "char *errbuf"
110.Fc
111.Ft int
112.Fo procstat_get_shm_info
113.Fa "struct procstat *procstat"
114.Fa "struct filestat *fst"
115.Fa "struct shmstat *shm"
116.Fa "char *errbuf"
117.Fc
118.Ft int
119.Fo procstat_get_socket_info
120.Fa "struct procstat *procstat"
121.Fa "struct filestat *fst"
122.Fa "struct sockstat *sock"
123.Fa "char *errbuf"
124.Fc
125.Ft int
126.Fo procstat_get_vnode_info
127.Fa "struct procstat *procstat"
128.Fa "struct filestat *fst"
129.Fa "struct vnstat *vn"
130.Fa "char *errbuf"
131.Fc
132.Ft "char **"
133.Fo procstat_getargv
134.Fa "struct procstat *procstat"
135.Fa "const struct kinfo_proc *kp"
136.Fa "size_t nchr"
137.Fa "char *errbuf"
138.Fc
139.Ft "Elf_Auxinfo *"
140.Fo procstat_getauxv
141.Fa "struct procstat *procstat"
142.Fa "struct kinfo_proc *kp"
143.Fa "unsigned int *count"
144.Fc
145.Ft "char **"
146.Fo procstat_getenvv
147.Fa "struct procstat *procstat"
148.Fa "const struct kinfo_proc *kp"
149.Fa "size_t nchr"
150.Fa "char *errbuf"
151.Fc
152.Ft "struct filestat_list *"
153.Fo procstat_getfiles
154.Fa "struct procstat *procstat"
155.Fa "struct kinfo_proc *kp"
156.Fa "int mmapped"
157.Fc
158.Ft "gid_t *"
159.Fo procstat_getgroups
160.Fa "struct procstat *procstat"
161.Fa "struct kinfo_proc *kp"
162.Fa "unsigned int *count"
163.Ft int
164.Fo procstat_getosrel
165.Fa "struct procstat *procstat"
166.Fa "struct kinfo_proc *kp"
167.Fa "int *osrelp"
168.Fc
169.Ft "struct kinfo_proc *"
170.Fo procstat_getprocs
171.Fa "struct procstat *procstat"
172.Fa "int what"
173.Fa "int arg"
174.Fa "unsigned int *count"
175.Fc
176.Ft "int"
177.Fo procstat_getpathname
178.Fa "struct procstat *procstat"
179.Fa "struct kinfo_proc *kp"
180.Fa "char *pathname"
181.Fa "size_t maxlen"
182.Fc
183.Ft "int"
184.Fo procstat_getrlimit
185.Fa "struct procstat *procstat"
186.Fa "struct kinfo_proc *kp"
187.Fa "int which"
188.Fa "struct rlimit* rlimit"
189.Fc
190.Ft "int"
191.Fo procstat_getumask
192.Fa "struct procstat *procstat"
193.Fa "struct kinfo_proc *kp"
194.Fa "unsigned short *maskp"
195.Fc
196.Ft "struct kinfo_vmentry *"
197.Fo procstat_getvmmap
198.Fa "struct procstat *procstat"
199.Fa "struct kinfo_proc *kp"
200.Fa "unsigned int *count"
201.Fc
202.Ft "struct procstat *"
203.Fn procstat_open_core "const char *filename"
204.Ft "struct procstat *"
205.Fn procstat_open_kvm "const char *nlistf" "const char *memf"
206.Ft "struct procstat *"
207.Fn procstat_open_sysctl void
208.Sh DESCRIPTION
209The
210.Nm libprocstat
211library contains the API for runtime file and process information
212retrieval from the running kernel via the
213.Xr sysctl 3
214library backend, and for post-mortem analysis via the
215.Xr kvm 3
216library backend, or from the process
217.Xr core 5
218file, searching for statistics in special
219.Xr elf 3
220note sections.
221.Pp
222The
223.Fn procstat_open_kvm
224and
225.Fn procstat_open_sysctl
226functions use the
227.Xr kvm 3
228or
229.Xr sysctl 3
230library routines, respectively, to access kernel state information
231used to retrieve processes and files states.
232The
233.Fn procstat_open_core
234uses
235.Xr elf 3
236routines to access statistics stored as a set of notes in a process
237.Xr core 5
238file, written by the kernel at the moment of the process abnormal termination.
239The
240.Fa filename
241argument is the process core file name.
242The
243.Fa nlistf
244argument is the executable image of the kernel being examined.
245If this argument is
246.Dv NULL ,
247the currently running kernel is assumed.
248The
249.Fa memf
250argument is the kernel memory device file.
251If this argument is
252.Dv NULL ,
253then
254.Pa /dev/mem
255is assumed.
256See
257.Xr kvm_open 3
258for more details.
259The functions dynamically allocate and return a
260.Vt procstat
261structure pointer used in the rest of the
262.Nm libprocstat
263library routines until the corresponding
264.Fn procstat_close
265call that cleans up the resources allocated by the
266.Fn procstat_open_*
267functions.
268.Pp
269The
270.Fn procstat_getprocs
271function gets a pointer to the
272.Vt procstat
273structure from one of the
274.Fn procstat_open_*
275functions and returns a dynamically allocated (sub-)set of active processes
276in the kernel filled in to array of
277.Vt kinfo_proc
278structures.
279The
280.Fa what
281and
282.Fa arg
283arguments constitute a filtering predicate as described in the
284.Xr kvm_getprocs 3
285function.
286The number of processes found is returned in the reference parameter
287.Fa cnt .
288The caller is responsible to free the allocated memory with a subsequent
289.Fn procstat_freeprocs
290function call.
291.Pp
292The
293.Fn procstat_getargv
294function gets a pointer to the
295.Vt procstat
296structure from one of the
297.Fn procstat_open_*
298functions, a pointer to
299.Vt kinfo_proc
300structure from the array obtained from the
301.Fn kvm_getprocs
302function, and returns a null-terminated argument vector that corresponds to
303the command line arguments passed to the process.
304The
305.Fa nchr
306argument indicates the maximum number of characters, including null bytes,
307to use in building the strings.
308If this amount is exceeded, the string causing the overflow is truncated and
309the partial result is returned.
310This is handy for programs that print only a one line summary of a
311command and should not copy out large amounts of text only to ignore it.
312If
313.Fa nchr
314is zero, no limit is imposed and all argument strings are returned.
315The values of the returned argument vector refer the strings stored
316in the
317.Vt procstat
318internal buffer.
319A subsequent call of the function with the same
320.Vt procstat
321argument will reuse the buffer.
322To free the allocated memory
323.Fn procstat_freeargv
324function call can be used, or it will be released on
325.Fn procstat_close .
326.Pp
327The
328.Fn procstat_getenvv
329function is similar to
330.Fn procstat_getargv
331but returns the vector of environment strings.
332The caller may free the allocated memory with a subsequent
333.Fn procstat_freeenv
334function call.
335.Pp
336The
337.Fn procstat_getauxv
338function gets a pointer to the
339.Vt procstat
340structure, a pointer to
341.Vt kinfo_proc
342structure, and returns the auxiliary vector as a dynamically allocated array of
343.Vt Elf_Auxinfo
344elements.
345The caller is responsible to free the allocated memory with a subsequent
346.Fn procstat_freeauxv
347function call.
348.Pp
349The
350.Fn procstat_getfiles
351function gets a pointer to the
352.Vt procstat
353structure initialized with one of the
354.Fn procstat_open_*
355functions, a pointer to
356.Vt kinfo_proc
357structure from the array obtained from the
358.Fn kvm_getprocs
359function, and returns a dynamically allocated linked list of filled in
360.Vt filestat_list
361structures using the STAILQ macros defined in
362.Xr queue 3 .
363The caller is responsible to free the allocated memory with a subsequent
364.Fn procstat_freefiles
365function call.
366.Pp
367The
368.Fn procstat_getgroups
369function gets a pointer to the
370.Vt procstat
371structure, a pointer to
372.Vt kinfo_proc
373structure, and returns the process groups as a dynamically allocated array of
374.Vt gid_t
375elements.
376The caller is responsible to free the allocated memory with a subsequent
377.Fn procstat_freegroups
378function call.
379.Pp
380The
381.Fn procstat_getosrel
382function gets a pointer to the
383.Vt procstat
384structure, a pointer to
385.Vt kinfo_proc
386structure, and returns osrel date in the 3rd reference parameter.
387.Pp
388The
389.Fn procstat_getpathname
390function gets a pointer to the
391.Vt procstat
392structure, a pointer to
393.Vt kinfo_proc
394structure, and copies the path of the process executable to
395.Fa pathname
396buffer, limiting to
397.Fa maxlen
398characters.
399.Pp
400The
401.Fn procstat_getrlimit
402function gets a pointer to the
403.Vt procstat
404structure, a pointer to
405.Vt kinfo_proc
406structure, resource index
407.Fa which ,
408and returns the actual resource limit in the 4th reference parameter.
409.Pp
410The
411.Fn procstat_getumask
412function gets a pointer to the
413.Vt procstat
414structure, a pointer to
415.Vt kinfo_proc
416structure, and returns the process umask in the 3rd reference parameter.
417.Pp
418The
419.Fn procstat_getvmmap
420function gets a pointer to the
421.Vt procstat
422structure initialized with one of the
423.Fn procstat_open_*
424functions, a pointer to
425.Vt kinfo_proc
426structure, and returns VM layout of the process as a dynamically allocated
427array of
428.Vt kinfo_vmentry
429structures.
430The caller is responsible to free the allocated memory with a subsequent
431.Fn procstat_freevmmap
432function call.
433.Pp
434The
435.Fn procstat_get_pipe_info ,
436.Fn procstat_get_pts_info ,
437.Fn procstat_get_shm_info ,
438.Fn procstat_get_socket_info
439and
440.Fn procstat_get_vnode_info
441functions are used to retrieve information about pipes, pseudo-terminals,
442shared memory objects,
443sockets, and vnodes, respectively.
444Each of them have a similar interface API.
445The
446.Fa procstat
447argument is a pointer obtained from one of
448.Fn procstat_open_*
449functions.
450The
451.Ft filestat Fa fst
452argument is an element of STAILQ linked list as obtained from the
453.Fn procstat_getfiles
454function.
455The
456.Ft filestat
457structure contains a
458.Fa fs_type
459field that specifies a file type and a corresponding function to be
460called among the
461.Nm procstat_get_*_info
462function family.
463The actual object is returned in the 3rd reference parameter.
464The
465.Fa errbuf
466argument indicates an actual error message in case of failure.
467.Pp
468.Bl -tag -width 20n -compact -offset indent
469.It Li PS_FST_TYPE_FIFO
470.Nm procstat_get_vnode_info
471.It Li PS_FST_TYPE_VNODE
472.Nm procstat_get_vnode_info
473.It Li PS_FST_TYPE_SOCKET
474.Nm procstat_get_socket_info
475.It Li PS_FST_TYPE_PIPE
476.Nm procstat_get_pipe_info
477.It Li PS_FST_TYPE_PTS
478.Nm procstat_get_pts_info
479.It Li PS_FST_TYPE_SHM
480.Nm procstat_get_shm_info
481.El
482.Sh SEE ALSO
483.Xr fstat 1 ,
484.Xr fuser 1 ,
485.Xr pipe 2 ,
486.Xr shm_open 2 ,
487.Xr socket 2 ,
488.Xr elf 3 ,
489.Xr kvm 3 ,
490.Xr queue 3 ,
491.Xr sysctl 3 ,
492.Xr pts 4 ,
493.Xr core 5 ,
494.Xr vnode 9
495.Sh HISTORY
496The
497.Nm libprocstat
498library appeared in
499.Fx 9.0 .
500.Sh AUTHORS
501.An -nosplit
502The
503.Nm libprocstat
504library was written by
505.An Stanislav Sedov Aq stas@FreeBSD.org .
506.Pp
507This manual page was written by
508.An Sergey Kandaurov Aq pluknet@FreeBSD.org .
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/lib/libprocstat/libprocstat.3 249681 2013-04-20 08:10:47Z trociny $
26.\"
27.Dd April 1, 2012
28.Dt LIBPROCSTAT 3
29.Os
30.Sh NAME
31.Nm procstat_open_core ,
32.Nm procstat_open_kvm ,
33.Nm procstat_open_sysctl ,
34.Nm procstat_close ,
35.Nm procstat_getargv ,
36.Nm procstat_getauxv ,
37.Nm procstat_getenvv ,
38.Nm procstat_getfiles ,
39.Nm procstat_getgroups ,
40.Nm procstat_getosrel ,
41.Nm procstat_getpathname ,
42.Nm procstat_getprocs ,
43.Nm procstat_getumask ,
44.Nm procstat_getvmmap ,
45.Nm procstat_freeargv ,
46.Nm procstat_freeauxv ,
47.Nm procstat_freeenvv ,
48.Nm procstat_freefiles ,
49.Nm procstat_freegroups ,
50.Nm procstat_freeprocs ,
51.Nm procstat_freevmmap ,
52.Nm procstat_get_pipe_info ,
53.Nm procstat_get_pts_info ,
54.Nm procstat_get_shm_info ,
55.Nm procstat_get_socket_info ,
56.Nm procstat_get_vnode_info
57.Nd library interface for file and process information retrieval
58.Sh LIBRARY
59.Lb libprocstat
60.Sh SYNOPSIS
61.In sys/param.h
62.In sys/queue.h
63.In libprocstat.h
64.Ft void
65.Fn procstat_close "struct procstat *procstat"
66.Fc
67.Ft void
68.Fo procstat_freeargv
69.Fa "struct procstat *procstat"
70.Fc
71.Ft void
72.Fo procstat_freeauxv
73.Fa "struct procstat *procstat"
74.Fa "Elf_Auxinfo *auxv"
75.Fc
76.Ft void
77.Fo procstat_freeenvv
78.Fa "struct procstat *procstat"
79.Fc
80.Ft void
81.Fo procstat_freefiles
82.Fa "struct procstat *procstat"
83.Fa "struct filestat_list *head"
84.Fc
85.Ft void
86.Fo procstat_freegroups
87.Fa "struct procstat *procstat"
88.Fa "gid_t *groups"
89.Fc
90.Ft void
91.Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
92.Ft void
93.Fo procstat_freevmmap
94.Fa "struct procstat *procstat"
95.Fa "struct kinfo_vmentry *vmmap"
96.Fc
97.Ft int
98.Fo procstat_get_pipe_info
99.Fa "struct procstat *procstat"
100.Fa "struct filestat *fst"
101.Fa "struct pipestat *pipe"
102.Fa "char *errbuf"
103.Fc
104.Ft int
105.Fo procstat_get_pts_info
106.Fa "struct procstat *procstat"
107.Fa "struct filestat *fst"
108.Fa "struct ptsstat *pts"
109.Fa "char *errbuf"
110.Fc
111.Ft int
112.Fo procstat_get_shm_info
113.Fa "struct procstat *procstat"
114.Fa "struct filestat *fst"
115.Fa "struct shmstat *shm"
116.Fa "char *errbuf"
117.Fc
118.Ft int
119.Fo procstat_get_socket_info
120.Fa "struct procstat *procstat"
121.Fa "struct filestat *fst"
122.Fa "struct sockstat *sock"
123.Fa "char *errbuf"
124.Fc
125.Ft int
126.Fo procstat_get_vnode_info
127.Fa "struct procstat *procstat"
128.Fa "struct filestat *fst"
129.Fa "struct vnstat *vn"
130.Fa "char *errbuf"
131.Fc
132.Ft "char **"
133.Fo procstat_getargv
134.Fa "struct procstat *procstat"
135.Fa "const struct kinfo_proc *kp"
136.Fa "size_t nchr"
137.Fa "char *errbuf"
138.Fc
139.Ft "Elf_Auxinfo *"
140.Fo procstat_getauxv
141.Fa "struct procstat *procstat"
142.Fa "struct kinfo_proc *kp"
143.Fa "unsigned int *count"
144.Fc
145.Ft "char **"
146.Fo procstat_getenvv
147.Fa "struct procstat *procstat"
148.Fa "const struct kinfo_proc *kp"
149.Fa "size_t nchr"
150.Fa "char *errbuf"
151.Fc
152.Ft "struct filestat_list *"
153.Fo procstat_getfiles
154.Fa "struct procstat *procstat"
155.Fa "struct kinfo_proc *kp"
156.Fa "int mmapped"
157.Fc
158.Ft "gid_t *"
159.Fo procstat_getgroups
160.Fa "struct procstat *procstat"
161.Fa "struct kinfo_proc *kp"
162.Fa "unsigned int *count"
163.Ft int
164.Fo procstat_getosrel
165.Fa "struct procstat *procstat"
166.Fa "struct kinfo_proc *kp"
167.Fa "int *osrelp"
168.Fc
169.Ft "struct kinfo_proc *"
170.Fo procstat_getprocs
171.Fa "struct procstat *procstat"
172.Fa "int what"
173.Fa "int arg"
174.Fa "unsigned int *count"
175.Fc
176.Ft "int"
177.Fo procstat_getpathname
178.Fa "struct procstat *procstat"
179.Fa "struct kinfo_proc *kp"
180.Fa "char *pathname"
181.Fa "size_t maxlen"
182.Fc
183.Ft "int"
184.Fo procstat_getrlimit
185.Fa "struct procstat *procstat"
186.Fa "struct kinfo_proc *kp"
187.Fa "int which"
188.Fa "struct rlimit* rlimit"
189.Fc
190.Ft "int"
191.Fo procstat_getumask
192.Fa "struct procstat *procstat"
193.Fa "struct kinfo_proc *kp"
194.Fa "unsigned short *maskp"
195.Fc
196.Ft "struct kinfo_vmentry *"
197.Fo procstat_getvmmap
198.Fa "struct procstat *procstat"
199.Fa "struct kinfo_proc *kp"
200.Fa "unsigned int *count"
201.Fc
202.Ft "struct procstat *"
203.Fn procstat_open_core "const char *filename"
204.Ft "struct procstat *"
205.Fn procstat_open_kvm "const char *nlistf" "const char *memf"
206.Ft "struct procstat *"
207.Fn procstat_open_sysctl void
208.Sh DESCRIPTION
209The
210.Nm libprocstat
211library contains the API for runtime file and process information
212retrieval from the running kernel via the
213.Xr sysctl 3
214library backend, and for post-mortem analysis via the
215.Xr kvm 3
216library backend, or from the process
217.Xr core 5
218file, searching for statistics in special
219.Xr elf 3
220note sections.
221.Pp
222The
223.Fn procstat_open_kvm
224and
225.Fn procstat_open_sysctl
226functions use the
227.Xr kvm 3
228or
229.Xr sysctl 3
230library routines, respectively, to access kernel state information
231used to retrieve processes and files states.
232The
233.Fn procstat_open_core
234uses
235.Xr elf 3
236routines to access statistics stored as a set of notes in a process
237.Xr core 5
238file, written by the kernel at the moment of the process abnormal termination.
239The
240.Fa filename
241argument is the process core file name.
242The
243.Fa nlistf
244argument is the executable image of the kernel being examined.
245If this argument is
246.Dv NULL ,
247the currently running kernel is assumed.
248The
249.Fa memf
250argument is the kernel memory device file.
251If this argument is
252.Dv NULL ,
253then
254.Pa /dev/mem
255is assumed.
256See
257.Xr kvm_open 3
258for more details.
259The functions dynamically allocate and return a
260.Vt procstat
261structure pointer used in the rest of the
262.Nm libprocstat
263library routines until the corresponding
264.Fn procstat_close
265call that cleans up the resources allocated by the
266.Fn procstat_open_*
267functions.
268.Pp
269The
270.Fn procstat_getprocs
271function gets a pointer to the
272.Vt procstat
273structure from one of the
274.Fn procstat_open_*
275functions and returns a dynamically allocated (sub-)set of active processes
276in the kernel filled in to array of
277.Vt kinfo_proc
278structures.
279The
280.Fa what
281and
282.Fa arg
283arguments constitute a filtering predicate as described in the
284.Xr kvm_getprocs 3
285function.
286The number of processes found is returned in the reference parameter
287.Fa cnt .
288The caller is responsible to free the allocated memory with a subsequent
289.Fn procstat_freeprocs
290function call.
291.Pp
292The
293.Fn procstat_getargv
294function gets a pointer to the
295.Vt procstat
296structure from one of the
297.Fn procstat_open_*
298functions, a pointer to
299.Vt kinfo_proc
300structure from the array obtained from the
301.Fn kvm_getprocs
302function, and returns a null-terminated argument vector that corresponds to
303the command line arguments passed to the process.
304The
305.Fa nchr
306argument indicates the maximum number of characters, including null bytes,
307to use in building the strings.
308If this amount is exceeded, the string causing the overflow is truncated and
309the partial result is returned.
310This is handy for programs that print only a one line summary of a
311command and should not copy out large amounts of text only to ignore it.
312If
313.Fa nchr
314is zero, no limit is imposed and all argument strings are returned.
315The values of the returned argument vector refer the strings stored
316in the
317.Vt procstat
318internal buffer.
319A subsequent call of the function with the same
320.Vt procstat
321argument will reuse the buffer.
322To free the allocated memory
323.Fn procstat_freeargv
324function call can be used, or it will be released on
325.Fn procstat_close .
326.Pp
327The
328.Fn procstat_getenvv
329function is similar to
330.Fn procstat_getargv
331but returns the vector of environment strings.
332The caller may free the allocated memory with a subsequent
333.Fn procstat_freeenv
334function call.
335.Pp
336The
337.Fn procstat_getauxv
338function gets a pointer to the
339.Vt procstat
340structure, a pointer to
341.Vt kinfo_proc
342structure, and returns the auxiliary vector as a dynamically allocated array of
343.Vt Elf_Auxinfo
344elements.
345The caller is responsible to free the allocated memory with a subsequent
346.Fn procstat_freeauxv
347function call.
348.Pp
349The
350.Fn procstat_getfiles
351function gets a pointer to the
352.Vt procstat
353structure initialized with one of the
354.Fn procstat_open_*
355functions, a pointer to
356.Vt kinfo_proc
357structure from the array obtained from the
358.Fn kvm_getprocs
359function, and returns a dynamically allocated linked list of filled in
360.Vt filestat_list
361structures using the STAILQ macros defined in
362.Xr queue 3 .
363The caller is responsible to free the allocated memory with a subsequent
364.Fn procstat_freefiles
365function call.
366.Pp
367The
368.Fn procstat_getgroups
369function gets a pointer to the
370.Vt procstat
371structure, a pointer to
372.Vt kinfo_proc
373structure, and returns the process groups as a dynamically allocated array of
374.Vt gid_t
375elements.
376The caller is responsible to free the allocated memory with a subsequent
377.Fn procstat_freegroups
378function call.
379.Pp
380The
381.Fn procstat_getosrel
382function gets a pointer to the
383.Vt procstat
384structure, a pointer to
385.Vt kinfo_proc
386structure, and returns osrel date in the 3rd reference parameter.
387.Pp
388The
389.Fn procstat_getpathname
390function gets a pointer to the
391.Vt procstat
392structure, a pointer to
393.Vt kinfo_proc
394structure, and copies the path of the process executable to
395.Fa pathname
396buffer, limiting to
397.Fa maxlen
398characters.
399.Pp
400The
401.Fn procstat_getrlimit
402function gets a pointer to the
403.Vt procstat
404structure, a pointer to
405.Vt kinfo_proc
406structure, resource index
407.Fa which ,
408and returns the actual resource limit in the 4th reference parameter.
409.Pp
410The
411.Fn procstat_getumask
412function gets a pointer to the
413.Vt procstat
414structure, a pointer to
415.Vt kinfo_proc
416structure, and returns the process umask in the 3rd reference parameter.
417.Pp
418The
419.Fn procstat_getvmmap
420function gets a pointer to the
421.Vt procstat
422structure initialized with one of the
423.Fn procstat_open_*
424functions, a pointer to
425.Vt kinfo_proc
426structure, and returns VM layout of the process as a dynamically allocated
427array of
428.Vt kinfo_vmentry
429structures.
430The caller is responsible to free the allocated memory with a subsequent
431.Fn procstat_freevmmap
432function call.
433.Pp
434The
435.Fn procstat_get_pipe_info ,
436.Fn procstat_get_pts_info ,
437.Fn procstat_get_shm_info ,
438.Fn procstat_get_socket_info
439and
440.Fn procstat_get_vnode_info
441functions are used to retrieve information about pipes, pseudo-terminals,
442shared memory objects,
443sockets, and vnodes, respectively.
444Each of them have a similar interface API.
445The
446.Fa procstat
447argument is a pointer obtained from one of
448.Fn procstat_open_*
449functions.
450The
451.Ft filestat Fa fst
452argument is an element of STAILQ linked list as obtained from the
453.Fn procstat_getfiles
454function.
455The
456.Ft filestat
457structure contains a
458.Fa fs_type
459field that specifies a file type and a corresponding function to be
460called among the
461.Nm procstat_get_*_info
462function family.
463The actual object is returned in the 3rd reference parameter.
464The
465.Fa errbuf
466argument indicates an actual error message in case of failure.
467.Pp
468.Bl -tag -width 20n -compact -offset indent
469.It Li PS_FST_TYPE_FIFO
470.Nm procstat_get_vnode_info
471.It Li PS_FST_TYPE_VNODE
472.Nm procstat_get_vnode_info
473.It Li PS_FST_TYPE_SOCKET
474.Nm procstat_get_socket_info
475.It Li PS_FST_TYPE_PIPE
476.Nm procstat_get_pipe_info
477.It Li PS_FST_TYPE_PTS
478.Nm procstat_get_pts_info
479.It Li PS_FST_TYPE_SHM
480.Nm procstat_get_shm_info
481.El
482.Sh SEE ALSO
483.Xr fstat 1 ,
484.Xr fuser 1 ,
485.Xr pipe 2 ,
486.Xr shm_open 2 ,
487.Xr socket 2 ,
488.Xr elf 3 ,
489.Xr kvm 3 ,
490.Xr queue 3 ,
491.Xr sysctl 3 ,
492.Xr pts 4 ,
493.Xr core 5 ,
494.Xr vnode 9
495.Sh HISTORY
496The
497.Nm libprocstat
498library appeared in
499.Fx 9.0 .
500.Sh AUTHORS
501.An -nosplit
502The
503.Nm libprocstat
504library was written by
505.An Stanislav Sedov Aq stas@FreeBSD.org .
506.Pp
507This manual page was written by
508.An Sergey Kandaurov Aq pluknet@FreeBSD.org .