diff options
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 | 89 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_XFERINFODATA.3 | 46 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 | 81 |
3 files changed, 216 insertions, 0 deletions
diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 new file mode 100644 index 000000000..b6100f253 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 @@ -0,0 +1,89 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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 +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HEADERFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HEADERFUNCTION \- callback that receives header data +.SH SYNOPSIS +#include <curl/curl.h> + +size_t header_callback(char *buffer, + size_t size, + size_t nitems, + void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl as soon as it has received header +data. The header callback will be called once for each header and only +complete header lines are passed on to the callback. Parsing headers is very +easy using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP +multiplied with \fInmemb\fP. Do not assume that the header line is zero +terminated! The pointer named \fIuserdata\fP is the one you set with the +\fICURLOPT_HEADERDATA(3)\fP option. This callback function must return the +number of bytes actually taken care of. If that amount differs from the amount +passed in to your function, it'll signal an error to the library. This will +cause the transfer to get aborted and the libcurl function in progress will +return \fICURL_WRITE_ERROR\fP. + +A complete HTTP header that is passed to this function can be up to +\fICURL_MAX_HTTP_HEADER\fP (100K) bytes. + +If this option is not set, or if it is set to NULL, but +\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to +accept response data will be used instead. That is, it will be the function +specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or +NULL - the default, stream-writing function. + +It's important to note that the callback will be invoked for the headers of +all responses received after initiating a request and not just the final +response. This includes all responses which occur during authentication +negotiation. If you need to operate on only the headers from the final +response, you will need to collect headers in the callback yourself and use +HTTP status lines, for example, to delimit response boundaries. + +When a server sends a chunked encoded transfer, it may contain a trailer. That +trailer is identical to a HTTP header and if such a trailer is received it is +passed to the application using this callback as well. There are several ways +to detect it being a trailer and not an ordinary header: 1) it comes after the +response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: +header among the regular response-headers mention what header(s) to expect in +the trailer. + +For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get +called with the server responses to the commands that libcurl sends. +.SH DEFAULT +Nothing. +.SH PROTOCOLS +Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3, +IMAP, SMTP and more. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_HEADERDATA "(3), " CURLOPT_WRITEFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 new file mode 100644 index 000000000..b2c170f63 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 @@ -0,0 +1,46 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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 +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_XFERINFODATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_XFERINFODATA \- custom pointer passed to the progress callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFODATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP. + +This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP. +.SH DEFAULT +The default value of this parameter is NULL. +.SH PROTOCOLS +All +.SH EXAMPLE +http://curl.haxx.se/libcurl/c/progressfunc.html +.SH AVAILABILITY +Added in 7.32.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_XFERINFOFUNCTION "(3), " CURLOPT_XFERINFOFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 new file mode 100644 index 000000000..cad81182e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 @@ -0,0 +1,81 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2014, 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 +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_XFERINFOFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_XFERINFOFUNCTION \- callback to progress meter function +.SH SYNOPSIS +#include <curl/curl.h> + +int progress_callback(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFOFUNCTION, progress_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl instead of its internal equivalent with a +frequent interval. While data is being transferred it will be called very +frequently, and during slow periods like when nothing is being transferred it +can slow down to about one call per second. + +\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not +used by libcurl but is only passed along from the application to the callback. + +The callback gets told how much data libcurl will transfer and has +transferred, in number of bytes. \fIdltotal\fP is the total number of bytes +libcurl expects to download in this transfer. \fIdlnow\fP is the number of +bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +expects to upload in this transfer. \fIulnow\fP is the number of bytes +uploaded so far. + +Unknown/unused argument values passed to the callback will be set to zero +(like if you only download data, the upload size will remain 0). Many times +the callback will be called one or more times first, before it knows the data +sizes so a program must be made to handle that. + +Returning a non-zero value from this callback will cause libcurl to abort the +transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. + +If you transfer data with the multi interface, this function will not be +called during periods of idleness unless you call the appropriate libcurl +function that performs transfers. + +\fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually +get called. +.SH DEFAULT +By default, libcurl has an internal progress meter. That's rarely wanted by +users. +.SH PROTOCOLS +All +.SH EXAMPLE +http://curl.haxx.se/libcurl/c/progressfunc.html +.SH AVAILABILITY +Added in 7.32.0. This callback replaces \fICURLOPT_PROGRESSFUNCTION(3)\fP +.SH RETURN VALUE +Returns CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_XFERINFODATA "(3), " CURLOPT_NOPROGRESS "(3), " |