[PATCH manpages v2 1/2] udp.7: add UDP_SEGMENT

[Willem de Bruijn <willemdebruijn.kernel@gmail.com>]

From: Willem de Bruijn <willemb@google.com>

UDP_SEGMENT was added in commit bec1f6f69736
("udp: generate gso with UDP_SEGMENT")

    $ git describe --contains bec1f6f69736
    linux/v4.18-rc1~114^2~377^2~8

Kernel source has example code in tools/testing/selftests/net/udpgso*

Per https://www.kernel.org/doc/man-pages/patches.html,
"Describe how you obtained the information in your patch":
I am the author of the above commit and follow-ons.

Signed-off-by: Willem de Bruijn <willemb@google.com>

---

Changes v1->v2
  - semantic newlines: also break on comma and colon
  - remove bold: section number following function name
  - add bold: special macro USHRT_MAX
---
 man7/udp.7 | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/man7/udp.7 b/man7/udp.7
index 5822bc551fdf..6646c1e96bb0 100644
--- a/man7/udp.7
+++ b/man7/udp.7
@@ -204,6 +204,34 @@ portable.
 .\"     UDP_ENCAP_ESPINUDP draft-ietf-ipsec-udp-encaps-06
 .\"     UDP_ENCAP_L2TPINUDP rfc2661
 .\" FIXME Document UDP_NO_CHECK6_TX and UDP_NO_CHECK6_RX, added in Linux 3.16
+.TP
+.BR UDP_SEGMENT " (since Linux 4.18)"
+Enables UDP segmentation offload.
+Segmentation offload reduces
+.BR send (2)
+cost by transferring multiple datagrams worth of data as a single large
+packet through the kernel transmit path,
+even when that exceeds MTU.
+As late as possible,
+the large packet is split by segment size into a series of datagrams.
+This segmentation offload step is deferred to hardware if supported,
+else performed in software.
+This option takes a value between 0 and
+.BR USHRT_MAX
+that sets the segment size:
+the size of datagram payload,
+excluding the UDP header.
+The segment size must be chosen such that at most 64 datagrams are sent in
+a single call and that the datagrams after segmentation meet the same MTU
+rules that apply to datagrams sent without this option.
+Segmentation offload depends on checksum offload,
+as datagram checksums are computed after segmentation.
+The option may also be set for individual
+.BR sendmsg (2)
+calls by passing it as a
+.BR cmsg (7).
+A value of zero disables the feature.
+This option should not be used in code intended to be portable.
 .SS Ioctls
 These ioctls can be accessed using
 .BR ioctl (2).
-- 
2.39.2.722.g9855ee24e9-goog