git: 50d3c72558f2 - main - libprocstat: document procstat_getadvlock(3)

From: Konstantin Belousov <kib_at_FreeBSD.org>
Date: Sat, 09 Apr 2022 21:48:24 UTC
The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=50d3c72558f2d0c0ae0a037813a9af420935b538

commit 50d3c72558f2d0c0ae0a037813a9af420935b538
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2022-04-03 14:54:27 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2022-04-09 21:47:49 +0000

    libprocstat: document procstat_getadvlock(3)
    
    Reviewed by:    markj, rmacklem
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D34756
---
 lib/libprocstat/libprocstat.3 | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/lib/libprocstat/libprocstat.3 b/lib/libprocstat/libprocstat.3
index 20d86a57217c..89ccdb245617 100644
--- a/lib/libprocstat/libprocstat.3
+++ b/lib/libprocstat/libprocstat.3
@@ -24,11 +24,12 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 26, 2020
+.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 ,
@@ -44,6 +45,7 @@
 .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 ,
@@ -71,6 +73,8 @@
 .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
@@ -152,6 +156,10 @@
 .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"
@@ -495,6 +503,25 @@ The caller is responsible to free the allocated memory with a subsequent
 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 ,