From 40914fd544efb8c2fa14783351d1dd17619d91fb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 17 Mar 2015 08:57:31 +0100 Subject: CURLOPT_*.3: more examples and edits --- docs/libcurl/opts/CURLOPT_HEADER.3 | 19 ++++++++++++++++++- docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 | 19 ++++++++++++++++++- docs/libcurl/opts/CURLOPT_HTTPHEADER.3 | 24 +++++++++++++++++++++--- docs/libcurl/opts/CURLOPT_READFUNCTION.3 | 11 ++++++----- docs/libcurl/opts/CURLOPT_WRITEDATA.3 | 12 +++++++----- 5 files changed, 70 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') 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, , et al. +.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, , 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" -- cgit v1.2.3