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