git: fda32d586035 - main - lock.9: describe lockmgr_{disowned,lock_flags,slock,unlock,xlock}

The branch main has been updated by rlibby:

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

commit fda32d586035f0bead930ecdb4547869e1c80fb5
Author:     Ryan Libby <rlibby@FreeBSD.org>
AuthorDate: 2024-06-23 21:46:31 +0000
Commit:     Ryan Libby <rlibby@FreeBSD.org>
CommitDate: 2024-06-23 21:46:31 +0000

    lock.9: describe lockmgr_{disowned,lock_flags,slock,unlock,xlock}
    
    Describe and link the following functions in the lockgmr API:
     - lockmgr_disowned
     - lockmgr_lock_flags
     - lockmgr_slock
     - lockmgr_unlock
     - lockmgr_xlock
    
    This is not a complete update of lock.9 but at least covers all the main
    lock operations.
    
    Reviewed by:    gbe, kib
    Sponsored by:   Dell EMC Isilon
    Differential Revision:  https://reviews.freebsd.org/D45689
---
 share/man/man9/Makefile |  5 ++++
 share/man/man9/lock.9   | 63 ++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index dfc9bd996504..38d836b1647a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1431,9 +1431,14 @@ MLINKS+=lock.9 lockdestroy.9 \
 	lock.9 lockmgr_args_rw.9 \
 	lock.9 lockmgr_assert.9 \
 	lock.9 lockmgr_disown.9 \
+	lock.9 lockmgr_disowned.9 \
+	lock.9 lockmgr_lock_flags.9 \
 	lock.9 lockmgr_printinfo.9 \
 	lock.9 lockmgr_recursed.9 \
 	lock.9 lockmgr_rw.9 \
+	lock.9 lockmgr_slock.9 \
+	lock.9 lockmgr_unlock.9 \
+	lock.9 lockmgr_xlock.9 \
 	lock.9 lockstatus.9
 MLINKS+=LOCK_PROFILING.9 MUTEX_PROFILING.9
 MLINKS+=make_dev.9 destroy_dev.9 \
diff --git a/share/man/man9/lock.9 b/share/man/man9/lock.9
index 96f617a72123..9cff6e3bd8aa 100644
--- a/share/man/man9/lock.9
+++ b/share/man/man9/lock.9
@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 .\" DAMAGE.
 .\"
-.Dd May 18, 2024
+.Dd June 21, 2024
 .Dt LOCK 9
 .Os
 .Sh NAME
@@ -34,9 +34,14 @@
 .Nm lockmgr_args ,
 .Nm lockmgr_args_rw ,
 .Nm lockmgr_disown ,
+.Nm lockmgr_disowned ,
+.Nm lockmgr_lock_flags ,
 .Nm lockmgr_printinfo ,
 .Nm lockmgr_recursed ,
 .Nm lockmgr_rw ,
+.Nm lockmgr_slock ,
+.Nm lockmgr_unlock ,
+.Nm lockmgr_xlock ,
 .Nm lockstatus ,
 .Nm lockmgr_assert
 .Nd "lockmgr family of functions"
@@ -56,6 +61,10 @@
 .Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo"
 .Ft void
 .Fn lockmgr_disown "struct lock *lkp"
+.Ft int
+.Fn lockmgr_disowned "const struct lock *lkp"
+.Ft int
+.Fn lockmgr_lock_flags "struct lock *lkp" "u_int flags" "struct lock_object *ilk" "const char *file" "int line"
 .Ft void
 .Fn lockmgr_printinfo "const struct lock *lkp"
 .Ft int
@@ -63,6 +72,12 @@
 .Ft int
 .Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk"
 .Ft int
+.Fn lockmgr_slock "struct lock *lkp" "u_int flags" "const char *file" "int line"
+.Ft int
+.Fn lockmgr_unlock "struct lock *lkp"
+.Ft int
+.Fn lockmgr_xlock "struct lock *lkp" "u_int flags" "const char *file" "int line"
+.Ft int
 .Fn lockstatus "const struct lock *lkp"
 .Pp
 .Cd "options INVARIANTS"
@@ -253,12 +268,55 @@ and
 .Dv LK_TIMO_DEFAULT .
 .Pp
 The
+.Fn lockmgr_lock_flags
+function works like
+.Fn lockmgr
+but accepts explicit
+.Fa file
+and
+.Fa line
+arguments for lock tracing.
+.Pp
+The
+.Fn lockmgr_slock ,
+.Fn lockmgr_xlock ,
+and
+.Fn lockmgr_unlock
+functions are lightweight entry points that function like
+.Fn lockmgr
+for the
+.Dv LK_SHARED ,
+.Dv LK_EXCLUSIVE ,
+and
+.Dv LK_RELEASE
+operations respectively.
+They provide functionality similar to
+.Xr sx 9
+locks in that none of the additional
+.Xr lockmgr 9
+features are supported.
+Specifically, these functions do not support unlocking interlocks, the
+.Dv LK_SLEEPFAIL
+flag, or locks with shared locking disabled via
+.Dv LK_NOSHARE .
+They also accept explicit
+.Fa file
+and
+.Fa line
+arguments for lock tracing.
+.Pp
+The
 .Fn lockmgr_disown
 function switches the owner from the current thread to be
 .Dv LK_KERNPROC ,
 if the lock is already held.
 .Pp
 The
+.Fn lockmgr_disowned
+function returns true or false according to whether the lock is held by
+.Dv LK_KERNPROC .
+.Pp
+The
 .Fn lockmgr_printinfo
 function prints debugging information about the lock.
 It is used primarily by
@@ -354,6 +412,8 @@ was requested and another thread had already requested a lock upgrade.
 was set, and a sleep would have been required, or
 .Dv LK_TRYUPGRADE
 operation was not able to upgrade the lock.
+.It Bq Er EDEADLK
+A shared lock was attempted while the thread already held the exclusive lock.
 .It Bq Er ENOLCK
 .Dv LK_SLEEPFAIL
 was set and
@@ -398,6 +458,7 @@ exclusive lock, and a
 .Xr panic 9
 will be the result of trying.
 .Sh SEE ALSO
+.Xr witness 4 ,
 .Xr condvar 9 ,
 .Xr locking 9 ,
 .Xr mtx_assert 9 ,