LIBPROCSTAT(3)

NAME
procstat_open_kvm, procstat_open_sysctl, procstat_close, procstat_getfiles, procstat_getprocs, procstat_freefiles, procstat_freeprocs, procstat_get_pipe_info, procstat_get_pts_info, procstat_get_shm_info, procstat_get_socket_info, procstat_get_vnode_info - library interface for file and process information retrieval

LIBRARY
libprocstat

SYNOPSIS
#include <sys/param.h>
#include <sys/queue.h>
#include <libprocstat.h>
void
procstat_close(struct procstat *procstat);
void
procstat_freefiles(struct procstat *procstat, struct filestat_list *head);
void
procstat_freeprocs(struct procstat *procstat, struct kinfo_proc *p);
int
procstat_get_pipe_info(struct procstat *procstat, struct filestat *fst, struct pipestat *pipe, char *errbuf);
int
procstat_get_pts_info(struct procstat *procstat, struct filestat *fst, struct ptsstat *pts, char *errbuf);
int
procstat_get_shm_info(struct procstat *procstat, struct filestat *fst, struct shmstat *shm, char *errbuf);
int
procstat_get_socket_info(struct procstat *procstat, struct filestat *fst, struct sockstat *sock, char *errbuf);
int
procstat_get_vnode_info(struct procstat *procstat, struct filestat *fst, struct vnstat *vn, char *errbuf);
struct filestat_list *
procstat_getfiles(struct procstat *procstat, struct kinfo_proc *kp, int mmapped);
struct kinfo_proc *
procstat_getprocs(struct procstat *procstat, int what, int arg, unsigned int *count);
struct procstat *
procstat_open_kvm(const char *nlistf, const char *memf);
struct procstat *
procstat_open_sysctl(void);

DESCRIPTION
The libprocstat library contains the API for runtime file and process information retrieval from the running kernel via the sysctl(3) library backend, and for post-mortem analysis via the kvm(3) library backend.

The procstat_open_kvm() and procstat_open_sysctl() functions use the kvm(3) or sysctl(3) library routines, respectively, to access kernel state information used to retrieve processes and files states. The nlistf argument is the executable image of the kernel being examined. If this argument is NULL, the currently running kernel is assumed. The memf argument is the kernel memory device file. If this argument is NULL, then /dev/mem is assumed. See kvm_open(3) for more details. Both functions dynamically allocate and return a procstat structure pointer used in the rest of the libprocstat library routines until the corresponding procstat_close() call that cleans up the resources allocated by the procstat_open_*() functions.

The procstat_getprocs() function gets a pointer to the procstat structure from one of the procstat_open_*() functions and returns a dynamically allocated (sub-)set of active processes in the kernel filled in to array of kinfo_proc structures. The what and arg arguments constitute a filtering predicate as described in the kvm_getprocs(3) function. The number of processes found is returned in the reference parameter cnt. The caller is responsible to free the allocated memory with a subsequent procstat_freeprocs() function call.

The procstat_getfiles() function gets a pointer to the procstat structure initialized with one of the procstat_open_*() functions, a pointer to kinfo_proc structure from the array obtained from the kvm_getprocs() function, and returns a dynamically allocated linked list of filled in filestat_list structures using the STAILQ macros defined in queue(3). The caller is responsible to free the allocated memory with a subsequent procstat_freefiles() function call.

The procstat_get_pipe_info(), procstat_get_pts_info(), procstat_get_shm_info(), procstat_get_socket_info() and procstat_get_vnode_info() functions are used to retrieve information about pipes, pseudo-terminals, shared memory objects, sockets, and vnodes, respectively. Each of them have a similar interface API. The procstat argument is a pointer obtained from one of procstat_open_*() functions. The filestat fst argument is an element of STAILQ linked list as obtained from the procstat_getfiles() function. The filestat structure contains a fs_type field that specifies a file type and a corresponding function to be called among the procstat_get_*_info function family. The actual object is returned in the 3rd reference parameter. The errbuf argument indicates an actual error message in case of failure.

PS_FST_TYPE_FIFO
    procstat_get_vnode_info
PS_FST_TYPE_VNODE
    procstat_get_vnode_info
PS_FST_TYPE_SOCKET
    procstat_get_socket_info
PS_FST_TYPE_PIPE
    procstat_get_pipe_info
PS_FST_TYPE_PTS
    procstat_get_pts_info
PS_FST_TYPE_SHM
    procstat_get_shm_info

SEE ALSO
fstat(1), fuser(1), pipe(2), shm_open(2), socket(2), kvm(3), queue(3), sysctl(3), pts(4), vnode(9)

HISTORY
The libprocstat library appeared in FreeBSD 9.0.

AUTHORS
-nosplit The libprocstat library was written by Stanislav Sedov <stas@FreeBSD.org>.

This manual page was written by Sergey Kandaurov <pluknet@FreeBSD.org>.