libfetch: Document fetchTimeout

Document the global fetchTimeout variable, now that it works reliably.

MFC after:	1 week
Reviewed by:	op
Differential Revision:	https://reviews.freebsd.org/D57910

1 files changed, 16 insertions, 2 deletions

diff --git a/lib/libfetch/fetch.3 b/lib/libfetch/fetch.3
index 20a22a263b5b..f76df3b027bd 100644
--- a/lib/libfetch/fetch.3
+++ b/lib/libfetch/fetch.3
@@ -24,7 +24,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 22, 2026
+.Dd June 27, 2026
 .Dt FETCH 3
 .Os
 .Sh NAME
@@ -56,7 +56,8 @@
 .Nm fetchGetFTP ,
 .Nm fetchPutFTP ,
 .Nm fetchStatFTP ,
-.Nm fetchListFTP
+.Nm fetchListFTP ,
+.Nm fetchTimeout
 .Nd file transfer functions
 .Sh LIBRARY
 .Lb libfetch
@@ -64,6 +65,7 @@
 .In sys/param.h
 .In stdio.h
 .In fetch.h
+.Vt extern int fetchTimeout;
 .Ft struct url *
 .Fn fetchMakeURL "const char *scheme" "const char *host" "int port" "const char *doc" "const char *user" "const char *pwd"
 .Ft struct url *
@@ -289,6 +291,18 @@ or
 functions is read-only, and that a stream returned by one of the
 .Fn fetchPutXXX
 functions is write-only.
+.Pp
+The
+.Va fetchTimeout
+global variable can be set to the amount of time in seconds to wait
+for each network operation, including each connection attempt (keeping
+in mind that one name may resolve to multiple addresses which will
+each be tried sequentially), each read, and each write.
+Thus,
+.Va fetchTimeout
+can safely be set to a relatively low value without fear of
+prematurely terminating a long transfer; it will only kick in if the
+transfer is stalled.
 .Sh FILE SCHEME
 .Fn fetchXGetFile ,
 .Fn fetchGetFile