Add conditional_head convenience function

lib/http_tools.sh

@@ -157,7 +157,7 @@ conditional_get () {
 		return 2
 	fi
 
-	local script_version="0.9"
+	local script_version="1.0"
 	local user_agent_string="HTTP Conditional GET client $script_version"
 
 	local hash
@@ -601,6 +601,59 @@ conditional_get () {
 	return 0
 }
 
+#######################################################################
+#
+# This function is analogous to the conditional_get function except
+# that this function issues a HEAD request instead of a GET request.
+# Consequently, this function always outputs the HTTP header, not
+# the response body.
+#
+# Usage: conditional_head [-vCcx] -d CACHE_DIR -T TMP_DIR HTTP_LOCATION
+#
+# Note that the command-line options and arguments are similar to
+# those of the conditional_get function. The only difference is that
+# option -F is not allowed since it effectively forces a cache write.
+# For details about available options, see the documentation for the
+# conditional_get function.
+#
+# IMPORTANNT! This function may read the header from cache (depending
+# on options) but it NEVER writes to cache.
+#
+# With no options, this function sends a conditional HEAD request to
+# the server and outputs the header received from the server on stdout.
+# The response code will be either 200 or 304. In either case, the
+# cache is not accessed.
+#
+# Option -C causes the function to read the header from cache. The
+# cached header is output on stdout if (and only if) the cache is
+# up-to-date. If the resource is not cached or the cache is not
+# up-to-date, the function quietly returns error code 1. This is
+# called Quiet Error Mode. See the documentation for the
+# conditional_get function for details.
+#
+# To determine if the cache is up-to-date, the client sends a
+# conditional HEAD request to the server. The cache is up-to-date
+# if (and only if) the server responds with 304.
+#
+# Note that the cached header (if it exists) will always indicate
+# a 200 response since a 304 response is never cached.
+#
+# Option -c reads the header directly from cache and outputs the
+# cached header on stdout. If the resource is not cached, the
+# function quietly returns error code 1 (i.e., Quiet Error Mode).
+# Note that no network access is required if option -c is used.
+#
+# Option -x adds an Accept-Encoding header to the HEAD request,
+# that is, when option -x is enabled, the client merely indicates
+# its support for HTTP Compression in the request. The server may
+# or may not indicate compression in the response header.
+#
+#######################################################################
+
+conditional_head () {
+	conditional_get -I "$@"
+}
+
 #######################################################################
 #
 # This function takes a file containing an HTTP response header and