From: sashan <sashan@openbsd.org>
Date: Wed, 5 Jul 2023 12:00:01 +0000 (+0000)
Subject: Document DIOCXEND in pf(4) manpage.
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=8946e15f4443bf0a417951f83c6e7ab8f5a66867;p=openbsd

Document DIOCXEND in pf(4) manpage.
With many improvements from jmc@ and kn@

OK jmc@, kn@ deraadt@
---

diff --git a/share/man/man4/pf.4 b/share/man/man4/pf.4
index 92eeb45f657..e0a506f8a1e 100644
--- a/share/man/man4/pf.4
+++ b/share/man/man4/pf.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pf.4,v 1.94 2022/11/20 16:45:10 kn Exp $
+.\"	$OpenBSD: pf.4,v 1.95 2023/07/05 12:00:01 sashan Exp $
 .\"
 .\" Copyright (C) 2001, Kjell Wooding.  All rights reserved.
 .\"
@@ -26,7 +26,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 20 2022 $
+.Dd $Mdocdate: July 5 2023 $
 .Dt PF 4
 .Os
 .Sh NAME
@@ -48,12 +48,25 @@ and retrieve statistics.
 The most commonly used functions are covered by
 .Xr pfctl 8 .
 .Pp
-Manipulations like loading a ruleset that involve more than a single
+Operations loading or reading a ruleset that involve more than a single
 .Xr ioctl 2
 call require a so-called
-.Em ticket ,
-which prevents the occurrence of
-multiple concurrent manipulations.
+.Sy ticket ,
+which allows
+.Nm
+to deal with concurrent operations.
+For certain
+.Xr ioctl 2
+commands (currently
+.Dv DIOCGETRULES )
+the number of tickets a program can get is limited.
+The programs must explicitly release their tickets using the
+.Dv DIOCXEND
+command to avoid hitting the limit.
+All tickets which are not freed by
+.Dv DIOCXEND
+are released when the program closes
+.Pa /dev/pf .
 .Pp
 Fields of
 .Xr ioctl 2
@@ -132,6 +145,9 @@ for subsequent
 calls and the number
 .Va nr
 of rules in the active ruleset.
+The ticket should be released by the
+.Dv DIOCXEND
+command.
 .It Dv DIOCGETRULE Fa "struct pfioc_rule *pr"
 Get a
 .Va rule
@@ -792,6 +808,10 @@ inactive rulesets since the last
 .Dv DIOCXBEGIN .
 .Dv DIOCXROLLBACK
 will silently ignore rulesets for which the ticket is invalid.
+.It Dv DIOCXEND Fa "u_int32_t *ticket"
+Release the ticket obtained by the
+.Dv DIOCGETRULES
+command.
 .It Dv DIOCSETHOSTID Fa "u_int32_t *hostid"
 Set the host ID, which is used by
 .Xr pfsync 4