doc(cgiutil): document server_url

2 files changed, 17 insertions, 1 deletions

diff --git a/TODO b/TODO
index 216db20..9c206f5 100644
--- a/TODO
+++ b/TODO
@@ -6,4 +6,4 @@ tests for xml.c | id:b9e91d022be6bdc70e7ab082743826370b713c72
 improve man3 situation | id:bf918930f6361c30f288c42894cbf9b0541c3340
 use errno instead of returning HTTP status codes in make_index | id:bfa35c48dcedbecd3a951eba243c4840178289ed
 sandboxing, at least chroot | id:f209aec893fe310c8276f64f6ff4a3208a2a4f28
-document cgiutil, timeutil and stringutil | id:fd05b97115848a8b22231a477b8252373bd87264
+document timeutil and stringutil | id:fd05b97115848a8b22231a477b8252373bd87264
diff --git a/cgiutil.h b/cgiutil.h
index b90b895..f809b25 100644
--- a/cgiutil.h
+++ b/cgiutil.h
@@ -92,4 +92,20 @@ int http_errno(int err);
  */
 int urlencode_realloc(char **input, int size);
 
+/*!
+ * @brief Returns URL of server addressed by the current CGI request
+ *
+ * server_url() uses the CGI 1.1 environment variables `SERVER_NAME`
+ * and `SERVER_PORT` to construct an URL to the server the current
+ * request is addressed to. Since CGI only reveals the HTTP version
+ * used and not wether an encrypted version of HTTP is used,
+ * server_url() will use the parameter `https` to decide which protocol
+ * identifier to prefix.
+ *
+ * The returned `char *` is dynamically allocated and must be cleaned
+ * up using `free()` before it goes out of scope.
+ *
+ * @param https if true, prefix `https://` else `http://`
+ * @return Pointer to dynamically allocated char buffer containing the URL.
+ */
 char *server_url(bool https);