1 files changed, 600 insertions, 0 deletions
diff --git a/lib/libprocstat/libprocstat.3 b/lib/libprocstat/libprocstat.3
new file mode 100644
index 000000000000..2617a8827a6d
--- /dev/null
+++ b/lib/libprocstat/libprocstat.3
@@ -0,0 +1,600 @@
+.\" Copyright (c) 2011 Sergey Kandaurov <pluknet@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd April 3, 2022
+.Dt LIBPROCSTAT 3
+.Os
+.Sh NAME
+.Nm procstat_close ,
+.Nm procstat_freeadvlock ,
+.Nm procstat_freeargv ,
+.Nm procstat_freeauxv ,
+.Nm procstat_freeenvv ,
+.Nm procstat_freefiles ,
+.Nm procstat_freegroups ,
+.Nm procstat_freekstack ,
+.Nm procstat_freeprocs ,
+.Nm procstat_freeptlwpinfo ,
+.Nm procstat_freevmmap ,
+.Nm procstat_get_pipe_info ,
+.Nm procstat_get_pts_info ,
+.Nm procstat_get_sem_info ,
+.Nm procstat_get_shm_info ,
+.Nm procstat_get_socket_info ,
+.Nm procstat_get_vnode_info ,
+.Nm procstat_getadvlock ,
+.Nm procstat_getargv ,
+.Nm procstat_getauxv ,
+.Nm procstat_getenvv ,
+.Nm procstat_getfiles ,
+.Nm procstat_getgroups ,
+.Nm procstat_getkstack ,
+.Nm procstat_getosrel ,
+.Nm procstat_getpathname ,
+.Nm procstat_getprocs ,
+.Nm procstat_getptlwpinfo ,
+.Nm procstat_getrlimit ,
+.Nm procstat_getumask ,
+.Nm procstat_getvmmap ,
+.Nm procstat_open_core ,
+.Nm procstat_open_kvm ,
+.Nm procstat_open_sysctl
+.Nd library interface for file and process information retrieval
+.Sh LIBRARY
+.Lb libprocstat
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/queue.h
+.In sys/socket.h
+.In libprocstat.h
+.Ft void
+.Fn procstat_close "struct procstat *procstat"
+.Ft void
+.Fn procstat_freeadvlock "struct procstat *procstat" "struct advlock_list *list"
+.Ft void
+.Fo procstat_freeargv
+.Fa "struct procstat *procstat"
+.Fc
+.Ft void
+.Fo procstat_freeauxv
+.Fa "struct procstat *procstat"
+.Fa "Elf_Auxinfo *auxv"
+.Fc
+.Ft void
+.Fo procstat_freeenvv
+.Fa "struct procstat *procstat"
+.Fc
+.Ft void
+.Fo procstat_freefiles
+.Fa "struct procstat *procstat"
+.Fa "struct filestat_list *head"
+.Fc
+.Ft void
+.Fo procstat_freegroups
+.Fa "struct procstat *procstat"
+.Fa "gid_t *groups"
+.Fc
+.Ft void
+.Fo procstat_freekstack
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_kstack *kkstp"
+.Fc
+.Ft void
+.Fn procstat_freeprocs "struct procstat *procstat" "struct kinfo_proc *p"
+.Ft void
+.Fo procstat_freevmmap
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_vmentry *vmmap"
+.Fc
+.Ft void
+.Fo procstat_freeptlwpinfo
+.Fa "struct procstat *procstat"
+.Fa "struct ptrace_lwpinfo *pl"
+.Fc
+.Ft int
+.Fo procstat_get_pipe_info
+.Fa "struct procstat *procstat"
+.Fa "struct filestat *fst"
+.Fa "struct pipestat *pipe"
+.Fa "char *errbuf"
+.Fc
+.Ft int
+.Fo procstat_get_pts_info
+.Fa "struct procstat *procstat"
+.Fa "struct filestat *fst"
+.Fa "struct ptsstat *pts"
+.Fa "char *errbuf"
+.Fc
+.Ft int
+.Fo procstat_get_sem_info
+.Fa "struct procstat *procstat"
+.Fa "struct filestat *fst"
+.Fa "struct semstat *sem"
+.Fa "char *errbuf"
+.Fc
+.Ft int
+.Fo procstat_get_shm_info
+.Fa "struct procstat *procstat"
+.Fa "struct filestat *fst"
+.Fa "struct shmstat *shm"
+.Fa "char *errbuf"
+.Fc
+.Ft int
+.Fo procstat_get_socket_info
+.Fa "struct procstat *procstat"
+.Fa "struct filestat *fst"
+.Fa "struct sockstat *sock"
+.Fa "char *errbuf"
+.Fc
+.Ft int
+.Fo procstat_get_vnode_info
+.Fa "struct procstat *procstat"
+.Fa "struct filestat *fst"
+.Fa "struct vnstat *vn"
+.Fa "char *errbuf"
+.Fc
+.Ft "struct advlock_list *"
+.Fo procstat_getadvlock
+.Fa "struct procstat *procstat"
+.Fc
+.Ft "char **"
+.Fo procstat_getargv
+.Fa "struct procstat *procstat"
+.Fa "const struct kinfo_proc *kp"
+.Fa "size_t nchr"
+.Fc
+.Ft "Elf_Auxinfo *"
+.Fo procstat_getauxv
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "unsigned int *count"
+.Fc
+.Ft "char **"
+.Fo procstat_getenvv
+.Fa "struct procstat *procstat"
+.Fa "const struct kinfo_proc *kp"
+.Fa "size_t nchr"
+.Fc
+.Ft "struct filestat_list *"
+.Fo procstat_getfiles
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "int mmapped"
+.Fc
+.Ft "gid_t *"
+.Fo procstat_getgroups
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "unsigned int *count"
+.Fc
+.Ft "struct kinfo_kstack *"
+.Fo procstat_getkstack
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "unsigned int *count"
+.Fc
+.Ft int
+.Fo procstat_getosrel
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "int *osrelp"
+.Fc
+.Ft "int"
+.Fo procstat_getpathname
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "char *pathname"
+.Fa "size_t maxlen"
+.Fc
+.Ft "struct kinfo_proc *"
+.Fo procstat_getprocs
+.Fa "struct procstat *procstat"
+.Fa "int what"
+.Fa "int arg"
+.Fa "unsigned int *count"
+.Fc
+.Ft "struct ptrace_lwpinfo *"
+.Fo procstat_getptlwpinfo
+.Fa "struct procstat *procstat"
+.Fa "unsigned int *count"
+.Fc
+.Ft "int"
+.Fo procstat_getrlimit
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "int which"
+.Fa "struct rlimit* rlimit"
+.Fc
+.Ft "int"
+.Fo procstat_getumask
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "unsigned short *maskp"
+.Fc
+.Ft "struct kinfo_vmentry *"
+.Fo procstat_getvmmap
+.Fa "struct procstat *procstat"
+.Fa "struct kinfo_proc *kp"
+.Fa "unsigned int *count"
+.Fc
+.Ft "struct procstat *"
+.Fn procstat_open_core "const char *filename"
+.Ft "struct procstat *"
+.Fn procstat_open_kvm "const char *nlistf" "const char *memf"
+.Ft "struct procstat *"
+.Fn procstat_open_sysctl void
+.Sh DESCRIPTION
+The
+.Nm libprocstat
+library contains the API for runtime file and process information
+retrieval from the running kernel via the
+.Xr sysctl 3
+library backend, and for post-mortem analysis via the
+.Xr kvm 3
+library backend, or from the process
+.Xr core 5
+file, searching for statistics in special
+.Xr elf 3
+note sections.
+.Pp
+The
+.Fn procstat_open_kvm
+and
+.Fn procstat_open_sysctl
+functions use the
+.Xr kvm 3
+or
+.Xr sysctl 3
+library routines, respectively, to access kernel state information
+used to retrieve processes and files states.
+The
+.Fn procstat_open_core
+uses
+.Xr elf 3
+routines to access statistics stored as a set of notes in a process
+.Xr core 5
+file, written by the kernel at the moment of the process abnormal termination.
+The
+.Fa filename
+argument is the process core file name.
+The
+.Fa nlistf
+argument is the executable image of the kernel being examined.
+If this argument is
+.Dv NULL ,
+the currently running kernel is assumed.
+The
+.Fa memf
+argument is the kernel memory device file.
+If this argument is
+.Dv NULL ,
+then
+.Pa /dev/mem
+is assumed.
+See
+.Xr kvm_open 3
+for more details.
+The functions dynamically allocate and return a
+.Vt procstat
+structure pointer used in the rest of the
+.Nm libprocstat
+library routines until the corresponding
+.Fn procstat_close
+call that cleans up the resources allocated by the
+.Fn procstat_open_*
+functions.
+.Pp
+The
+.Fn procstat_getprocs
+function gets a pointer to the
+.Vt procstat
+structure from one of the
+.Fn procstat_open_*
+functions and returns a dynamically allocated (sub-)set of active processes
+in the kernel filled in to array of
+.Vt kinfo_proc
+structures.
+The
+.Fa what
+and
+.Fa arg
+arguments constitute a filtering predicate as described in the
+.Xr kvm_getprocs 3
+function.
+The number of processes found is returned in the reference parameter
+.Fa cnt .
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freeprocs
+function call.
+.Pp
+The
+.Fn procstat_getptlwpinfo
+function gets a pointer to the
+.Vt procstat
+structure from the
+.Fn procstat_open_core
+function and returns a dynamically allocated set of signals intercepted by a
+process in the process's core file.
+The number of processes found is returned in the reference parameter
+.Fa cnt .
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freeptlwpinfo
+function call.
+.Pp
+The
+.Fn procstat_getargv
+function gets a pointer to the
+.Vt procstat
+structure from one of the
+.Fn procstat_open_*
+functions, a pointer to
+.Vt kinfo_proc
+structure from the array obtained from the
+.Fn procstat_getprocs
+function, and returns a null-terminated argument vector that corresponds to
+the command line arguments passed to the process.
+The
+.Fa nchr
+argument indicates the maximum number of characters, including null bytes,
+to use in building the strings.
+If this amount is exceeded, the string causing the overflow is truncated and
+the partial result is returned.
+This is handy for programs that print only a one line summary of a
+command and should not copy out large amounts of text only to ignore it.
+If
+.Fa nchr
+is zero, no limit is imposed and all argument strings are returned.
+The values of the returned argument vector refer the strings stored
+in the
+.Vt procstat
+internal buffer.
+A subsequent call of the function with the same
+.Vt procstat
+argument will reuse the buffer.
+To free the allocated memory
+.Fn procstat_freeargv
+function call can be used, or it will be released on
+.Fn procstat_close .
+.Pp
+The
+.Fn procstat_getenvv
+function is similar to
+.Fn procstat_getargv
+but returns the vector of environment strings.
+The caller may free the allocated memory with a subsequent
+.Fn procstat_freeenvv
+function call.
+.Pp
+The
+.Fn procstat_getauxv
+function gets a pointer to the
+.Vt procstat
+structure, a pointer to
+.Vt kinfo_proc
+structure, and returns the auxiliary vector as a dynamically allocated array of
+.Vt Elf_Auxinfo
+elements.
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freeauxv
+function call.
+.Pp
+The
+.Fn procstat_getfiles
+function gets a pointer to the
+.Vt procstat
+structure initialized with one of the
+.Fn procstat_open_*
+functions, a pointer to
+.Vt kinfo_proc
+structure from the array obtained from the
+.Fn procstat_getprocs
+function, and returns a dynamically allocated linked list of filled in
+.Vt filestat_list
+structures using the STAILQ macros defined in
+.Xr queue 3 .
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freefiles
+function call.
+.Pp
+The
+.Fn procstat_getgroups
+function gets a pointer to the
+.Vt procstat
+structure, a pointer to
+.Vt kinfo_proc
+structure, and returns the process groups as a dynamically allocated array of
+.Vt gid_t
+elements.
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freegroups
+function call.
+.Pp
+The
+.Fn procstat_getkstack
+function gets a pointer to the
+.Vt procstat
+structure initialized with one of the
+.Fn procstat_open_*
+functions, a pointer to
+.Vt kinfo_proc
+structure, and returns kernel stacks of the process as a dynamically allocated
+array of
+.Vt kinfo_kstack
+structures.
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freekstack
+function call.
+.Pp
+The
+.Fn procstat_getosrel
+function gets a pointer to the
+.Vt procstat
+structure, a pointer to
+.Vt kinfo_proc
+structure, and returns osrel date in the 3rd reference parameter.
+.Pp
+The
+.Fn procstat_getpathname
+function gets a pointer to the
+.Vt procstat
+structure, a pointer to
+.Vt kinfo_proc
+structure, and copies the path of the process executable to
+.Fa pathname
+buffer, limiting to
+.Fa maxlen
+characters.
+.Pp
+The
+.Fn procstat_getrlimit
+function gets a pointer to the
+.Vt procstat
+structure, a pointer to
+.Vt kinfo_proc
+structure, resource index
+.Fa which ,
+and returns the actual resource limit in the 4th reference parameter.
+.Pp
+The
+.Fn procstat_getumask
+function gets a pointer to the
+.Vt procstat
+structure, a pointer to
+.Vt kinfo_proc
+structure, and returns the process umask in the 3rd reference parameter.
+.Pp
+The
+.Fn procstat_getvmmap
+function gets a pointer to the
+.Vt procstat
+structure initialized with one of the
+.Fn procstat_open_*
+functions, a pointer to
+.Vt kinfo_proc
+structure, and returns VM layout of the process as a dynamically allocated
+array of
+.Vt kinfo_vmentry
+structures.
+The caller is responsible to free the allocated memory with a subsequent
+.Fn procstat_freevmmap
+function call.
+.Pp
+The
+.Fn procstat_getadvlock
+function returns a dynamically allocated list of
+.Va struct advlock
+structures, providing a snapshot of the currently
+acquired advisory locks in the system.
+Both locally acquired POSIX (
+.Xr fcntl 2 )
+and BSD-style (
+.Xr flock 2 )
+locks are reported, as well as locks established by remote file
+system protocols.
+For each lock, unique identifiers for the locked file and its mount point
+are guaranteed to be provided.
+If a path for the locked file can be reconstructed, it is provided as well.
+The returned list must be freed with the
+.Fn procstat_freeadvlock
+function.
+.Pp
+The
+.Fn procstat_get_pipe_info ,
+.Fn procstat_get_pts_info ,
+.Fn procstat_get_sem_info ,
+.Fn procstat_get_shm_info ,
+.Fn procstat_get_socket_info
+and
+.Fn procstat_get_vnode_info
+functions are used to retrieve information about pipes, pseudo-terminals,
+semaphores, shared memory objects,
+sockets, and vnodes, respectively.
+Each of them have a similar interface API.
+The
+.Fa procstat
+argument is a pointer obtained from one of
+.Fn procstat_open_*
+functions.
+The
+.Ft filestat Fa fst
+argument is an element of STAILQ linked list as obtained from the
+.Fn procstat_getfiles
+function.
+The
+.Ft filestat
+structure contains a
+.Fa fs_type
+field that specifies a file type and a corresponding function to be
+called among the
+.Nm procstat_get_*_info
+function family.
+The actual object is returned in the 3rd reference parameter.
+The
+.Fa errbuf
+argument indicates an actual error message in case of failure.
+.Pp
+.Bl -tag -width 20n -compact -offset indent
+.It Li PS_FST_TYPE_FIFO
+.Nm procstat_get_vnode_info
+.It Li PS_FST_TYPE_VNODE
+.Nm procstat_get_vnode_info
+.It Li PS_FST_TYPE_SOCKET
+.Nm procstat_get_socket_info
+.It Li PS_FST_TYPE_PIPE
+.Nm procstat_get_pipe_info
+.It Li PS_FST_TYPE_PTS
+.Nm procstat_get_pts_info
+.It Li PS_FST_TYPE_SEM
+.Nm procstat_get_sem_info
+.It Li PS_FST_TYPE_SHM
+.Nm procstat_get_shm_info
+.El
+.Sh SEE ALSO
+.Xr fstat 1 ,
+.Xr fuser 1 ,
+.Xr pipe 2 ,
+.Xr shm_open 2 ,
+.Xr socket 2 ,
+.Xr elf 3 ,
+.Xr kvm 3 ,
+.Xr queue 3 ,
+.Xr sem_open 3 ,
+.Xr sysctl 3 ,
+.Xr pts 4 ,
+.Xr core 5 ,
+.Xr vnode 9
+.Sh HISTORY
+The
+.Nm libprocstat
+library appeared in
+.Fx 9.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm libprocstat
+library was written by
+.An Stanislav Sedov Aq Mt stas@FreeBSD.org .
+.Pp
+This manual page was written by
+.An Sergey Kandaurov Aq Mt pluknet@FreeBSD.org .