[src/trunk]: src/share/man/man4 bpf(4): assorted markup tweaks

[uwe <uwe%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f49f5abb8101
branches:  trunk
changeset: 373444:f49f5abb8101
user:      uwe <uwe%NetBSD.org@localhost>
date:      Sat Feb 11 02:52:52 2023 +0000

description:
bpf(4): assorted markup tweaks

This is mostly non-controversial changes to the cargo-culted markup.
While here - add missing .It to BIOCLOCK so that it's not buried in
the text for the previous item and comment out a paragraph about an
ancient SunOS bug.

diffstat:

 share/man/man4/bpf.4 |  271 ++++++++++++++++++++++++++++++--------------------
 1 files changed, 162 insertions(+), 109 deletions(-)

diffs (truncated from 559 to 300 lines):

diff -r 0f997d05c7f0 -r f49f5abb8101 share/man/man4/bpf.4
--- a/share/man/man4/bpf.4      Sat Feb 11 02:34:15 2023 +0000
+++ b/share/man/man4/bpf.4      Sat Feb 11 02:52:52 2023 +0000
@@ -1,6 +1,6 @@
 .\" -*- nroff -*-
 .\"
-.\"    $NetBSD: bpf.4,v 1.66 2023/02/07 01:17:41 gutteridge Exp $
+.\"    $NetBSD: bpf.4,v 1.67 2023/02/11 02:52:52 uwe Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1992, 1993, 1994
 .\"    The Regents of the University of California.  All rights reserved.
@@ -100,12 +100,12 @@
 The (third) argument to the
 .Xr ioctl 2
 should be a pointer to the type indicated.
-.Bl -tag -width indent -offset indent
-.It Dv BIOCGBLEN ( u_int )
+.Bl -tag -width Dv
+.It Dv BIOCGBLEN Pq Vt u_int
 Returns the required buffer length for reads on
 .Nm
 files.
-.It Dv BIOCSBLEN ( u_int )
+.It Dv BIOCSBLEN Pq Vt u_int
 Sets the buffer length for reads on
 .Nm
 files.
@@ -116,15 +116,15 @@
 A read call will result in
 .Er EINVAL
 if it is passed a buffer that is not this size.
-.It Dv BIOCGDLT ( u_int )
+.It Dv BIOCGDLT Pq Vt u_int
 Returns the type of the data link layer underlying the attached interface.
 .Er EINVAL
 is returned if no interface has been specified.
 The device types, prefixed with
-.Dq DLT_ ,
+.Ql DLT_ ,
 are defined in
 .In net/bpf.h .
-.It Dv BIOCGDLTLIST ( struct bpf_dltlist )
+.It Dv BIOCGDLTLIST Pq Vt struct bpf_dltlist
 Returns an array of the available types of the data link layer
 underlying the attached interface:
 .Bd -literal -offset indent
@@ -135,26 +135,29 @@
 .Ed
 .Pp
 The available types are returned in the array pointed to by the
-.Va bfl_list
-field while their length in u_int is supplied to the
-.Va bfl_len
+.Fa bfl_list
+field while their length in
+.Vt u_int
+is supplied to the
+.Fa bfl_len
 field.
 .Er ENOMEM
 is returned if there is not enough buffer space and
 .Er EFAULT
 is returned if a bad address is encountered.
 The
-.Va bfl_len
+.Fa bfl_len
 field is modified on return to indicate the actual length in u_int
 of the array returned.
 If
-.Va bfl_list
+.Fa bfl_list
 is
 .Dv NULL ,
 the
-.Va bfl_len
-field is set to indicate the required length of an array in u_int.
-.It Dv BIOCSDLT ( u_int )
+.Fa bfl_len
+field is set to indicate the required length of an array in
+.Vt u_int .
+.It Dv BIOCSDLT Pq Vt u_int
 Changes the type of the data link layer underlying the attached interface.
 .Er EINVAL
 is returned if no interface has been specified or the specified
@@ -173,30 +176,34 @@
 Flushes the buffer of incoming packets,
 and resets the statistics that are returned by
 .Dv BIOCGSTATS .
-.It Dv BIOCGETIF ( struct ifreq )
+.It Dv BIOCGETIF Pq Vt struct ifreq
 Returns the name of the hardware interface that the file is listening on.
-The name is returned in the ifr_name field of
-.Fa ifr .
+The name is returned in the
+.Fa ifr_name
+field of
+.Vt ifreq .
 All other fields are undefined.
-.It Dv BIOCSETIF ( struct ifreq )
+.It Dv BIOCSETIF Pq Vt struct ifreq
 Sets the hardware interface associated with the file.
 This command must be performed before any packets can be read.
 The device is indicated by name using the
-.Dv ifr_name
+.Fa ifr_name
 field of the
-.Fa ifreq .
+.Vt ifreq .
 Additionally, performs the actions of
 .Dv BIOCFLUSH .
-.It Dv BIOCSRTIMEOUT , BIOCGRTIMEOUT ( struct timeval )
-Sets or gets the read timeout parameter.
+.It Dv BIOCSRTIMEOUT , BIOCGRTIMEOUT Pq Vt struct timeval
+Sets or gets the
+.Dq Em read timeout
+parameter.
 The
-.Fa timeval
+.Vt timeval
 specifies the length of time to wait before timing
 out on a read request.
 This parameter is initialized to zero by
 .Xr open 2 ,
 indicating no timeout.
-.It Dv BIOCGSTATS ( struct bpf_stat )
+.It Dv BIOCGSTATS Pq Vt struct bpf_stat
 Returns the following structure of packet statistics:
 .Bd -literal -offset indent
 struct bpf_stat {
@@ -208,21 +215,23 @@
 .Ed
 .Pp
 The fields are:
-.Bl -tag -width bs_recv -offset indent
-.It Va bs_recv
+.Bl -tag -width Fa -offset indent
+.It Fa bs_recv
 the number of packets received by the descriptor since opened or reset
-(including any buffered since the last read call);
-.It Va bs_drop
+.Pq including any buffered since the last read call ;
+.It Fa bs_drop
 the number of packets which were accepted by the filter but dropped by the
 kernel because of buffer overflows
-(i.e., the application's reads aren't keeping up with the packet
-traffic); and
-.It Va bs_capt
+.Po
+i.e., the application's reads aren't keeping up with the packet traffic
+.Pc ;
+and
+.It Fa bs_capt
 the number of packets accepted by the filter.
 .El
-.It Dv BIOCIMMEDIATE ( u_int )
+.It Dv BIOCIMMEDIATE Pq Vt u_int
 Enables or disables
-.Dq immediate mode ,
+.Dq Em immediate mode ,
 based on the truth value of the argument.
 When immediate mode is enabled, reads return immediately upon packet
 reception.
@@ -232,11 +241,11 @@
 .Xr rarpd 8 ,
 which must respond to messages in real time.
 The default for a new file is off.
-.Dv BIOCLOCK
+.It Dv BIOCLOCK Pq Dv NULL
 Set the locked flag on the bpf descriptor.
 This prevents the execution of ioctl commands which could change the
 underlying operating parameters of the device.
-.It Dv BIOCSETF ( struct bpf_program )
+.It Dv BIOCSETF Pq Vt struct bpf_program
 Sets the filter program used by the kernel to discard uninteresting
 packets.
 An array of instructions and its length are passed in using the following structure:
@@ -248,26 +257,26 @@
 .Ed
 .Pp
 The filter program is pointed to by the
-.Va bf_insns
+.Fa bf_insns
 field while its length in units of
-.Sq struct bpf_insn
+.Vt struct bpf_insn
 is given by the
-.Va bf_len
+.Fa bf_len
 field.
 Also, the actions of
 .Dv BIOCFLUSH
 are performed.
 .Pp
 See section
-.Sy FILTER MACHINE
+.Sx FILTER MACHINE
 for an explanation of the filter language.
-.It Dv BIOCSETWF ( struct bpf_program )
+.It Dv BIOCSETWF Pq Vt struct bpf_program
 Sets the write filter program used by the kernel to control what type
 of packets can be written to the interface.
 See the
 .Dv BIOCSETF
 command for more information on the bpf filter program.
-.It Dv BIOCVERSION ( struct bpf_version )
+.It Dv BIOCVERSION Pq Vt struct bpf_version
 Returns the major and minor version numbers of the filter language currently
 recognized by the kernel.
 Before installing a filter, applications must check
@@ -289,16 +298,19 @@
 from
 .In net/bpf.h .
 An incompatible filter
-may result in undefined behavior (most likely, an error returned by
+may result in undefined behavior
+.Po
+most likely, an error returned by
 .Xr ioctl 2
-or haphazard packet matching).
-.It Dv BIOCSRSIG , BIOCGRSIG ( u_int )
+or haphazard packet matching
+.Pc .
+.It Dv BIOCSRSIG , BIOCGRSIG Pq Vt u_int
 Sets or gets the receive signal.
 This signal will be sent to the process or process group specified by
 .Dv FIOSETOWN .
 It defaults to
 .Dv SIGIO .
-.It Dv BIOCGHDRCMPLT , BIOCSHDRCMPLT ( u_int )
+.It Dv BIOCGHDRCMPLT , BIOCSHDRCMPLT Pq Vt u_int
 Sets or gets the status of the
 .Dq header complete
 flag.
@@ -307,7 +319,7 @@
 Set to one if the link level source address will be written,
 as provided, to the wire.
 This flag is initialized to zero by default.
-.It Dv BIOCGSEESENT , BIOCSSEESENT ( u_int )
+.It Dv BIOCGSEESENT , BIOCSSEESENT Pq Vt u_int
 These commands are obsolete but left for compatibility.
 Use
 .Dv BIOCSDIRECTION
@@ -319,7 +331,7 @@
 Set to zero to see only incoming packets on the interface.
 Set to one to see packets originating locally and remotely on the interface.
 This flag is initialized to one by default.
-.It Dv BIOCSDIRECTION , BIOCGDIRECTION Pq Li u_int
+.It Dv BIOCSDIRECTION , BIOCGDIRECTION Pq Vt u_int
 Set or get the setting determining whether incoming, outgoing, or all packets
 on the interface should be returned by BPF.
 Set to
@@ -334,7 +346,7 @@
 This setting is initialized to
 .Dv BPF_D_INOUT
 by default.
-.It Dv BIOCFEEDBACK , BIOCSFEEDBACK , BIOCGFEEDBACK ( u_int )
+.It Dv BIOCFEEDBACK , BIOCSFEEDBACK , BIOCGFEEDBACK Pq Vt u_int
 Set (or get)
 .Dq packet feedback mode .
 This allows injected packets to be fed back as input to the interface when
@@ -352,19 +364,19 @@
 .El
 .Sh STANDARD IOCTLS
 .Nm
-now supports several standard
-.Xr ioctl 2 Ns 's
+supports several standard
+.Xr ioctl 2 Ap s
 which allow the user to do async and/or non-blocking I/O to an open
 .Nm bpf
 file descriptor.
-.Bl -tag -width indent -offset indent
-.It Dv FIONREAD ( int )
+.Bl -tag -width Dv
+.It Dv FIONREAD Pq Vt int
 Returns the number of bytes that are immediately available for reading.
-.It Dv FIONBIO ( int )
+.It Dv FIONBIO Pq Vt int
 Set or clear non-blocking I/O.
 If arg is non-zero, then doing a
 .Xr read 2
-when no data is available will return -1 and
+when no data is available will return \-1 and
 .Va errno
 will be set to
 .Er EAGAIN .
@@ -372,20 +384,22 @@
 Note: setting this
 overrides the timeout set by
 .Dv BIOCSRTIMEOUT .
-.It Dv FIOASYNC ( int )
+.It Dv FIOASYNC Pq Vt int
 Enable or disable async I/O.
 When enabled (arg is non-zero), the process or process group specified by
 .Dv FIOSETOWN
-will start receiving SIGIO's when packets
-arrive.
+will start receiving
+.Dv SIGIO Ap s
+when packets arrive.