From 99c24e2b2cdcea79a9f8b9455de87ade6bd4365f Mon Sep 17 00:00:00 2001
From: Sean Chittenden <seanc@FreeBSD.org>
Date: Wed, 12 Mar 2003 09:28:44 +0000
Subject: [PATCH] Update sendfile.2 to include a TUNING section that documents
 the various tunables that are applicable to sendfile(2).  Update tuning.7 to
 mention a reference to sendfile.2.

Approved by:	keramida
---
 lib/libc/sys/sendfile.2 | 38 ++++++++++++++++++++++++++++++++++++++
 share/man/man7/tuning.7 |  5 +++++
 2 files changed, 43 insertions(+)

diff --git a/lib/libc/sys/sendfile.2 b/lib/libc/sys/sendfile.2
index a0d823964478..fac2577926d1 100644
--- a/lib/libc/sys/sendfile.2
+++ b/lib/libc/sys/sendfile.2
@@ -106,6 +106,43 @@ The
 implementation of
 .Fn sendfile
 is "zero-copy", meaning that it has been optimized so that copying of the file data is avoided.
+.Sh TUNING
+Internally this system call uses a special
+.Xr sendfile 2
+buffer
+.Pq Fa "struct sf_buf"
+to handle sending file data to the client.
+If the sending socket is
+blocking and there are not enough sendfile buffers available,
+.Xr sendfile 2
+will block and report a state of
+.Dq sfbufa .
+If the sending socket is non-blocking and there are not enough
+sendfile buffers available, the call will block and wait for the
+necessary buffers to become available before finishing the call.
+.Pp
+The number of
+.Fa sf_buf Ns 's
+allocated should be proportional to the number of nmbclusters used to
+send data to a client via
+.Xr sendfile 2 .
+Tune accordingly to avoid blocking!
+Busy installations that make extensive use of
+.Xr sendfile 2
+may want to increase these values to be inline with their
+.Ar kern.ipc.nmbclusters
+.Pq see Xr tuning 7 for details .
+.Pp
+The number of
+.Xr sendfile 2
+buffers in use is determined at boot time by either the
+.Em kern.ipc.nsfbufs
+.Xr loader.conf 5
+variable or the
+.Em NSFBUFS
+kernel configuration tunable.
+The number of sendfile buffers scales with
+.Em kern.maxusers .
 .Sh RETURN VALUES
 .Rv -std sendfile
 .Sh ERRORS
@@ -161,6 +198,7 @@ If specified, the number of bytes successfully sent will be returned in
 .Xr open 2 ,
 .Xr send 2 ,
 .Xr socket 2 ,
+.Xr tuning 7 ,
 .Xr writev 2
 .Sh HISTORY
 The
diff --git a/share/man/man7/tuning.7 b/share/man/man7/tuning.7
index cc5081cbafd2..ec1e9244148c 100644
--- a/share/man/man7/tuning.7
+++ b/share/man/man7/tuning.7
@@ -775,6 +775,11 @@ with
 .Va kern.maxusers
 so you should not need to modify this parameter except under extreme
 circumstances.
+See the
+.Dq TUNING
+section in the
+.Xr sendfile 2
+man page for details.
 .Sh KERNEL CONFIG TUNING
 There are a number of kernel options that you may have to fiddle with in
 a large-scale system.