CURLOPT_*.3: more examples and edits

5 files changed, 70 insertions, 15 deletions

diff --git a/docs/libcurl/opts/CURLOPT_HEADER.3 b/docs/libcurl/opts/CURLOPT_HEADER.3
index 130575aaa..f5a4be8d3 100644
--- a/docs/libcurl/opts/CURLOPT_HEADER.3
+++ b/docs/libcurl/opts/CURLOPT_HEADER.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -38,9 +38,26 @@ about the protocol in use.
 
 It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header
 data separately.
+
+While named confusingly similar, \fICURLOPT_HTTPHEADER(3)\fP is used to set
+custom HTTP headers!
 .SH DEFAULT
 0
+.SH PROTOCOLS
+Most
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+
+  curl_easy_setopt(curl, CURLOPT_HEADER, 1L);
+
+  curl_easy_perform(curl);
+}
+.fi
 .SH RETURN VALUE
 Returns CURLE_OK.
 .SH "SEE ALSO"
 .BR CURLOPT_HEADERFUNCTION "(3), "
+.BR CURLOPT_HTTPHEADER "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
index 6c17d3150..4268f22b8 100644
--- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3
@@ -80,7 +80,24 @@ Nothing.
 Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3,
 IMAP, SMTP and more.
 .SH EXAMPLE
-TODO
+.nf
+static size_t header_callback(char *buffer, size_t size,
+                              size_t nitems, void *userdata)
+{
+  /* received header is nitems * size long in 'buffer' NOT ZERO TERMINATED */
+  /* 'userdata' is set with CURLOPT_WRITEDATA */
+  return nitems * size;
+}
+
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+
+  curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback);
+
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Always
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3
index 10fcf08f0..ad0134031 100644
--- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3
+++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -73,11 +73,29 @@ NULL
 .SH PROTOCOLS
 HTTP
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+
+struct curl_slist *list = NULL;
+
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+
+  list = curl_slist_append(list, "Shoesize: 10");
+  list = curl_slist_append(list, "Accept:");
+
+  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list);
+
+  curl_easy_perform(curl);
+
+  curl_slist_free_all(list); /* free the list again */
+}
+.fi
+
 .SH AVAILABILITY
 As long as HTTP is enabled
 .SH RETURN VALUE
 Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not.
 .SH "SEE ALSO"
 .BR CURLOPT_CUSTOMREQUEST "(3), " CURLOPT_HEADEROPT "(3), "
-.BR CURLOPT_PROXYHEADER "(3)"
+.BR CURLOPT_PROXYHEADER "(3), " CURLOPT_HEADER "(3)"
diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3
index 79139adf1..edd9bdbf6 100644
--- a/docs/libcurl/opts/CURLOPT_READFUNCTION.3
+++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -34,9 +34,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
 Pass a pointer to your callback function, as the prototype shows above.
 
 This callback function gets called by libcurl as soon as it needs to read data
-in order to send it to the peer. The data area pointed at by the pointer
-\fIbuffer\fP should be filled up with at most \fIsize\fP multiplied with
-\fInmemb\fP number of bytes by your function.
+in order to send it to the peer - like if you ask it to upload or post data to
+the server. The data area pointed at by the pointer \fIbuffer\fP should be
+filled up with at most \fIsize\fP multiplied with \fInmemb\fP number of bytes
+by your function.
 
 Your function must then return the actual number of bytes that it stored in
 that memory area. Returning 0 will signal end-of-file to the library and cause
@@ -75,4 +76,4 @@ was added in 7.12.1.
 This will return CURLE_OK.
 .SH "SEE ALSO"
 .BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "
-.BR CURLOPT_SEEKFUNCTION "(3), "
+.BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), "
diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3
index be07c769a..0b7a50287 100644
--- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3
+++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -46,12 +46,14 @@ By default, this is a FILE * to stdout.
 Used for all protocols.
 .SH EXAMPLE
 A common technique is to use the write callback to store the incoming data
-into a dynamically growing allocated buffer, and then this CURLOPT_WRITEDATA
-is used to point to a struct or the buffer to store data in. Like in the
-getinmemory example: http://curl.haxx.se/libcurl/c/getinmemory.html
+into a dynamically growing allocated buffer, and then this
+\fICURLOPT_WRITEDATA(3)\fP is used to point to a struct or the buffer to store
+data in. Like in the getinmemory example:
+http://curl.haxx.se/libcurl/c/getinmemory.html
 .SH AVAILABILITY
 Available in all libcurl versions. This option was formerly known as
-\fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA\fP was introduced in 7.9.7.
+\fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA(3)\fP was introduced in
+7.9.7.
 .SH RETURN VALUE
 This will return CURLE_OK.
 .SH "SEE ALSO"