From 902caa953d1a1507262297c806a162cbc2ce0add Mon Sep 17 00:00:00 2001
From: Mark Johnston <markj@FreeBSD.org>
Date: Sun, 8 Sep 2019 20:41:00 +0000
Subject: [PATCH] MFC r351573: Document fetchReqHTTP().

---
 lib/libfetch/Makefile |  1 +
 lib/libfetch/fetch.3  | 22 +++++++++++++++++++---
 lib/libfetch/http.c   |  3 +++
 3 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/lib/libfetch/Makefile b/lib/libfetch/Makefile
index abd5f8de23f..6990e7b1bb8 100644
--- a/lib/libfetch/Makefile
+++ b/lib/libfetch/Makefile
@@ -68,6 +68,7 @@ MLINKS+= fetch.3 fetchPutFTP.3
 MLINKS+= fetch.3 fetchPutFile.3
 MLINKS+= fetch.3 fetchPutHTTP.3
 MLINKS+= fetch.3 fetchPutURL.3
+MLINKS+= fetch.3 fetchReqHTTP.3
 MLINKS+= fetch.3 fetchStat.3
 MLINKS+= fetch.3 fetchStatFTP.3
 MLINKS+= fetch.3 fetchStatFile.3
diff --git a/lib/libfetch/fetch.3 b/lib/libfetch/fetch.3
index e04917ebcb4..e28cd55c6ef 100644
--- a/lib/libfetch/fetch.3
+++ b/lib/libfetch/fetch.3
@@ -26,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 18, 2016
+.Dd August 28, 2019
 .Dt FETCH 3
 .Os
 .Sh NAME
@@ -53,6 +53,7 @@
 .Nm fetchPutHTTP ,
 .Nm fetchStatHTTP ,
 .Nm fetchListHTTP ,
+.Nm fetchReqHTTP ,
 .Nm fetchXGetFTP ,
 .Nm fetchGetFTP ,
 .Nm fetchPutFTP ,
@@ -112,6 +113,8 @@
 .Ft struct url_ent *
 .Fn fetchListHTTP "struct url *u" "const char *flags"
 .Ft FILE *
+.Fn fetchReqHTTP "struct url *u" "const char *method" "const char *flags" "const char *content_type" "const char *body"
+.Ft FILE *
 .Fn fetchXGetFTP "struct url *u" "struct url_stat *us" "const char *flags"
 .Ft FILE *
 .Fn fetchGetFTP "struct url *u" "const char *flags"
@@ -355,9 +358,10 @@ and password "anonymous@<hostname>".
 .Sh HTTP SCHEME
 The
 .Fn fetchXGetHTTP ,
-.Fn fetchGetHTTP
-and
+.Fn fetchGetHTTP ,
 .Fn fetchPutHTTP
+and
+.Fn fetchReqHTTP
 functions implement the HTTP/1.1 protocol.
 With a little luck, there is
 even a chance that they comply with RFC2616 and RFC2617.
@@ -387,6 +391,18 @@ will send a conditional
 HTTP header to only fetch the content if it is newer than
 .Va ims_time .
 .Pp
+The function
+.Fn fetchReqHTTP
+can be used to make requests with an arbitrary HTTP verb,
+including POST, DELETE, CONNECT, OPTIONS, TRACE or PATCH.
+This can be done by setting the argument
+.Fa method
+to the intended verb, such as
+.Ql POST ,
+and
+.Fa body
+to the content.
+.Pp
 Since there seems to be no good way of implementing the HTTP PUT
 method in a manner consistent with the rest of the
 .Nm fetch
diff --git a/lib/libfetch/http.c b/lib/libfetch/http.c
index 53b9d244b96..85d624e2da3 100644
--- a/lib/libfetch/http.c
+++ b/lib/libfetch/http.c
@@ -2093,6 +2093,9 @@ fetchListHTTP(struct url *url __unused, const char *flags __unused)
 	return (NULL);
 }
 
+/*
+ * Arbitrary HTTP verb and content requests
+ */
 FILE *
 fetchReqHTTP(struct url *URL, const char *method, const char *flags,
 	const char *content_type, const char *body)
-- 
2.45.0