diff options
Diffstat (limited to 'docs/libcurl/opts')
233 files changed, 14430 insertions, 0 deletions
diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 new file mode 100644 index 0000000..66ceab8 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \- chunk length threshold for pipelining +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, long size); +.SH DESCRIPTION +Pass a long with a \fBsize\fP in bytes. If a pipelined connection is currently +processing a chunked (Transfer-encoding: chunked) request with a current chunk +length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP, that pipeline +will not be considered for additional requests, even if it is shorter than +\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.SH DEFAULT +The default value is 0, which means that the penalization is inactive. +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE "(3), " +.BR CURLMOPT_MAX_PIPELINE_LENGTH "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 new file mode 100644 index 0000000..203b6ac --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \- size threshold for pipelining penalty +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, long size); +.SH DESCRIPTION +Pass a long with a \fBsize\fP in bytes. If a pipelined connection is currently +processing a request with a Content-Length larger than this +\fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline will then not be +considered for additional requests, even if it is shorter than +\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.SH DEFAULT +The default value is 0, which means that the size penalization is inactive. +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 new file mode 100644 index 0000000..759ce08 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 @@ -0,0 +1,62 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_MAXCONNECTS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_MAXCONNECTS \- set size of connection cache +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAXCONNECTS, long max); +.SH DESCRIPTION +Pass a long indicating the \fBmax\fP. The set number will be used as the +maximum amount of simultaneously open connections that libcurl may keep in its +connection cache after completed use. By default libcurl will enlarge the size +for each added easy handle to make it fit 4 times the number of added easy +handles. + +By setting this option, you can prevent the cache size from growing beyond the +limit set by you. + +When the cache is full, curl closes the oldest one in the cache to prevent the +number of open connections from increasing. + +This option is for the multi handle's use only, when using the easy interface +you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option. + +See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP for limiting the number of active +connections. + +.SH DEFAULT +See DESCRIPTION +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.3 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), " +.BR CURLOPT_MAXCONNECTS "(3), " + diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 new file mode 100644 index 0000000..7522d43 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 @@ -0,0 +1,58 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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 CURLMOPT_MAX_HOST_CONNECTIONS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_MAX_HOST_CONNECTIONS \- set max number of connections to a single host +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, long max); +.SH DESCRIPTION +Pass a long to indicate \fBmax\fP. The set number will be used as the maximum +amount of simultaneously open connections to a single host (a host being the +same as a host name + port number pair). For each new session to a host, +libcurl will open a new connection up to the limit set by +\fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, the +sessions will be pending until a connection becomes available. If +\fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to pipeline if the +host is capable of it. + +The default \fBmax\fP value is 0, unlimited. However, for backwards +compatibility, setting it to 0 when \fICURLMOPT_PIPELINING(3)\fP is 1 will not +be treated as unlimited. Instead it will open only 1 connection and try to +pipeline on it. + +This set limit is also used for proxy connections, and then the proxy is +considered to be the host for which this limit counts. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_MAXCONNECTS "(3), " CURLMOPT_MAX_TOTAL_CONNECTIONS "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 new file mode 100644 index 0000000..c2adb45 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_MAX_PIPELINE_LENGTH 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_PIPELINE_LENGTH, long max); +.SH DESCRIPTION +Pass a long. The set \fBmax\fP number will be used as the maximum amount of +outstanding requests in a pipelined connection. Only used if pipelining is +enabled. + +When this limit is reached, libcurl will use another connection to the same +host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until +one of the pipelines to the host is ready to accept a request. Thus, the +total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP * +\fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. +.SH DEFAULT +5 +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 new file mode 100644 index 0000000..2783a7d --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_MAX_TOTAL_CONNECTIONS \- max simultaneously open connections +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, long amount); +.SH DESCRIPTION +Pass a long for the \fBamount\fP. The set number will be used as the maximum +number of simultaneously open connections in total using this multi +handle. For each new session, libcurl will open a new connection up to the +limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is +reached, the sessions will be pending until there are available +connections. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to +pipeline if the host is capable of it. +.SH DEFAULT +The default value is 0, which means that there is no limit. It is then simply +controlled by the number of easy handles added. +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_MAXCONNECTS "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 new file mode 100644 index 0000000..c795c48 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 @@ -0,0 +1,68 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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 CURLMOPT_PIPELINING 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_PIPELINING \- enable/disable HTTP pipelining +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bits); +.SH DESCRIPTION +Set the \fBbits\fP parameter to 1 to make libcurl use HTTP pipelining for +HTTP/1.1 transfers done using this multi handle, as far as possible. This +means that if you add a second request that can use an already existing +connection, the second request will be \&"piped" on the same connection rather +than being executed in parallel. + +When using pipelining, there are also several other related options that are +interesting to tweak and adjust to alter how libcurl spreads out requests on +different connections or not etc. + +Starting in 7.43.0, the \fBbits\fP parameter's bit 1 also has a meaning and +libcurl is now offering symbol names for the bits: +.IP CURLPIPE_NOTHING (0) +Default, which means doing no attempts at pipelining or multiplexing. +.IP CURLPIPE_HTTP1 (1) +If this bit is set, libcurl will try to pipeline HTTP/1.1 requests on +connections that are already established and in use to hosts. +.IP CURLPIPE_MULTIPLEX (2) +If this bit is set, libcurl will try to multiplex the new transfer over an +existing connection if possible. This requires HTTP/2. +.SH DEFAULT +0 (off) +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.0. Multiplex support bit added in 7.43.0. +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_MAX_PIPELINE_LENGTH "(3), " +.BR CURLMOPT_PIPELINING_SITE_BL "(3), " +.BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE "(3), " +.BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE "(3), " +.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), " +.BR CURLMOPT_MAXCONNECTS "(3), " +.BR CURLMOPT_MAX_HOST_CONNECTIONS "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 new file mode 100644 index 0000000..e3ea4b1 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 @@ -0,0 +1,60 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_PIPELINING_SERVER_BL 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_PIPELINING_SERVER_BL \- pipelining server blacklist +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SERVER_BL, char **servers); +.SH DESCRIPTION +Pass a \fBservers\fP array of char *, ending with a NULL entry. This is a list +of server types prefixes (in the Server: HTTP header) that are blacklisted +from pipelining, i.e server types that are known to not support HTTP +pipelining. The array is copied by libcurl. + +Note that the comparison matches if the Server: header begins with the string +in the blacklist, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can +both be blacklisted by having "Ninja" in the backlist. + +Pass a NULL pointer to clear the blacklist. +.SH DEFAULT +The default value is NULL, which means that there is no blacklist. +.SH PROTOCOLS +.SH EXAMPLE +.nf + server_blacklist[] = + { + "Microsoft-IIS/6.0", + "nginx/0.8.54", + NULL + }; + + curl_multi_setopt(m, CURLMOPT_PIPELINING_SERVER_BL, server_blacklist); +.fi +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_PIPELINING_SITE_BL "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 new file mode 100644 index 0000000..cf6e6e7 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_PIPELINING_SITE_BL 3 "4 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_PIPELINING_SITE_BL \- pipelining host blacklist +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING_SITE_BL, char **hosts); +.SH DESCRIPTION +Pass a \fBhosts\fP array of char *, ending with a NULL entry. This is a list +of sites that are blacklisted from pipelining, i.e sites that are known to not +support HTTP pipelining. The array is copied by libcurl. + +Pass a NULL pointer to clear the blacklist. +.SH DEFAULT +The default value is NULL, which means that there is no blacklist. +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf + site_blacklist[] = + { + "www.haxx.se", + "www.example.com:1234", + NULL + }; + + curl_multi_setopt(m, CURLMOPT_PIPELINING_SITE_BL, site_blacklist); +.fi +.SH AVAILABILITY +Added in 7.30.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_PIPELINING_SERVER_BL "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 new file mode 100644 index 0000000..bf7e6a7 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_SOCKETDATA 3 "3 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETDATA, void *pointer); +.SH DESCRIPTION +A data \fIpointer\fP to pass to the socket callback set with the +\fICURLMOPT_SOCKETFUNCTION(3)\fP option. + +This pointer will not be touched by libcurl but will only be passed in to the +socket callbacks's \fBuserp\fP argument. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.4 +.SH RETURN VALUE +Returns CURLM_OK. +.SH "SEE ALSO" +.BR CURLMOPT_SOCKETFUNCTION "(3), " curl_multi_socket_action "(3), " +.BR CURLMOPT_TIMERFUNCTION "(3) " diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 new file mode 100644 index 0000000..d64fe11 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 @@ -0,0 +1,62 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_SOCKETFUNCTION 3 "3 Nov 2014" "libcurl 7.39.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +int socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int what, /* see above */ + void *userp, /* private callback pointer */ + void *socketp); /* private socket pointer */ + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +When the \fIcurl_multi_socket_action(3)\fP function runs, it informs the +application about updates in the socket (file descriptor) status by doing +none, one, or multiple calls to the \fBsocket_callback\fP. The callback gets +status updates with changes since the previous time the callback was called. +If the given callback pointer is NULL, no callback will be called. Set the +callback's \fBuserp\fP argument with \fICURLMOPT_SOCKETDATA(3)\fP. See +\fIcurl_multi_socket_action(3)\fP for more details on how the callback is used +and should work. +.SH DEFAULT +NULL (no callback) +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.4 +.SH RETURN VALUE +Returns CURLM_OK. +.SH "SEE ALSO" +.BR CURLMOPT_SOCKETDATA "(3), " curl_multi_socket_action "(3), " +.BR CURLMOPT_TIMERFUNCTION "(3) " + diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 new file mode 100644 index 0000000..41627da --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_TIMERDATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERDATA, void *pointer); +.SH DESCRIPTION +A data \fBpointer\fP to pass to the timer callback set with the +\fICURLMOPT_TIMERFUNCTION(3)\fP option. + +This pointer will not be touched by libcurl but will only be passed in to the +timer callbacks's \fBuserp\fP argument. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_TIMERFUNCTION "(3), " CURLMOPT_SOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 new file mode 100644 index 0000000..f509b45 --- /dev/null +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 @@ -0,0 +1,101 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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 CURLMOPT_TIMERFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options" +.SH NAME +CURLMOPT_TIMERFUNCTION \- set callback to receive timeout values +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +int timer_callback(CURLM *multi, /* multi handle */ + long timeout_ms, /* see above */ + void *userp); /* private callback pointer */ + +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Certain features, such as timeouts and retries, require you to call libcurl +even when there is no activity on the file descriptors. + +Your callback function \fBtimer_callback\fP should install a non-repeating +timer with an interval of \fBtimeout_ms\fP. Each time that timer fires, call +either \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP, +depending on which interface you use. + +A \fBtimeout_ms\fP value of -1 means you should delete your timer. + +A \fBtimeout_ms\fP value of 0 means you should call +\fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP (once) as soon +as possible. + +\fBtimer_callback\fP will only be called when the \fBtimeout_ms\fP changes. + +The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP. + +The timer callback should return 0 on success, and -1 on error. This callback +can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +static gboolean timeout_cb(gpointer user_data) { + if (user_data) { + g_free(user_data); + curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL); + } + int running; + curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running); + return G_SOURCE_REMOVE; +} + +static int timerfunc(CURLM *multi, long timeout_ms, void *userp) { + guint *id = userp; + + if (id) + g_source_remove(*id); + + // -1 means we should just delete our timer. + if (timeout_ms == -1) { + g_free(id); + id = NULL; + } else { + if (!id) + id = g_new(guint, 1); + *id = g_timeout_add(timeout_ms, timeout_cb, id); + } + curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id); + return 0; +} + +curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); +.fi +.SH AVAILABILITY +Added in 7.16.0 +.SH RETURN VALUE +Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLMOPT_TIMERDATA "(3), " CURLMOPT_SOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 new file mode 100644 index 0000000..a51c86a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_ACCEPTTIMEOUT_MS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_ACCEPTTIMEOUT_MS \- timeout waiting for FTP server to connect back +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms); +.SH DESCRIPTION +Pass a long telling libcurl the maximum number of milliseconds to wait for a +server to connect back to libcurl when an active FTP connection is used. +.SH DEFAULT +If no timeout is set, the internal default of 60000 (one minute) will be used. +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.24.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 new file mode 100644 index 0000000..376799a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 @@ -0,0 +1,63 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_ACCEPT_ENCODING 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_ACCEPT_ENCODING \- enables automatic decompression of HTTP downloads +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc); +.SH DESCRIPTION +Pass a char * argument specifying what encoding you'd like. + +Sets the contents of the Accept-Encoding: header sent in a HTTP request, and +enables decoding of a response when a Content-Encoding: header is received. +Three encodings are supported: \fIidentity\fP, which does nothing, +\fIdeflate\fP which requests the server to compress its response using the +zlib algorithm, and \fIgzip\fP which requests the gzip algorithm. + +If a zero-length string is set like "", then an Accept-Encoding: header +containing all built-in supported encodings is sent. + +You can also opt to just include the Accept-Encoding: header in your request +with \fICURLOPT_HTTPHEADER(3)\fP but then there will be no automatic +decompressing when receiving data. + +This is a request, not an order; the server may or may not do it. This option +must be set (to any non-NULL value) or else any unsolicited encoding done by +the server is ignored. See the special file lib/README.encoding for further +details. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option was called CURLOPT_ENCODING before 7.21.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_TRANSFER_ENCODING "(3), " CURLOPT_HTTPHEADER "(3), " +.BR CURLOPT_HTTP_CONTENT_DECODING "(3), " diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 new file mode 100644 index 0000000..510e3b3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_ADDRESS_SCOPE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_ADDRESS_SCOPE \- set scope for local IPv6 addresses +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ADDRESS_SCOPE, long scope); +.SH DESCRIPTION +Pass a long specifying the scope_id value to use when connecting to IPv6 +link-local or site-local addresses. +.SH DEFAULT +0 +.SH PROTOCOLS +All, when using IPv6 +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_APPEND.3 b/docs/libcurl/opts/CURLOPT_APPEND.3 new file mode 100644 index 0000000..0352296 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_APPEND.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_APPEND 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_APPEND \- enable appending to the remote file +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_APPEND, long append); +.SH DESCRIPTION +A parameter set to 1 tells the library to append to the remote file instead of +overwrite it. This is only useful when uploading to an FTP site. +.SH DEFAULT +0 +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option was known as CURLOPT_FTPAPPEND up to 7.16.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_DIRLISTONLY "(3), " CURLOPT_RESUME_FROM "(3), " diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 new file mode 100644 index 0000000..f8d5668 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_AUTOREFERER 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_AUTOREFERER \- automatically update the referer header +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AUTOREFERER, long autorefer); +.SH DESCRIPTION +Pass a parameter set to 1 to enable this. When enabled, libcurl will +automatically set the Referer: header field in HTTP requests where it follows +a Location: redirect. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_REFERER "(3), " CURLOPT_FOLLOWLOCATION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 new file mode 100644 index 0000000..9e31ae9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_BUFFERSIZE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_BUFFERSIZE \- set preferred receive buffer size +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_BUFFERSIZE, long size); +.SH DESCRIPTION +Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive +buffer in libcurl. The main point of this would be that the write callback +gets called more often and with smaller chunks. This is just treated as a +request, not an order. You cannot be guaranteed to actually get the given +size. + +This size is by default set as big as possible (\fICURL_MAX_WRITE_SIZE\fP), so +it only makes sense to use this option if you want it smaller. +.SH DEFAULT +CURL_MAX_WRITE_SIZE +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.10 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAX_RECV_SPEED "(3), " CURLOPT_WRITEFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3 new file mode 100644 index 0000000..85c9ba3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CAINFO.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CAINFO 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CAINFO \- path to Certificate Authority (CA) bundle +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAINFO, char *path); +.SH DESCRIPTION +Pass a char * to a zero terminated string naming a file holding one or more +certificates to verify the peer with. + +If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server's certificate, \fICURLOPT_CAINFO(3)\fP need not even indicate an +accessible file. + +This option is by default set to the system path where libcurl's cacert bundle +is assumed to be stored, as established at build time. + +If curl is built against the NSS SSL library, the NSS PEM PKCS#11 module +(libnsspem.so) needs to be available for this option to work properly. +.SH DEFAULT +Built-in system specific +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +For SSL engines that don't support certificate files the CURLOPT_CAINFO option +is ignored. Refer to http://curl.haxx.se/docs/ssl-compared.html +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_CAPATH "(3), " +.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.3 b/docs/libcurl/opts/CURLOPT_CAPATH.3 new file mode 100644 index 0000000..6695f9f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CAPATH.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CAPATH 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CAPATH \- specify directory holding CA certificates +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CAPATH, char *capath); +.SH DESCRIPTION +Pass a char * to a zero terminated string naming a directory holding multiple +CA certificates to verify the peer with. If libcurl is built against OpenSSL, +the certificate directory must be prepared using the openssl c_rehash utility. +This makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. + +The \fICURLOPT_CAPATH(3)\fP function apparently does not work in Windows due +to some limitation in openssl. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option is supported by the OpenSSL, GnuTLS and PolarSSL backends. The NSS +backend provides the option only for backward compatibility. +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, and CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_CAINFO "(3), " +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.3 b/docs/libcurl/opts/CURLOPT_CERTINFO.3 new file mode 100644 index 0000000..a508b86 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_CERTINFO 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CERTINFO \- request SSL certificate information +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CERTINFO, long certinfo); +.SH DESCRIPTION +Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With +this enabled, libcurl will extract lots of information and data about the +certificates in the certificate chain used in the SSL connection. This data may +then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and its +option \fICURLINFO_CERTINFO\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +All TLS-based +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option is supported by the OpenSSL, GnuTLS, NSS and GSKit backends. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CAINFO "(3), " CURLOPT_SSL_VERIFYPEER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 new file mode 100644 index 0000000..4dd7907 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 @@ -0,0 +1,69 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CHUNK_BGN_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcardmatch +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +long chunk_bgn_callback(const void *transfer_info, void *ptr, + int remains); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_BGN_FUNCTION, + chunk_bgn_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl before a part of the stream is +going to be transferred (if the transfer supports chunks). + +The \fItransfer_info\fP pointer will point to a struct curl_fileinfo with +details about the file that is about to get transferred. + +This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP +option for now. + +The target of transfer_info parameter is a "feature depended" structure. For +the FTP wildcard download, the target is curl_fileinfo structure (see +\fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by +\fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks +remaining per the transfer. If the feature is not available, the parameter has +zero value. + +Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, +\fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or +\fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +This was added in 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CHUNK_END_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 new file mode 100644 index 0000000..4d0ff3d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CHUNK_DATA 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CHUNK_DATA \- custom pointer to the FTP chunk callbacks +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_DATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP that will be untouched by libcurl and passed as the ptr +argument to the \fICURL_CHUNK_BGN_FUNCTION(3)\fP and +\fICURL_CHUNK_END_FUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CHUNK_BGN_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 new file mode 100644 index 0000000..64f829c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CHUNK_END_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcardmatch +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +long chunk_end_callback(void *ptr); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CHUNK_END_FUNCTION, + chunk_end_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 a part of the stream has been +transferred (or skipped). + +Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or +\fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_WILDCARDMATCH "(3), " CURLOPT_CHUNK_BGN_FUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 new file mode 100644 index 0000000..b8af353 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CLOSESOCKETDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CLOSESOCKETDATA \- pointer passed to the socket close callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +argument in the closesocket callback set with +\fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. +.SH DEFAULT +The default value of this parameter is NULL. +.SH PROTOCOLS +All except file: +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CLOSESOCKETFUNCTION "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 new file mode 100644 index 0000000..2594b16 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CLOSESOCKETFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement function +.SH SYNOPSIS +#include <curl/curl.h> + +int closesocket_callback(void *clientp, curl_socket_t item); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETFUNCTION, closesocket_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl instead of the \fIclose(3)\fP or +\fIclosesocket(3)\fP call when sockets are closed (not for any other file +descriptors). This is pretty much the reverse to the +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP option. Return 0 to signal success and 1 +if there was an error. + +The \fIclientp\fP pointer is set with +\fICURLOPT_CLOSESOCKETDATA(3)\fP. \fIitem\fP is the socket libcurl wants to be +closed. +.SH DEFAULT +By default libcurl uses the standard socket close function. +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CLOSESOCKETDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 new file mode 100644 index 0000000..7f28e63 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 @@ -0,0 +1,60 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_CONNECTTIMEOUT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONNECTTIMEOUT \- timeout for the connect phase +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT, long timeout); +.SH DESCRIPTION +Pass a long. It should contain the maximum time in seconds that you allow the +connection phase to the server to take. This only limits the connection +phase, it has no impact once it has connected. Set to zero to switch to the +default built-in connection timeout - 300 seconds. See also the +\fICURLOPT_TIMEOUT(3)\fP option. + +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL(3)\fP is set. +.SH DEFAULT +300 +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* complete connection within 10 seconds */ + curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 new file mode 100644 index 0000000..d81118e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 @@ -0,0 +1,60 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_CONNECTTIMEOUT_MS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONNECTTIMEOUT_MS \- timeout for the connect phase +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS, long timeout); +.SH DESCRIPTION +Pass a long. It should contain the maximum time in milliseconds that you allow +the connection phase to the server to take. This only limits the connection +phase, it has no impact once it has connected. Set to zero to switch to the +default built-in connection timeout - 300 seconds. See also the +\fICURLOPT_TIMEOUT_MS(3)\fP option. + +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL(3)\fP is set. +.SH DEFAULT +300000 +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* complete connection within 10000 milliseconds */ + curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10000L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 new file mode 100644 index 0000000..afb3cfd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CONNECT_ONLY 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONNECT_ONLY \- stop when connected to target server +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECT_ONLY, long only); +.SH DESCRIPTION +Pass a long. If the parameter equals 1, it tells the library to perform all +the required proxy authentication and connection setup, but no data transfer, +and then return. + +The option can be used to simply test a connection to a server, but is more +useful when used with the \fICURLINFO_LASTSOCKET\fP option to +\fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then +the application can obtain the most recently used socket for special data +transfers. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP, SMTP, POP3 and IMAP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 new file mode 100644 index 0000000..ebc4d77 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 @@ -0,0 +1,82 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CONV_FROM_NETWORK_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION, + conv_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. +The amount of data to convert is indicated by the \fIlength\fP parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. \fICURLE_OK\fP must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, +should be returned if an error was encountered. + +\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP converts to host encoding from the +network encoding. It is used when commands or ASCII data are received over +the network. + +If you set a callback pointer to NULL, or don't set it at all, the built-in +libcurl iconv functions will be used. If HAVE_ICONV was not defined when +libcurl was built, and no callback has been established, conversion will +return the CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: + + \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" + +The iconv code in libcurl will default the network and UTF8 codeset names as +follows: + + \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + + \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" + +You will need to override these definitions if they are different on your +system. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP, SMTP, IMAP, POP3 +.SH EXAMPLE +TODO +.SH AVAILABILITY +Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CONV_TO_NETWORK_FUNCTION "(3), " CURLOPT_CONV_FROM_UTF8_FUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 new file mode 100644 index 0000000..682e1c5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.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_CONV_FROM_UTF8_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONV_FROM_UTF8_FUNCTION \- convert data from UTF8 to host encoding +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, + conv_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. +The amount of data to convert is indicated by the \fIlength\fP parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. \fICURLE_OK\fP must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, +should be returned if an error was encountered. + +\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP converts to host encoding from UTF8 +encoding. It is required only for SSL processing. + +If you set a callback pointer to NULL, or don't set it at all, the built-in +libcurl iconv functions will be used. If HAVE_ICONV was not defined when +libcurl was built, and no callback has been established, conversion will +return the CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: + + \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" + +The iconv code in libcurl will default the network and UTF8 codeset names as +follows: + + \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + + \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" + +You will need to override these definitions if they are different on your +system. +.SH DEFAULT +NULL +.SH PROTOCOLS +TLS-based protocols. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CONV_TO_NETWORK_FUNCTION "(3), " CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 new file mode 100644 index 0000000..e8817f8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 @@ -0,0 +1,82 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CONV_TO_NETWORK_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode conv_callback(char *ptr, size_t length); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, + conv_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +Applies to non-ASCII platforms. \fIcurl_version_info(3)\fP will return the +CURL_VERSION_CONV feature bit set if this option is provided. + +The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. +The amount of data to convert is indicated by the \fIlength\fP parameter. The +converted data overlays the input data in the buffer pointed to by the ptr +parameter. \fICURLE_OK\fP must be returned upon successful conversion. A +CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, +should be returned if an error was encountered. + +\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP converts from host encoding to the +network encoding. It is used when commands or ASCII data are sent over the +network. + +If you set a callback pointer to NULL, or don't set it at all, the built-in +libcurl iconv functions will be used. If HAVE_ICONV was not defined when +libcurl was built, and no callback has been established, conversion will +return the CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: + + \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" + +The iconv code in libcurl will default the network and UTF8 codeset names as +follows: + + \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + + \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" + +You will need to override these definitions if they are different on your +system. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP, SMTP, IMAP, POP3 +.SH EXAMPLE +TODO +.SH AVAILABILITY +Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), " CURLOPT_CONV_TO_UTF8_FUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.3 b/docs/libcurl/opts/CURLOPT_COOKIE.3 new file mode 100644 index 0000000..a390135 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIE.3 @@ -0,0 +1,80 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_COOKIE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_COOKIE \- set contents of HTTP Cookie header +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIE, char *cookie); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It will be used to +set a cookie in the HTTP request. The format of the string should be +NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie +should contain. + +If you need to set multiple cookies, set them all using a single option +concatenated like this: "name1=content1; name2=content2;" etc. + +This option sets the cookie header explicitly in the outgoing request(s). If +multiple requests are done due to authentication, followed redirections or +similar, they will all get this cookie passed on. + +The cookies set by this option are separate from the internal cookie storage +held by the cookie engine and will not be modified by it. If you enable the +cookie engine and either you've imported a cookie of the same name (e.g. 'foo') +or the server has set one, it will have no effect on the cookies you set here. +A request to the server will send both the 'foo' held by the cookie engine and +the 'foo' held by this option. To set a cookie that is instead held by the +cookie engine and can be modified by the server use +\fICURLOPT_COOKIELIST(3)\fP. + +Using this option multiple times will only make the latest string override the +previous ones. + +This option will not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP +or \fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies +automatically. +.SH DEFAULT +NULL, no cookies +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + curl_easy_setopt(curl, CURLOPT_COOKIE, "tool=curl; fun=yes;"); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +If HTTP is enabled +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIELIST "(3), " +.BR CURLOPT_HTTPHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 new file mode 100644 index 0000000..a4c3b02 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 @@ -0,0 +1,59 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_COOKIEFILE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_COOKIEFILE \- file name to read cookies from +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEFILE, char *filename); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It should point to +the file name of your file holding cookie data to read. The cookie data can be +in either the old Netscape / Mozilla cookie data format or just regular +HTTP-style headers dumped to a file. + +It also enables the cookie engine, making libcurl parse and send cookies on +subsequent requests with this handle. + +Given an empty or non-existing file or by passing the empty string ("") to +this option, you can enable the cookie engine without reading any initial +cookies. + +This option only \fBreads\fP cookies. To make libcurl write cookies to file, +see \fICURLOPT_COOKIEJAR(3)\fP. + +If you use this option multiple times, you just add more files to read. +Subsequent files will add more cookies. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +As long as HTTP is supported +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_COOKIE "(3), " CURLOPT_COOKIEJAR "(3), " diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 new file mode 100644 index 0000000..936d4d8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 @@ -0,0 +1,58 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_COOKIEJAR 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_COOKIEJAR \- file name to store cookies to +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename); +.SH DESCRIPTION +Pass a \fIfilename\fP as char *, zero terminated. This will make libcurl write +all internally known cookies to the specified file when +\fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be +created. Specify "-" as filename to instead have the cookies written to +stdout. Using this option also enables cookies for this session, so if you for +example follow a location it will make matching cookies get sent accordingly. + +Note that libcurl doesn't read any cookies from the cookie jar. If you want to +read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. + +If the cookie jar file can't be created or written to (when the +\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an +error for this. Using \fICURLOPT_VERBOSE(3)\fP or +\fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the +only visible feedback you get about this possibly lethal situation. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), " CURLOPT_COOKIELIST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 new file mode 100644 index 0000000..937c79d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 @@ -0,0 +1,120 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_COOKIELIST 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIELIST, + char *cookie); +.SH DESCRIPTION +Pass a char * to a \fIcookie\fP string. + +Such a cookie can be either a single line in Netscape / Mozilla format or just +regular HTTP-style header (Set-Cookie: ...) format. This will also enable the +cookie engine. This adds that single cookie to the internal cookie store. + +If you use the Set-Cookie format and don't specify a domain then the cookie +is sent for any domain and will not be modified. If a server sets a cookie of +the same name (or maybe you've imported one) then both will be sent on a future +transfer to that server, likely not what you intended. Either set a domain in +Set-Cookie (doing that will include sub domains) or use the Netscape format as +shown in EXAMPLE. + +Starting in 7.43.0 the aforementioned any-domain cookies will not appear in the +lists exported by \fICURLINFO_COOKIELIST(3)\fP and \fICURLOPT_COOKIEJAR(3)\fP. + +Additionally, there are commands available that perform actions if you pass in +these exact strings: +.IP ALL +erases all cookies held in memory + +.IP SESS +erases all session cookies held in memory + +.IP FLUSH +writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP + +.IP RELOAD +loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP + +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +/* This example shows an inline import of a cookie in Netscape format. +You can set the cookie as HttpOnly to prevent XSS attacks by prepending +#HttpOnly_ to the hostname. That may be useful if the cookie will later +be imported by a browser. +*/ + +#define SEP "\\t" /* Tab separates the fields */ + +char *my_cookie = + "example.com" /* Hostname */ + SEP "FALSE" /* Include subdomains */ + SEP "/" /* Path */ + SEP "FALSE" /* Secure */ + SEP "0" /* Expiry in epoch time format. 0 == Session */ + SEP "foo" /* Name */ + SEP "bar"; /* Value */ + +/* my_cookie is imported immediately via CURLOPT_COOKIELIST. +*/ +curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); + +/* The list of cookies in cookies.txt will not be imported until right +before a transfer is performed. Cookies in the list that have the same +hostname, path and name as in my_cookie are skipped. That is because +libcurl has already imported my_cookie and it's considered a "live" +cookie. A live cookie won't be replaced by one read from a file. +*/ +curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */ + +/* Cookies are exported after curl_easy_cleanup is called. The server +may have added, deleted or modified cookies by then. The cookies that +were skipped on import are not exported. +*/ +curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); /* export */ + +res = curl_easy_perform(curl); /* cookies imported from cookies.txt */ + +curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ +.fi +.SH AVAILABILITY +ALL was added in 7.14.1 + +SESS was added in 7.15.4 + +FLUSH was added in 7.17.1 + +RELOAD was added in 7.39.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIEJAR "(3), " CURLOPT_COOKIE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 new file mode 100644 index 0000000..0d56076 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_COOKIESESSION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_COOKIESESSION \- start a new cookie session +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIESESSION, long init); +.SH DESCRIPTION +Pass a long set to 1 to mark this as a new cookie "session". It will force +libcurl to ignore all cookies it is about to load that are "session cookies" +from the previous session. By default, libcurl always stores and loads all +cookies, independent if they are session cookies or not. Session cookies are +cookies without expiry date and they are meant to be alive and existing for +this "session" only. + +A "session" is usually defined in browser land for as long as you have your +browser up, more or less. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_COOKIEFILE "(3), " CURLOPT_COOKIE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 new file mode 100644 index 0000000..d35aebd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_COPYPOSTFIELDS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_COPYPOSTFIELDS \- have libcurl copy data to POST +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COPYPOSTFIELDS, char *data); +.SH DESCRIPTION +Pass a char * as parameter, which should be the full \fIdata\fP to post in a +HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but +the original data is instead copied by the library, allowing the application +to overwrite the original data after setting this option. + +Because data are copied, care must be taken when using this option in +conjunction with \fICURLOPT_POSTFIELDSIZE(3)\fP or +\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP: If the size has not been set prior to +\fICURLOPT_COPYPOSTFIELDS(3)\fP, the data is assumed to be a zero terminated +string; else the stored size informs the library about the byte count to +copy. In any case, the size must not be changed after +\fICURLOPT_COPYPOSTFIELDS(3)\fP, unless another \fICURLOPT_POSTFIELDS(3)\fP or +\fICURLOPT_COPYPOSTFIELDS(3)\fP option is issued. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + char local_buffer[1024]="data to send"; + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the data to copy from the buffer and send in the request */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* send data from the local stack */ + curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POSTFIELDSIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CRLF.3 b/docs/libcurl/opts/CURLOPT_CRLF.3 new file mode 100644 index 0000000..32d8b79 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CRLF.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CRLF 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CRLF \- enable/disable CRLF conversion +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLF, long conv); +.SH DESCRIPTION +Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to +CRLF newlines on transfers. Disable this option again by setting the value to +0 (zero). + +This is a legacy option of questionable use. +.SH DEFAULT +0 +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +SMTP since 7.40.0, other protocols since they were introduced +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_CONV_FROM_NETWORK_FUNCTION "(3), " CURLOPT_CONV_TO_NETWORK_FUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.3 b/docs/libcurl/opts/CURLOPT_CRLFILE.3 new file mode 100644 index 0000000..adc0e99 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.3 @@ -0,0 +1,60 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CRLFILE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CRLFILE \- specify a Certificate Revocation List file +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CRLFILE, char *file); +.SH DESCRIPTION +Pass a char * to a zero terminated string naming a \fIfile\fP with the +concatenation of CRL (in PEM format) to use in the certificate validation that +occurs during the SSL exchange. + +When curl is built to use NSS or GnuTLS, there is no way to influence the use +of CRL passed to help in the verification process. When libcurl is built with +OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both +set, requiring CRL check against all the elements of the certificate chain if +a CRL file is passed. + +This option makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. + +A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the +option. It is returned when the SSL exchange fails because the CRL file cannot +be loaded. A failure in certificate verification due to a revocation +information found in the CRL does not trigger this specific error. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS-based protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 new file mode 100644 index 0000000..fd33118 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 @@ -0,0 +1,95 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_CUSTOMREQUEST 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_CUSTOMREQUEST \- custom string for request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *request); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. + +When you change the request method by setting \fBCURLOPT_CUSTOMREQUEST(3)\fP +to something, you don't actually change how libcurl behaves or acts in regards +to the particular request method, it will only change the actual string sent +in the request. + +Restore to the internal default by setting this to NULL. + +This option can be used to specify the request: +.IP HTTP +Instead of GET or HEAD when performing HTTP based requests. This is +particularly useful, for example, for performing a HTTP DELETE request. + +For example: + +When you tell libcurl to do a HEAD request, but then specify a GET though a +custom request libcurl will still act as if it sent a HEAD. To switch to a +proper HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use +\fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper +GET use \fICURLOPT_HTTPGET(3)\fP. + +Many people have wrongly used this option to replace the entire request with +their own, including multiple headers and POST contents. While that might work +in many cases, it will cause libcurl to send invalid requests and it could +possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and +\fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP +to replace or extend the set of headers sent by libcurl. Use +\fICURLOPT_HTTP_VERSION(3)\fP to change HTTP version. + +.IP FTP +Instead of LIST and NLST when performing FTP directory listings. +.IP IMAP +Instead of LIST when issuing IMAP based requests. +.IP POP3 +Instead of LIST and RETR when issuing POP3 based requests. + +For example: + +When you tell libcurl to use a custom request it will behave like a LIST or +RETR command was sent where it expects data to be returned by the server. As +such \fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as +DELE and NOOP for example. +.IP SMTP +Instead of a HELP or VRFY when issuing SMTP based requests. + +For example: + +Normally a multiline response is returned which can be used, in conjunction +with \fICURLOPT_MAIL_RCPT(3)\fP, to specify an EXPN request. If the +\fICURLOPT_NOBODY(3)\fP option is specified then the request can be used to +issue NOOP and RSET commands. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP, FTP, IMAP, POP3 and SMTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +IMAP is supported since 7.30.0, POP3 since 7.26.0 and SMTP since 7.34.0. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_HTTPHEADER "(3), " CURLOPT_NOBODY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 new file mode 100644 index 0000000..ebdb0c5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DEBUGDATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DEBUGDATA \- custom pointer for debug callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGDATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP to whatever you want passed in to your +\fICURLOPT_DEBUGFUNCTION(3)\fP in the last void * argument. This pointer is +not used by libcurl, it is only passed to the callback. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +http://curl.haxx.se/libcurl/c/debug.html +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 new file mode 100644 index 0000000..6c4721b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 @@ -0,0 +1,184 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DEBUGFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DEBUGFUNCTION \- debug callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +typedef enum { + CURLINFO_TEXT = 0, + CURLINFO_HEADER_IN, /* 1 */ + CURLINFO_HEADER_OUT, /* 2 */ + CURLINFO_DATA_IN, /* 3 */ + CURLINFO_DATA_OUT, /* 4 */ + CURLINFO_SSL_DATA_IN, /* 5 */ + CURLINFO_SSL_DATA_OUT, /* 6 */ + CURLINFO_END +} curl_infotype; + +int debug_callback(CURL *handle, + curl_infotype type, + char *data, + size_t size, + void *userptr); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGFUNCTION, + debug_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +\fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when +\fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug +information, as specified in the \fItype\fP argument. This function must +return 0. The \fIdata\fP pointed to by the char * passed to this function WILL +NOT be zero terminated, but will be exactly of the \fIsize\fP as told by the +\fIsize\fP argument. + +The \fIuserptr\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP. + +Available curl_infotype values: +.IP CURLINFO_TEXT +The data is informational text. +.IP CURLINFO_HEADER_IN +The data is header (or header-like) data received from the peer. +.IP CURLINFO_HEADER_OUT +The data is header (or header-like) data sent to the peer. +.IP CURLINFO_DATA_IN +The data is protocol data received from the peer. +.IP CURLINFO_DATA_OUT +The data is protocol data sent to the peer. +.IP CURLINFO_SSL_DATA_OUT +The data is SSL/TLS (binary) data sent to the peer. +.IP CURLINFO_SSL_DATA_IN +The data is SSL/TLS (binary) data received from the peer. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +static +void dump(const char *text, + FILE *stream, unsigned char *ptr, size_t size) +{ + size_t i; + size_t c; + unsigned int width=0x10; + + fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\n", + text, (long)size, (long)size); + + for(i=0; i<size; i+= width) { + fprintf(stream, "%4.4lx: ", (long)i); + + /* show hex to the left */ + for(c = 0; c < width; c++) { + if(i+c < size) + fprintf(stream, "%02x ", ptr[i+c]); + else + fputs(" ", stream); + } + + /* show data on the right */ + for(c = 0; (c < width) && (i+c < size); c++) + fputc(ptr[i+c]>=0x20) && (ptr[i+c]<0x80)?ptr[i+c]:'.', stream); + + fputc('\n', stream); /* newline */ + } +} + +static +int my_trace(CURL *handle, curl_infotype type, + char *data, size_t size, + void *userp) +{ + const char *text; + (void)handle; /* prevent compiler warning */ + + switch (type) { + case CURLINFO_TEXT: + fprintf(stderr, "== Info: %s", data); + default: /* in case a new one is introduced to shock us */ + return 0; + + case CURLINFO_HEADER_OUT: + text = "=> Send header"; + break; + case CURLINFO_DATA_OUT: + text = "=> Send data"; + break; + case CURLINFO_SSL_DATA_OUT: + text = "=> Send SSL data"; + break; + case CURLINFO_HEADER_IN: + text = "<= Recv header"; + break; + case CURLINFO_DATA_IN: + text = "<= Recv data"; + break; + case CURLINFO_SSL_DATA_IN: + text = "<= Recv SSL data"; + break; + } + + dump(text, stderr, (unsigned char *)data, size); + return 0; +} + +int main(void) +{ + CURL *curl; + CURLcode res; + + curl = curl_easy_init(); + if(curl) { + curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); + + /* the DEBUGFUNCTION has no effect until we enable VERBOSE */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); + res = curl_easy_perform(curl); + /* Check for errors */ + if(res != CURLE_OK) + fprintf(stderr, "curl_easy_perform() failed: %s\n", + curl_easy_strerror(res)); + + /* always cleanup */ + curl_easy_cleanup(curl); + } + return 0; +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_DEBUGDATA "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 new file mode 100644 index 0000000..a81f907 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DIRLISTONLY 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DIRLISTONLY \- ask for names only in a directory listing +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DIRLISTONLY, long listonly); +.SH DESCRIPTION +For FTP and SFTP based URLs a parameter set to 1 tells the library to list the +names of files in a directory, rather than performing a full directory listing +that would normally include file sizes, dates etc. + +For POP3 a parameter of 1 tells the library to list the email message or +messages on the POP3 server. This can be used to change the default behaviour +of libcurl, when combined with a URL that contains a message ID, to perform a +"scan listing" which can then be used to determine the size of an email. + +Note: For FTP this causes a NLST command to be sent to the FTP server. Beware +that some FTP servers list only files in their response to NLST; they might not +include subdirectories and symbolic links. + +Setting this option to 1 also implies a directory listing even if the URL +doesn't end with a slash, which otherwise is necessary. + +Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it +will effectively break that feature then. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +FTP, SFTP and POP3 +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported +since 7.21.5. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CUSTOMREQUEST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 new file mode 100644 index 0000000..9332780 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DNS_CACHE_TIMEOUT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DNS_CACHE_TIMEOUT \- set life-time for DNS cache entries +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_CACHE_TIMEOUT, long age); +.SH DESCRIPTION +Pass a long, this sets the timeout in seconds. Name resolves will be kept in +memory and used for this number of seconds. Set to zero to completely disable +caching, or set to -1 to make the cached entries remain forever. By default, +libcurl caches this info for 60 seconds. + +The name resolve functions of various libc implementations don't re-read name +server information unless explicitly told so (for example, by calling +\fIres_init(3)\fP). This may cause libcurl to keep using the older server even +if DHCP has updated the server info, and this may look like a DNS cache issue +to the casual libcurl-app user. + +Note that DNS entries have a "TTL" property but libcurl doesn't use that. This +DNS cache timeout is entirely speculative that a name will resolve to the same +address for a certain small amount of time into the future. +.SH DEFAULT +60 +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_DNS_USE_GLOBAL_CACHE "(3), " CURLOPT_DNS_SERVERS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 new file mode 100644 index 0000000..c33d791 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DNS_INTERFACE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DNS_INTERFACE \- set interface to speak DNS over +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_INTERFACE, char *ifname); +.SH DESCRIPTION +Pass a char * as parameter. Set the name of the network interface that the DNS +resolver should bind to. This must be an interface name (not an address). Set +this option to NULL to use the default setting (don't bind to a specific +interface). +.SH DEFAULT +NULL +.SH PROTOCOLS +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.33.0. This option also requires that libcurl was built with a +resolver backend that supports this operation. The c-ares backend is the only +such one. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +or CURLE_NOT_BUILT_IN if support was disabled at compile-time. +.SH "SEE ALSO" +.BR CURLOPT_DNS_SERVERS "(3), " CURLOPT_DNS_LOCAL_IP4 "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 new file mode 100644 index 0000000..f5db645 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DNS_LOCAL_IP4 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DNS_LOCAL_IP4 \- IPv4 address to bind DNS resolves to +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP4, char *address); +.SH DESCRIPTION +Set the local IPv4 \fIaddress\fP that the resolver should bind to. The +argument should be of type char * and contain a single numerical IPv4 address +as a string. Set this option to NULL to use the default setting (don't bind +to a specific IP address). +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +Added in 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile-time, or +CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. +.SH "SEE ALSO" +.BR CURLOPT_DNS_INTERFACE "(3), " CURLOPT_DNS_LOCAL_IP4 "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 new file mode 100644 index 0000000..56865bb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DNS_LOCAL_IP6 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DNS_LOCAL_IP6 \- IPv6 address to bind DNS resolves to +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_LOCAL_IP6, char *address); +.SH DESCRIPTION +Set the local IPv6 \fIaddress\fP that the resolver should bind to. The +argument should be of type char * and contain a single IPv6 address as a +string. Set this option to NULL to use the default setting (don't bind to a +specific IP address). +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +Added in 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile-time, or +CURLE_BAD_FUNCTION_ARGUMENT when given a bad address. +.SH "SEE ALSO" +.BR CURLOPT_DNS_INTERFACE "(3), " CURLOPT_DNS_LOCAL_IP4 "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 new file mode 100644 index 0000000..9f51788 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DNS_SERVERS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DNS_SERVERS \- set preferred DNS servers +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SERVERS, char *servers); +.SH DESCRIPTION +Pass a char * that is the list of DNS servers to be used instead of the system +default. The format of the dns servers option is: + +host[:port][,host[:port]]... + +For example: + +192.168.1.100,192.168.1.101,3.4.5.6 +.SH DEFAULT +NULL - use system default +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +Added in 7.24.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, +CURLE_NOT_BUILT_IN if support was disabled at compile-time, +CURLE_BAD_FUNCTION_ARGUMENT when given an invalid server list, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_DNS_LOCAL_IP4 "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 new file mode 100644 index 0000000..db53c0b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_DNS_USE_GLOBAL_CACHE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_DNS_USE_GLOBAL_CACHE \- enable/disable global DNS cache +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_USE_GLOBAL_CACHE, + long enable); +.SH DESCRIPTION +Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS +cache that will survive between easy handle creations and deletions. This is +not thread-safe and this will use a global variable. + +\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over +to using the share interface instead! See \fICURLOPT_SHARE(3)\fP and +\fIcurl_share_init(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Subject for removal in the future. Do not use! +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SHARE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 new file mode 100644 index 0000000..2e72ecc --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_EGDSOCKET 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_EGDSOCKET \- set EGD socket path +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EGDSOCKET, char *path); +.SH DESCRIPTION +Pass a char * to the zero terminated path name to the Entropy Gathering Daemon +socket. It will be used to seed the random engine for SSL. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. Only the OpenSSL and GnuTLS backends will use this. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_RANDOM_FILE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 new file mode 100644 index 0000000..577202c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 @@ -0,0 +1,72 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_ERRORBUFFER 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_ERRORBUFFER \- set error buffer for error messages +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf); +.SH DESCRIPTION +Pass a char * to a buffer that the libcurl may store human readable error +messages in on failures or problems. This may be more helpful than just the +return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer +\fBmust be at least CURL_ERROR_SIZE bytes big\fP. + +You must keep the associated buffer available until libcurl no longer needs +it. Failing to do so will cause very odd behavior or even crashes. libcurl +will need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same +option again to use a different pointer. + +Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better +debug and trace why errors happen. + +If the library does not return an error, the buffer may not have been +touched. Do not rely on the contents in those cases. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + char error[CURL_ERROR_SIZE] + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* provide a buffer to store errors in */ + curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, error); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_DEBUGFUNCTION "(3), " CURLOPT_VERBOSE "(3), " +.BR curl_easy_strerror "(3), " curl_multi_strerror "(3), " +.BR curl_share_strerror "(3) " diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 new file mode 100644 index 0000000..81f4571 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_EXPECT_100_TIMEOUT_MS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_EXPECT_100_TIMEOUT_MS \- timeout for Expect: 100-continue response +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_EXPECT_100_TIMEOUT_MS, + long milliseconds); +.SH DESCRIPTION +Pass a long to tell libcurl the number of \fImilliseconds\fP to wait for a +server response with the HTTP status 100 (Continue), 417 (Expectation Failed) +or similar after sending a HTTP request containing an Expect: 100-continue +header. If this times out before a response is received, the request body is +sent anyway. +.SH DEFAULT +1000 milliseconds +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.36.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_POST "(3), " CURLOPT_HTTPPOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 new file mode 100644 index 0000000..a8267fd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FAILONERROR 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FAILONERROR \- request failure on HTTP response >= 400 +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FAILONERROR, long fail); +.SH DESCRIPTION +A long parameter set to 1 tells the library to fail the request if the HTTP +code returned is equal to or larger than 400. The default action would be to +return the page normally, ignoring that code. + +This method is not fail-safe and there are occasions where non-successful +response codes will slip through, especially when authentication is involved +(response codes 401 and 407). + +You might get some amounts of headers transferred before this situation is +detected, like when a "100-continue" is received as a response to a POST/PUT +and a 401 or 407 is received immediately afterwards. +.SH DEFAULT +0, do not fail on error +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTP200ALIASES "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.3 b/docs/libcurl/opts/CURLOPT_FILETIME.3 new file mode 100644 index 0000000..7c57aff --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FILETIME.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FILETIME 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FILETIME \- get the modification time of the remote resource +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FILETIME, long gettime); +.SH DESCRIPTION +Pass a long. If it is 1, libcurl will attempt to get the modification time of +the remote document in this operation. This requires that the remote server +sends the time or replies to a time querying command. The +\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument +can be used after a transfer to extract the received time (if any). +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP, FTP, SFTP, FILE +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR curl_easy_getinfo "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 new file mode 100644 index 0000000..a0466fe --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.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_FNMATCH_DATA 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FNMATCH_DATA \- custom pointer to fnmatch callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_DATA, + void *pointer); +.SH DESCRIPTION +Pass a pointer that will be untouched by libcurl and passed as the ptr +argument to the \fICURL_FNMATCH_FUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FNMATCH_FUNCTION "(3), " CURLOPT_WILDCARDMATCH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 new file mode 100644 index 0000000..fc119a9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FNMATCH_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FNMATCH_FUNCTION \- wildcard matching function callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +int fnmatch_callback(void *ptr, + const char *pattern, + const char *string); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FNMATCH_FUNCTION, + fnmatch_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback s used for wildcard matching. + +Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, +\fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an +error occurred. +.SH DEFAULT +NULL == an internal function for wildcard matching. +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FNMATCH_DATA "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 new file mode 100644 index 0000000..3a32cae --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FOLLOWLOCATION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); +.SH DESCRIPTION +A parameter set to 1 tells the library to follow any Location: header that the +server sends as part of a HTTP header in a 3xx response. + +This means that libcurl will re-send the same request on the new location and +follow new Location: headers all the way until no more such headers are +returned. \fICURLOPT_MAXREDIRS(3)\fP can be used to limit the number of +redirects libcurl will follow. + +libcurl can limit to what protocols it will automatically follow. The accepted +protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP and it excludes the +FILE protocol by default. + +For users who think the existing location following is too naive, too simple +or just lacks features, it is very easy to instead implement your own redirect +follow logic with the use of \fIcurl_easy_getinfo(3)\fP's +\fICURLINFO_REDIRECT_URL\fP option instead of using +\fICURLOPT_FOLLOWLOCATION(3)\fP. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_REDIR_PROTOCOLS "(3), " CURLOPT_PROTOCOLS "(3), " +.BR CURLOPT_POSTREDIR "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 new file mode 100644 index 0000000..c588ca5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FORBID_REUSE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FORBID_REUSE \- make connection get closed at once after use +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FORBID_REUSE, long close); +.SH DESCRIPTION +Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the +connection when done with the transfer. Normally, libcurl keeps all +connections alive when done with one transfer in case a succeeding one follows +that can re-use them. This option should be used with caution and only if you +understand what it does as it can seriously impact performance. + +Set to 0 to have libcurl keep the connection open for possible later re-use +(default behavior). +.SH DEFAULT +0 +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXCONNECTS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 new file mode 100644 index 0000000..1caaf61 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FRESH_CONNECT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FRESH_CONNECT \- force a new connection to be used +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FRESH_CONNECT, long fresh); +.SH DESCRIPTION +Pass a long. Set to 1 to make the next transfer use a new (fresh) connection +by force instead of trying to re-use an existing one. This option should be +used with caution and only if you understand what it does as it may seriously +impact performance. + +Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the +connection is closed after use so that it won't be re-used. + +Set \fIfresh\fP to 0 to have libcurl attempt re-using an existing connection +(default behavior). +.SH DEFAULT +0 +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_FORBID_REUSE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.3 b/docs/libcurl/opts/CURLOPT_FTPPORT.3 new file mode 100644 index 0000000..fd87bb2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.3 @@ -0,0 +1,72 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTPPORT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTPPORT \- make FTP transfer active +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPPORT, char *spec); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It specifies that the +FTP transfer will be made actively and the given string will be used to get +the IP address to use for the FTP PORT instruction. + +The PORT instruction tells the remote server to connect to our specified IP +address. The string may be a plain IP address, a host name, a network +interface name (under Unix) or just a '-' symbol to let the library use your +system's default IP address. Default FTP operations are passive, and thus +won't use PORT. + +The address can be followed by a ':' to specify a port, optionally followed by +a '-' to specify a port range. If the port specified is 0, the operating +system will pick a free port. If a range is provided and all ports in the +range are not available, libcurl will report CURLE_FTP_PORT_FAILED for the +handle. Invalid port/range settings are ignored. IPv6 addresses followed by +a port or portrange have to be in brackets. IPv6 addresses without port/range +specifier can be in brackets. + +Examples with specified ports: + +.nf + eth0:0 + 192.168.1.2:32000-33000 + curl.se:32123 + [::1]:1234-4567 +.fi + +You disable PORT again and go back to using the passive version by setting +this option to NULL. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Port range support was added in 7.19.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_FTP_USE_EPRT "(3), " CURLOPT_FTP_USE_EPSV "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 new file mode 100644 index 0000000..bfbea9c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTPSSLAUTH 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTPSSLAUTH \- set order in which to attempt TLS vs SSL when using FTP +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order); +.SH DESCRIPTION +Pass a long using one of the values from below, to alter how libcurl issues +\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only +interesting if \fICURLOPT_USE_SSL(3)\fP is also set. + +Possible \fIorder\fP values: +.IP CURLFTPAUTH_DEFAULT +Allow libcurl to decide. +.IP CURLFTPAUTH_SSL +Try "AUTH SSL" first, and only if that fails try "AUTH TLS". +.IP CURLFTPAUTH_TLS +Try "AUTH TLS" first, and only if that fails try "AUTH SSL". +.SH DEFAULT +CURLFTPAUTH_DEFAULT +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.12.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_USE_SSL "(3), " CURLOPT_FTP_SSL_CCC "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 new file mode 100644 index 0000000..3c34247 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.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_FTP_ACCOUNT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_ACCOUNT \- set account info for FTP +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ACCOUNT, char *account); +.SH DESCRIPTION +Pass a pointer to a zero terminated string (or NULL to disable). When an FTP +server asks for "account data" after user name and password has been provided, +this data is sent off using the ACCT command. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.13.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 new file mode 100644 index 0000000..b51e4dd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_ALTERNATIVE_TO_USER 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_ALTERNATIVE_TO_USER, + char *cmd); +.SH DESCRIPTION +Pass a char * as parameter, pointing to a string which will be used to +authenticate if the usual FTP "USER user" and "PASS password" negotiation +fails. This is currently only known to be required when connecting to +Tumbleweed's Secure Transport FTPS server using client certificates for +authentication. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_FTP_SKIP_PASV_IP "(3), " CURLOPT_FTP_RESPONSE_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 new file mode 100644 index 0000000..a52863e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_CREATE_MISSING_DIRS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing dirs for FTP and SFTP +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +typedef enum { + CURLFTP_CREATE_DIR_NONE, + CURLFTP_CREATE_DIR, + CURLFTP_CREATE_DIR_RETRY +} curl_ftpcreatedir; + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_CREATE_MISSING_DIRS, + long create); +.SH DESCRIPTION +Pass a long telling libcurl to \fIcreate\fP the dir. If the value is +\fICURLFTP_CREATE_DIR\fP (1), libcurl will attempt to create any remote +directory that it fails to "move" into. + +For FTP requests, that means a CWD command fails. CWD being the command that +changes working directory. + +For SFTP requests, libcurl will attempt to create the remote directory if it +can't obtain a handle to the target-location. The creation will fail if a file +of the same name as the directory to create already exists or lack of +permissions prevents creation. + +Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to +retry the CWD command again if the subsequent MKD command fails. This is +especially useful if you're doing many simultaneous connections against the +same server and they all have this option enabled, as then CWD may first fail +but then another connection does MKD before this connection and thus MKD fails +but trying CWD works! +.SH DEFAULT +CURLFTP_CREATE_DIR_NONE (0) +.SH PROTOCOLS +FTP and SFTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.10.7. SFTP support added in 7.16.3. The retry option was added in +7.19.4. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the +create value is not. +.SH "SEE ALSO" +.BR CURLOPT_FTP_FILEMETHOD "(3), " CURLOPT_FTP_USE_EPSV "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 new file mode 100644 index 0000000..62396b9 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 @@ -0,0 +1,62 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_FILEMETHOD 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_FILEMETHOD \- select directory traversing method for FTP +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_FILEMETHOD, + long method); +.SH DESCRIPTION +Pass a long telling libcurl which \fImethod\fP to use to reach a file on a +FTP(S) server. + +This option exists because some server implementations aren't compliant to +what the standards say should work. + +The argument should be one of the following alternatives: +.IP CURLFTPMETHOD_MULTICWD +libcurl does a single CWD operation for each path part in the given URL. For +deep hierarchies this means many commands. This is how RFC1738 says it should +be done. This is the default but the slowest behavior. +.IP CURLFTPMETHOD_NOCWD +libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a +full path to the server for all these commands. This is the fastest behavior. +.IP CURLFTPMETHOD_SINGLECWD +libcurl does one CWD with the full target directory and then operates on the +file \&"normally" (like in the multicwd case). This is somewhat more standards +compliant than 'nocwd' but without the full penalty of 'multicwd'. +.SH DEFAULT +CURLFTPMETHOD_MULTICWD +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FTPLISTONLY "(3), " CURLOPT_FTP_SKIP_PASV_IP "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 new file mode 100644 index 0000000..18dbc2f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_RESPONSE_TIMEOUT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_RESPONSE_TIMEOUT \- time allowed to wait for FTP response +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_RESPONSE_TIMEOUT, long timeout); +.SH DESCRIPTION +Pass a long. Causes libcurl to set a \fItimeout\fP period (in seconds) on the +amount of time that the server is allowed to take in order to send a response +message for a command before the session is considered dead. While libcurl is +waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is +recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set +\fICURLOPT_FTP_RESPONSE_TIMEOUT(3)\fP to a value smaller than +\fICURLOPT_TIMEOUT(3)\fP. +.SH DEFAULT +None +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.10.8 +.SH RETURN VALUE +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT "(3), " CURLOPT_CONNECTTIMEOUT "(3), " +.BR CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 new file mode 100644 index 0000000..b1803fd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_SKIP_PASV_IP 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_SKIP_PASV_IP \- ignore the IP address in the PASV response +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SKIP_PASV_IP, long skip); +.SH DESCRIPTION +Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP +address the server suggests in its 227-response to libcurl's PASV command when +libcurl connects the data connection. Instead libcurl will re-use the same IP +address it already uses for the control connection. But it will use the port +number from the 227-response. + +This option thus allows libcurl to work around broken server installations +that due to NATs, firewalls or incompetence report the wrong IP address back. + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. +.SH DEFAULT +0 +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.14.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FTPPORT "(3), " CURLOPT_FTP_USE_EPRT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 new file mode 100644 index 0000000..5391285 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_SSL_CCC 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_SSL_CCC \- switch off SSL again with FTP after auth +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_SSL_CCC, + long how); +.SH DESCRIPTION +If enabled, this option makes libcurl use CCC (Clear Command Channel). It +shuts down the SSL/TLS layer after authenticating. The rest of the control +channel communication will be unencrypted. This allows NAT routers to follow +the FTP transaction. Pass a long using one of the values below +.IP CURLFTPSSL_CCC_NONE +Don't attempt to use CCC. +.IP CURLFTPSSL_CCC_PASSIVE +Do not initiate the shutdown, but wait for the server to do it. Do not send a +reply. +.IP CURLFTPSSL_CCC_ACTIVE +Initiate the shutdown and wait for a reply. +.SH DEFAULT +CURLFTPSSL_CCC_NONE +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_USE_SSL "(3), " CURLOPT_FTPSSLAUTH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 new file mode 100644 index 0000000..d26af0c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_USE_EPRT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_USE_EPRT \- enable/disable use of EPRT with FTP +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPRT, long enabled); +.SH DESCRIPTION +Pass a long. If the value is 1, it tells curl to use the EPRT command when +doing active FTP downloads (which is enabled by +\fICURLOPT_FTPPORT(3)\fP). Using EPRT means that it will first attempt to use +EPRT before using PORT, but if you pass zero to this option, it will not try +using EPRT, only plain PORT. + +If the server is an IPv6 host, this option will have no effect as EPRT is +necessary then. +.SH DEFAULT +.SH PROTOCOLS +.SH EXAMPLE +.SH AVAILABILITY +Added in 7.10.5 +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_FTP_USE_EPSV "(3), " CURLOPT_FTPPORT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 new file mode 100644 index 0000000..172985a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_FTP_USE_EPSV 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_USE_EPSV \- enable/disable use of EPSV +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_EPSV, long epsv); +.SH DESCRIPTION +Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV +command when doing passive FTP downloads (which it does by default). Using +EPSV means that it will first attempt to use EPSV before using PASV, but if +you pass zero to this option, it will not try using EPSV, only plain PASV. + +If the server is an IPv6 host, this option will have no effect as of 7.12.3. +.SH DEFAULT +1 +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with FTP +.SH RETURN VALUE +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FTP_USE_EPRT "(3), " CURLOPT_FTPPORT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 new file mode 100644 index 0000000..b20f3fb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.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_FTP_USE_PRET 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_FTP_USE_PRET \- enable the PRET command +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_USE_PRET, long enable); +.SH DESCRIPTION +Pass a long. If the value is 1, it tells curl to send a PRET command before +PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non-standard +command for directory listings as well as up and downloads in PASV mode. Has +no effect when using the active FTP transfers mode. +.SH DEFAULT +0 +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FTP_USE_EPRT "(3), " CURLOPT_FTP_USE_EPSV "(3), " diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 new file mode 100644 index 0000000..13f3cec --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_GSSAPI_DELEGATION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_GSSAPI_DELEGATION \- set allowed GSS-API delegation +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_GSSAPI_DELEGATION, long level); +.SH DESCRIPTION +Set the long parameter \fIlevel\fP to CURLGSSAPI_DELEGATION_FLAG to allow +unconditional GSSAPI credential delegation. The delegation is disabled by +default since 7.21.7. Set the parameter to CURLGSSAPI_DELEGATION_POLICY_FLAG +to delegate only if the OK-AS-DELEGATE flag is set in the service ticket in +case this feature is supported by the GSS-API implementation and the definition +of GSS_C_DELEG_POLICY_FLAG was available at compile-time. +.SH DEFAULT +CURLGSSAPI_DELEGATION_NONE +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.22.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HEADER.3 b/docs/libcurl/opts/CURLOPT_HEADER.3 new file mode 100644 index 0000000..f5a4be8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADER.3 @@ -0,0 +1,63 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_HEADER 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HEADER \- pass headers to the data stream +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADER, long onoff); +.SH DESCRIPTION +Pass in \fIonoff\fP set to 1 to tell the library to include the header in the +body output for requests with this \fIhandle\fP. This option is relevant for +protocols that actually have headers or other meta-data (like HTTP and FTP). + +When asking to get the header info passed to the same callback as the body, it +is not possible to accurately separate them again without detailed knowledge +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_HEADERDATA.3 b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 new file mode 100644 index 0000000..c0a45f2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HEADERDATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HEADERDATA \- pointer to pass to header callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERDATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP to be used to write the header part of the received data +to. + +If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used, +\fIpointer\fP will be passed in to the respective callback. + +If neither of those options are set, \fIpointer\fP must be a valid FILE * and +it will be used by a plain fwrite() to write headers to. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_HEADERFUNCTION "(3), " CURLOPT_WRITEFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 new file mode 100644 index 0000000..f8ed0ab --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 @@ -0,0 +1,106 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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 \fIbuffer\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 \fICURLE_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 +.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 +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_HEADERDATA "(3), " CURLOPT_WRITEFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 new file mode 100644 index 0000000..7776b92 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_HEADEROPT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HEADEROPT \- set how to send HTTP headers +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADEROPT, long bitmask); +.SH DESCRIPTION +Pass a long that is a bitmask of options of how to deal with headers. The two +mutually exclusive options are: + +\fBCURLHEADER_UNIFIED\fP - the headers specified in +\fICURLOPT_HTTPHEADER(3)\fP will be used in requests both to servers and +proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP will not have +any effect. + +\fBCURLHEADER_SEPARATE\fP - makes \fICURLOPT_HTTPHEADER(3)\fP headers only get +sent to a server and not to a proxy. Proxy headers must be set with +\fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non-CONNECT request +is sent to a proxy, libcurl will send both server headers and proxy +headers. When doing CONNECT, libcurl will send \fICURLOPT_PROXYHEADER(3)\fP +headers only to the proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to +the server. +.SH DEFAULT +CURLHEADER_SEPARATE (changed in 7.42.1, ased CURLHEADER_UNIFIED before then) +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.37.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTPHEADER "(3), " CURLOPT_PROXYHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 new file mode 100644 index 0000000..b87db46 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 @@ -0,0 +1,58 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HTTP200ALIASES 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTP200ALIASES \- specify alternative matches for HTTP 200 OK +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES, + struct curl_slist *aliases); +.SH DESCRIPTION +Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP +200 responses. Some servers respond with a custom header response line. For +example, SHOUTcast servers respond with "ICY 200 OK". Also some very old +Icecast 1.3.x servers will respond like that for certain user agent headers or +in absence of such. By including this string in your list of aliases, +the response will be treated as a valid HTTP header line such as +"HTTP/1.0 200 OK". + +The linked list should be a fully valid list of struct curl_slist structs, and +be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and +\fIcurl_slist_free_all(3)\fP to clean up an entire list. + +The alias itself is not parsed for any version strings. The protocol is +assumed to match HTTP 1.0 when an alias match. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.10.3 +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTP_VERSION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 new file mode 100644 index 0000000..35d75aa --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 @@ -0,0 +1,116 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HTTPAUTH 3 "2 Aug 2014" "libcurl 7.38.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTPAUTH \- set HTTP server authentication methods to try +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask); +.SH DESCRIPTION +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) you want it to use speaking to the remote server. + +The available bits are listed below. If more than one bit is set, libcurl will +first query the site to see which authentication methods it supports and then +pick the best one you allow it to use. For some methods, this will induce an +extra network round-trip. Set the actual name and password with the +\fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the +\fICURLOPT_PASSWORD(3)\fP options. + +For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP. + +.IP CURLAUTH_BASIC +HTTP Basic authentication. This is the default choice, and the only method +that is in wide-spread use and supported virtually everywhere. This sends +the user name and password over the network in plain text, easily captured by +others. +.IP CURLAUTH_DIGEST +HTTP Digest authentication. Digest authentication is defined in RFC2617 and +is a more secure way to do authentication over public networks than the +regular old-fashioned Basic method. +.IP CURLAUTH_DIGEST_IE +HTTP Digest authentication with an IE flavor. Digest authentication is +defined in RFC2617 and is a more secure way to do authentication over public +networks than the regular old-fashioned Basic method. The IE flavor is simply +that libcurl will use a special "quirk" that IE is known to have used before +version 7 and that some servers require the client to use. +.IP CURLAUTH_NEGOTIATE +HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined +in RFC 4559 and is the most secure way to perform authentication over HTTP. + +You need to build libcurl with a suitable GSS-API library or SSPI on Windows +for this to work. +.IP CURLAUTH_NTLM +HTTP NTLM authentication. A proprietary protocol invented and used by +Microsoft. It uses a challenge-response and hash concept similar to Digest, to +prevent the password from being eavesdropped. + +You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this +option to work, or build libcurl on Windows with SSPI support. +.IP CURLAUTH_NTLM_WB +NTLM delegating to winbind helper. Authentication is performed by a separate +binary application that is executed when needed. The name of the application +is specified at compile time but is typically /usr/bin/ntlm_auth + +Note that libcurl will fork when necessary to run the winbind application and +kill it when complete, calling waitpid() to await its exit when done. On POSIX +operating systems, killing the process will cause a SIGCHLD signal to be +raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be +handled intelligently by the application. In particular, the application must +not unconditionally call wait() in its SIGCHLD signal handler to avoid being +subject to a race condition. This behavior is subject to change in future +versions of libcurl. +.IP CURLAUTH_ANY +This is a convenience macro that sets all bits and thus makes libcurl pick any +it finds suitable. libcurl will automatically select the one it finds most +secure. +.IP CURLAUTH_ANYSAFE +This is a convenience macro that sets all bits except Basic and thus makes +libcurl pick any it finds suitable. libcurl will automatically select the one +it finds most secure. +.IP CURLAUTH_ONLY +This is a meta symbol. OR this value together with a single specific auth +value to force libcurl to probe for un-restricted auth and if not, only that +single auth algorithm is acceptable. +.SH DEFAULT +CURLAUTH_BASIC +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Option Added in 7.10.6. + +CURLAUTH_DIGEST_IE was added added in 7.19.3 + +CURLAUTH_ONLY was added in 7.21.3 + +CURLAUTH_NTLM_WB was added in 7.22.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication +methods. +.SH "SEE ALSO" +.BR CURLOPT_PROXYAUTH "(3), " CURLOPT_USERPWD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.3 b/docs/libcurl/opts/CURLOPT_HTTPGET.3 new file mode 100644 index 0000000..c14c387 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.3 @@ -0,0 +1,59 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HTTPGET 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTPGET \- ask for a HTTP GET request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPGET, long useget); +.SH DESCRIPTION +Pass a long. If \fIuseget\fP is 1, this forces the HTTP request to get back to +using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the +same curl \fIhandle\fP. + +When setting \fICURLOPT_HTTPGET(3)\fP to 1, it will automatically set +\fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* use a GET to fetch this */ + curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_NOBODY "(3), " CURLOPT_UPLOAD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 new file mode 100644 index 0000000..cd50431 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 @@ -0,0 +1,110 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_HTTPHEADER 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTPHEADER \- set custom HTTP headers +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPHEADER, struct curl_slist *headers); +.SH DESCRIPTION +Pass a pointer to a linked list of HTTP headers to pass to the server and/or +proxy in your HTTP request. The same list can be used for both host and proxy +requests! + +The linked list should be a fully valid list of \fBstruct curl_slist\fP +structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list +and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a +header that is otherwise generated and used by libcurl internally, your added +one will be used instead. If you add a header with no content as in 'Accept:' +(no data on the right side of the colon), the internally used header will get +disabled. With this option you can add new headers, replace internal headers +and remove internal headers. To add a header with no content (nothing to the +right side of the colon), use the form 'MyHeader;' (note the ending +semicolon). + +The headers included in the linked list \fBmust not\fP be CRLF-terminated, +because libcurl adds CRLF after each header item. Failure to comply with this +will result in strange bugs because the server will most likely ignore part of +the headers you specified. + +The first line in a request (containing the method, usually a GET or POST) is +not a header and cannot be replaced using this option. Only the lines +following the request-line are headers. Adding this method line in this list +of headers will only cause your request to send an invalid header. Use +\fICURLOPT_CUSTOMREQUEST(3)\fP to change the method. + +When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl will not copy +the entire list so you \fBmust\fP keep it around until you no longer use this +\fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on +the list. + +Pass a NULL to this option to reset back to no custom headers. + +The most commonly replaced headers have "shortcuts" in the options +\fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and +\fICURLOPT_REFERER(3)\fP. We recommend using those. + +There's an alternative option that sets or replaces headers only for requests +that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use +\fICURLOPT_HEADEROPT(3)\fP to control the behavior. +.SH SECURITY CONCERNS +By default, this option makes libcurl send the given headers in all HTTP +requests done by this handle. You should therefore use this option with +caution if you for example connect to the remote site using a proxy and a +CONNECT request, you should to consider if that proxy is supposed to also get +the headers. They may be private or otherwise sensitive to leak. + +Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you +intend them to get sent. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.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), " CURLOPT_HEADER "(3)" diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 new file mode 100644 index 0000000..0f35b63 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 @@ -0,0 +1,78 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HTTPPOST 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTPPOST \- specify the multipart formpost content +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPOST, + struct curl_httppost *formpost); +.SH DESCRIPTION +Tells libcurl you want a multipart/formdata HTTP POST to be made and you +instruct what data to pass on to the server in the \fIformpost\fP argument. +Pass a pointer to a linked list of curl_httppost structs as parameter. The +easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as +documented. The data in this list must remain intact until you close this curl +handle again with \fIcurl_easy_cleanup(3)\fP. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP. + +When setting \fICURLOPT_HTTPPOST(3)\fP, it will automatically set +\fICURLOPT_NOBODY(3)\fP to 0. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +/* Fill in the file upload field. This makes libcurl load data from + the given file name when curl_easy_perform() is called. */ +curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "sendfile", + CURLFORM_FILE, "postit2.c", + CURLFORM_END); + +/* Fill in the filename field */ +curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "filename", + CURLFORM_COPYCONTENTS, "postit2.c", + CURLFORM_END); + +/* Fill in the submit field too, even if this is rarely needed */ +curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "submit", + CURLFORM_COPYCONTENTS, "send", + CURLFORM_END); +.fi +.SH AVAILABILITY +As long as HTTP is enabled +.SH RETURN VALUE +Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 new file mode 100644 index 0000000..f861afb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_HTTPPROXYTUNNEL 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTPPROXYTUNNEL \- tunnel through HTTP proxy +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel); +.SH DESCRIPTION +Set the parameter to 1 to make libcurl tunnel all operations through the HTTP +proxy. There is a big difference between using a proxy and to tunnel through +it. If you don't know what this means, you probably don't want this tunneling +option. + +Tunneling essentially means that a CONNECT is sent to the proxy, asking it to +connect to a remote host on a specific port number and then the traffic is +just passed through the proxy. Proxies tend to whitelist specific port numbers +it allows CONNECT requests to and often only port 80 and 443 are allowed. + +When using this, it only makes sense to use \fICURLOPT_PROXYTYPE(3)\fP set to +a HTTP proxy. +.SH DEFAULT +0 +.SH PROTOCOLS +All network protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " CURLOPT_PROXYPORT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 new file mode 100644 index 0000000..65472ec --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HTTP_CONTENT_DECODING 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTP_CONTENT_DECODING \- enable/disable HTTP content decoding +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_CONTENT_DECODING, + long enabled); +.SH DESCRIPTION +Pass a long to tell libcurl how to act on content decoding. If set to zero, +content decoding will be disabled. If set to 1 it is enabled. Libcurl has no +default content decoding but requires you to use +\fICURLOPT_ACCEPT_ENCODING(3)\fP for that. +.SH DEFAULT +1 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " +.BR CURLOPT_ACCEPT_ENCODING "(3) " diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 new file mode 100644 index 0000000..26662db --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_HTTP_TRANSFER_DECODING 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTP_TRANSFER_DECODING \- enable/disable HTTP transfer decoding +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_TRANSFER_DECODING, + long enabled); +.SH DESCRIPTION +Pass a long to tell libcurl how to act on transfer decoding. If set to zero, +transfer decoding will be disabled, if set to 1 it is enabled +(default). libcurl does chunked transfer decoding by default unless this +option is set to zero. +.SH DEFAULT +1 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTP_CONTENT_DECODING "(3), " CURLOPT_ACCEPT_ENCODING "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 new file mode 100644 index 0000000..c85d144 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_HTTP_VERSION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HTTP_VERSION \- specify HTTP protocol version to use +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version); +.SH DESCRIPTION +Pass \fIversion\fP a long, set to one of the values described below. They +force libcurl to use the specific HTTP versions. This is not sensible to do +unless you have a good reason. You have to set this option if you want to use +libcurl's HTTP/2 support. + +.IP CURL_HTTP_VERSION_NONE +We don't care about what version the library uses. libcurl will use whatever +it thinks fit. +.IP CURL_HTTP_VERSION_1_0 +Enforce HTTP 1.0 requests. +.IP CURL_HTTP_VERSION_1_1 +Enforce HTTP 1.1 requests. +.IP CURL_HTTP_VERSION_2_0 +Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.x if HTTP 2 can't be +negotiated with the server. (Added in 7.33.0) +.SH DEFAULT +CURL_HTTP_VERSION_NONE +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSLVERSION "(3), " CURLOPT_HTTP200ALIASES "(3), " diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 new file mode 100644 index 0000000..51fd6b0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_IGNORE_CONTENT_LENGTH 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_IGNORE_CONTENT_LENGTH \- ignore Content-Length in HTTP response +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IGNORE_CONTENT_LENGTH, + long ignore); +.SH DESCRIPTION +If \fIignore\fP is set to 1, ignore the Content-Length header in the HTTP +response. This is useful for Apache 1.x (and similar servers) which will +report incorrect content length for files over 2 gigabytes. If this option is +used, curl will not be able to accurately report progress, and will simply +stop the download when the server ends the connection. + +Only use this option if strictly necessary. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* we know the server is silly, ignore content-length */ + curl_easy_setopt(curl, CURLOPT_IGNORE_CONTENT_LENGTH, 1L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.14.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTP_VERSION "(3), " CURLOPT_MAXFILESIZE_LARGE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 new file mode 100644 index 0000000..fd49e21 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 @@ -0,0 +1,71 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_INFILESIZE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_INFILESIZE \- set size of the input file to send off +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE, long filesize); +.SH DESCRIPTION +When uploading a file to a remote site, \fIfilesize\fP should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a long. See also \fICURLOPT_INFILESIZE_LARGE(3)\fP for sending files larger +than 2GB. + +For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE(3)\fP is +mandatory. + +To unset this value again, set it to -1. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl will actually send, as that +is controlled entirely by what the read callback returns, but telling one +value and sending a different amount may lead to errors. +.SH DEFAULT +Unset +.SH PROTOCOLS +Many +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + long uploadsize = FILE_SIZE; + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/destination.tar.gz"); + + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + curl_easy_setopt(curl, CURLOPT_INFILESIZE, uploadsize); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +SMTP support added in 7.23.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_INFILESIZE_LARGE "(3), " CURLOPT_UPLOAD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 new file mode 100644 index 0000000..114676d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 @@ -0,0 +1,72 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_INFILESIZE_LARGE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_INFILESIZE_LARGE \- set size of the input file to send off +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INFILESIZE_LARGE, + curl_off_t filesize); +.SH DESCRIPTION +When uploading a file to a remote site, \fIfilesize\fP should be used to tell +libcurl what the expected size of the input file is. This value must be passed +as a \fBcurl_off_t\fP. + +For uploading using SCP, this option or \fICURLOPT_INFILESIZE(3)\fP is +mandatory. + +To unset this value again, set it to -1. + +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. + +This option does not limit how much data libcurl will actually send, as that +is controlled entirely by what the read callback returns, but telling one +value and sending a different amount may lead to errors. +.SH DEFAULT +Unset +.SH PROTOCOLS +Many +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_off_t uploadsize = FILE_SIZE; + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/destination.tar.gz"); + + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, uploadsize); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +SMTP support added in 7.23.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_INFILESIZE "(3), " CURLOPT_UPLOAD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_INTERFACE.3 new file mode 100644 index 0000000..0890eb6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.3 @@ -0,0 +1,55 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_INTERFACE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_INTERFACE \- source interface for outgoing traffic +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERFACE, char *interface); +.SH DESCRIPTION +Pass a char * as parameter. This sets the \fIinterface\fP name to use as +outgoing network interface. The name can be an interface name, an IP address, +or a host name. + +If the parameter starts with "if!" then it is treated as only as interface +name and no attempt will ever be named to do treat it as an IP address or to +do name resolution on it. If the parameter starts with \&"host!" it is +treated as either an IP address or a hostname. Hostnames are resolved +synchronously. Using the if! format is highly recommended when using the +multi interfaces to avoid allowing the code to block. If "if!" is specified +but the parameter does not match an existing interface, CURLE_INTERFACE_FAILED +is returned from the libcurl function used to perform the transfer. +.SH DEFAULT +NULL, use whatever the TCP stack finds suitable +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +The "if!" and "host!" syntax was added in 7.24.0. +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_TCP_NODELAY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 new file mode 100644 index 0000000..836dfac --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_INTERLEAVEDATA 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_INTERLEAVEDATA \- custom pointer to RTSP interleave callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEDATA, void *pointer); +.SH DESCRIPTION +This is the userdata \fIpointer\fP that will be passed to +\fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is +received. +.SH DEFAULT +NULL +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_INTERLEAVEFUNCTION "(3), " CURLOPT_RTSP_REQUEST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 new file mode 100644 index 0000000..b965529 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 @@ -0,0 +1,68 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_INTERLEAVEFUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_INTERLEAVEFUNCTION \- callback function for RTSP interleaved data +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +size_t interleave_callback(void *ptr, size_t size, size_t nmemb, + void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERLEAVEFUNCTION, + interleave_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl as soon as it has received +interleaved RTP data. This function gets called for each $ block and therefore +contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl +writes the interleaved header as well as the included data for each call. The +first byte is always an ASCII dollar sign. The dollar sign is followed by a +one byte channel identifier and then a 2 byte integer length in network byte +order. See \fIRFC2326 Section 10.12\fP for more information on how RTP +interleaving behaves. If unset or set to NULL, curl will use the default write +function. + +Interleaved RTP poses some challenges for the client application. Since the +stream data is sharing the RTSP control connection, it is critical to service +the RTP in a timely fashion. If the RTP data is not handled quickly, +subsequent response processing may become unreasonably delayed and the +connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to +service RTP data when no requests are desired. If the application makes a +request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will +process any pending RTP data before marking the request as finished. +.SH DEFAULT +NULL +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_INTERLEAVEFUNCTION "(3), " CURLOPT_RTSP_REQUEST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 new file mode 100644 index 0000000..456080c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_IOCTLDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_IOCTLDATA \- custom pointer passed to I/O callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLDATA, void *pointer); +.SH DESCRIPTION +Pass the \fIpointer\fP that will be untouched by libcurl and passed as the 3rd +argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP. +.SH DEFAULT +By default, the value of this parameter is NULL. +.SH PROTOCOLS +Used with HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.12.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_IOCTLFUNCTION "(3), " CURLOPT_SEEKFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 new file mode 100644 index 0000000..ebfe8df --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 @@ -0,0 +1,76 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_IOCTLFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_IOCTLFUNCTION \- callback for I/O operations +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +typedef enum { + CURLIOE_OK, /* I/O operation successful */ + CURLIOE_UNKNOWNCMD, /* command was unknown to callback */ + CURLIOE_FAILRESTART, /* failed to restart the read */ + CURLIOE_LAST /* never use */ +} curlioerr; + +typedef enum { + CURLIOCMD_NOP, /* no operation */ + CURLIOCMD_RESTARTREAD, /* restart the read stream from start */ + CURLIOCMD_LAST /* never use */ +} curliocmd; + +curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLFUNCTION, ioctl_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl when something special +I/O-related needs to be done that the library can't do by itself. For now, +rewinding the read data stream is the only action it can request. The +rewinding of the read data stream may be necessary when doing a HTTP PUT or +POST with a multi-pass authentication method. + +The callback MUST return \fICURLIOE_UNKNOWNCMD\fP if the input \fIcmd\fP is +not \fICURLIOCMD_RESTARTREAD\fP. + +The \fIclientp\fP argument to the callback is set with the +\fICURLOPT_IOCTLDATA(3)\fP option. + +This option is deprecated! Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP +instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this +parameter will be ignored when seeking. +.SH DEFAULT +By default, this parameter is set to NULL. Not used. +.SH PROTOCOLS +Used with HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.12.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_IOCTLDATA "(3), " CURLOPT_SEEKFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 new file mode 100644 index 0000000..ad9827a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_IPRESOLVE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_IPRESOLVE \- specify which IP protocol version to use +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IPRESOLVE, long resolve); +.SH DESCRIPTION +Allows an application to select what kind of IP addresses to use when +resolving host names. This is only interesting when using host names that +resolve addresses using more than one version of IP. The allowed values are: +.IP CURL_IPRESOLVE_WHATEVER +Default, resolves addresses to all IP versions that your system allows. +.IP CURL_IPRESOLVE_V4 +Resolve to IPv4 addresses. +.IP CURL_IPRESOLVE_V6 +Resolve to IPv6 addresses. +.SH DEFAULT +CURL_IPRESOLVE_WHATEVER +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_HTTP_VERSION "(3), " CURLOPT_SSLVERSION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 b/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 new file mode 100644 index 0000000..08afb29 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 @@ -0,0 +1,58 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_ISSUERCERT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_ISSUERCERT \- issuer SSL certificate filename +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ISSUERCERT, char *file); +.SH DESCRIPTION +Pass a char * to a zero terminated string naming a \fIfile\fP holding a CA +certificate in PEM format. If the option is set, an additional check against +the peer certificate is performed to verify the issuer is indeed the one +associated with the certificate provided by the option. This additional check +is useful in multi-level PKI where one needs to enforce that the peer +certificate is from a specific branch of the tree. + +This option makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is +not considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP +has to be set too for the check to fail). (Added in 7.19.0) +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS-based protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_CRLFILE "(3), " CURLOPT_SSL_VERIFYPEER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 new file mode 100644 index 0000000..0ed0c87 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_KEYPASSWD 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_KEYPASSWD \- set passphrase to private key +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KEYPASSWD, char *pwd); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the \fICURLOPT_SSLKEY(3)\fP or +\fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never needed a pass +phrase to load a certificate but you need one to load your private key. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and +CURLOPT_SSLCERTPASSWD up to 7.9.2. +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLKEY "(3), " CURLOPT_SSH_PRIVATE_KEYFILE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 new file mode 100644 index 0000000..571eba3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_KRBLEVEL 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_KRBLEVEL \- set FTP kerberos security level +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_KRBLEVEL, char *level); +.SH DESCRIPTION +Pass a char * as parameter. Set the kerberos security level for FTP; this also +enables kerberos awareness. This is a string that should match one of the +following: \&'clear', \&'safe', \&'confidential' or \&'private'. If the +string is set but doesn't match one of these, 'private' will be used. Set the +string to NULL to disable kerberos support for FTP. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +This option was known as CURLOPT_KRB4LEVEL up to 7.16.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_KRBLEVEL "(3), " CURLOPT_FTP_SSL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.3 b/docs/libcurl/opts/CURLOPT_LOCALPORT.3 new file mode 100644 index 0000000..88ca1f8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOCALPORT.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_LOCALPORT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_LOCALPORT \- set local port number to use for socket +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORT, long port); +.SH DESCRIPTION +Pass a long. This sets the local port number of the socket used for the +connection. This can be used in combination with \fICURLOPT_INTERFACE(3)\fP +and you are recommended to use \fICURLOPT_LOCALPORTRANGE(3)\fP as well when +this option is set. Valid port numbers are 1 - 65535. +.SH DEFAULT +0, disabled - use whatever the system thinks is fine +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_LOCALPORTRANGE "(3), " CURLOPT_INTERFACE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 new file mode 100644 index 0000000..3a7c701 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_LOCALPORTRANGE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_LOCALPORTRANGE \- number of additional local ports to try +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOCALPORTRANGE, + long range); +.SH DESCRIPTION +Pass a long. The \fIrange\fP argument is the number of attempts libcurl will +make to find a working local port number. It starts with the given +\fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting +this option to 1 or below will make libcurl do only one try for the exact port +number. Port numbers by nature are scarce resources that will be busy at times +so setting this value to something too low might cause unnecessary connection +setup failures. +.SH DEFAULT +1 +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.2 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_LOCALPORT "(3), " CURLOPT_INTERFACE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 new file mode 100644 index 0000000..dde3c6e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_LOGIN_OPTIONS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_LOGIN_OPTIONS \- set login options +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOGIN_OPTIONS, char *options); +.SH DESCRIPTION +Pass a char * as parameter, which should be pointing to the zero terminated +\fIoptions\fP string to use for the transfer. + +For more information about the login options please see RFC2384, RFC5092 and +IETF draft draft-earhart-url-smtp-00.txt + +\fBCURLOPT_LOGIN_OPTIONS(3)\fP can be used to set protocol specific login +options, such as the preferred authentication mechanism via "AUTH=NTLM" or +"AUTH=*", and should be used in conjunction with the \fICURLOPT_USERNAME(3)\fP +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +Only IMAP, POP3 and SMTP support login options. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.34.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 new file mode 100644 index 0000000..893c1b1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.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_LOW_SPEED_LIMIT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_LOW_SPEED_LIMIT \- set low speed limit in bytes per second +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_LIMIT, long speedlimit); +.SH DESCRIPTION +Pass a long as parameter. It contains the average transfer speed in bytes per +second that the transfer should be below during +\fICURLOPT_LOW_SPEED_TIME(3)\fP seconds for libcurl to consider it to be too +slow and abort. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_LOW_SPEED_TIME "(3), " CURLOPT_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 new file mode 100644 index 0000000..90b19f2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_LOW_SPEED_TIME 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_LOW_SPEED_TIME \- set low speed limit time period +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_LOW_SPEED_TIME, long speedtime); +.SH DESCRIPTION +Pass a long as parameter. It contains the time in number seconds that the +transfer speed should be below the \fICURLOPT_LOW_SPEED_LIMIT(3)\fP for the +library to consider it too slow and abort. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_LOW_SPEED_LIMIT "(3), " CURLOPT_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 new file mode 100644 index 0000000..4591a01 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 @@ -0,0 +1,58 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAIL_AUTH 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAIL_AUTH \- SMTP authentication address +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_AUTH, char *auth); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. This will be used to +specify the authentication address (identity) of a submitted message that is +being relayed to another server. + +This optional parameter allows co-operating agents in a trusted environment to +communicate the authentication of individual messages and should only be used +by the application program, using libcurl, if the application is itself a mail +server acting in such an environment. If the application is operating as such +and the AUTH address is not known or is invalid, then an empty string should +be used for this parameter. + +Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address +should not be specified within a pair of angled brackets (<>). However, if an +empty string is used then a pair of brackets will be sent by libcurl as +required by RFC2554. +.SH DEFAULT +NULL +.SH PROTOCOLS +SMTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_MAIL_FROM "(3), " CURLOPT_MAIL_RCPT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 new file mode 100644 index 0000000..bf7160e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAIL_FROM 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAIL_FROM \- SMTP sender address +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_FROM, char *from); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. This should be used +to specify the sender's email address when sending SMTP mail with libcurl. + +An originator email address should be specified with angled brackets (<>) +around it, which if not specified will be added automatically. + +If this parameter is not specified then an empty address will be sent to the +mail server which may cause the email to be rejected. +.SH DEFAULT +blank +.SH PROTOCOLS +SMTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_MAIL_RCPT "(3), " CURLOPT_MAIL_AUTH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 new file mode 100644 index 0000000..95665e7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 @@ -0,0 +1,60 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAIL_RCPT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAIL_RCPT \- list of SMTP mail recipients +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT, + struct curl_slist *rcpts); +.SH DESCRIPTION +Pass a pointer to a linked list of recipients to pass to the server in your +SMTP mail request. The linked list should be a fully valid list of \fBstruct +curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to +create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. + +When performing a mail transfer, each recipient should be specified within a +pair of angled brackets (<>), however, should you not use an angled bracket as +the first character libcurl will assume you provided a single email address +and enclose that address within brackets for you. + +When performing an address verification (VRFY command), each recipient should +be specified as the user name or user name and domain (as per Section 3.5 of +RFC5321). + +When performing a mailing list expand (EXPN command), each recipient should be +specified using the mailing list name, such as "Friends" or "London-Office". +.SH DEFAULT +NULL +.SH PROTOCOLS +SMTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0. The VRFY and EXPN logic was added in 7.34.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAIL_FROM "(3), " CURLOPT_MAIL_AUTH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 new file mode 100644 index 0000000..2a41b37 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 @@ -0,0 +1,59 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAXCONNECTS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAXCONNECTS \- maximum connection cache size +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXCONNECTS, long amount); +.SH DESCRIPTION +Pass a long. The set \fIamount\fP will be the maximum number of simultaneously +open persistent connections that libcurl may cache in the pool associated with +this handle. The default is 5, and there isn't much point in changing this +value unless you are perfectly aware of how this works and changes libcurl's +behaviour. This concerns connections using any of the protocols that support +persistent connections. + +When reaching the maximum limit, curl closes the oldest one in the cache to +prevent increasing the number of open connections. + +If you already have performed transfers with this curl handle, setting a +smaller \fICURLOPT_MAXCONNECTS(3)\fP than before may cause open connections to +get closed unnecessarily. + +If you add this easy handle to a multi handle, this setting is not +acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and the +\fICURLMOPT_MAXCONNECTS\fP option. +.SH DEFAULT +5 +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLMOPT_MAXCONNECTS "(3), " CURLOPT_MAXREDIRS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 new file mode 100644 index 0000000..e0ce066 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAXFILESIZE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAXFILESIZE \- maximum file size allowed to download +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE, long size); +.SH DESCRIPTION +Pass a long as parameter. This allows you to specify the maximum \fIsize\fP +(in bytes) of a file to download. If the file requested is found larger than +this value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will +be returned. + +The file size is not always known prior to download, and for such files this +option has no effect even if the file transfer ends up being larger than this +given limit. This concerns both FTP and HTTP transfers. + +If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. +.SH DEFAULT +None +.SH PROTOCOLS +FTP and HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_MAXFILESIZE_LARGE "(3), " CURLOPT_MAX_RECV_SPEED_LARGE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 new file mode 100644 index 0000000..b313001 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAXFILESIZE_LARGE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXFILESIZE_LARGE, + curl_off_t size); +.SH DESCRIPTION +Pass a curl_off_t as parameter. This allows you to specify the maximum +\fIsize\fP (in bytes) of a file to download. If the file requested is found +larger than this value, the transfer will not start and +\fICURLE_FILESIZE_EXCEEDED\fP will be returned. + +The file size is not always known prior to download, and for such files this +option has no effect even if the file transfer ends up being larger than this +given limit. This concerns both FTP and HTTP transfers. +.SH DEFAULT +None +.SH PROTOCOLS +FTP and HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.11.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAXFILESIZE "(3), " CURLOPT_MAX_RECV_SPEED_LARGE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 new file mode 100644 index 0000000..34608c3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAXREDIRS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAXREDIRS \- maximum number of redirects allowed +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAXREDIRS, long amount); +.SH DESCRIPTION +Pass a long. The set number will be the redirection limit \fIamount\fP. If +that many redirections have been followed, the next redirect will cause an +error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the +\fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time. + +Setting the limit to 0 will make libcurl refuse any redirect. + +Set it to -1 for an infinite number of redirects. +.SH DEFAULT +-1, unlimited +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); + + /* enable redirect following */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* allow three redirects */ + curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FOLLOWLOCATION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 new file mode 100644 index 0000000..e73ad22 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAX_RECV_SPEED_LARGE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_RECV_SPEED_LARGE, + curl_off_t speed); +.SH DESCRIPTION +Pass a curl_off_t as parameter. If a download exceeds this \fIspeed\fP +(counted in bytes per second) on cumulative average during the transfer, the +transfer will pause to keep the average rate less than or equal to the +parameter value. Defaults to unlimited speed. + +This option doesn't affect transfer speeds done with FILE:// URLs. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +All but file:// +.SH EXAMPLE +.SH AVAILABILITY +Added in 7.15.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAX_SEND_SPEED_LARGE "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 new file mode 100644 index 0000000..4893b39 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_MAX_SEND_SPEED_LARGE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAX_SEND_SPEED_LARGE, + curl_off_t maxspeed); +.SH DESCRIPTION +Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds +this speed (counted in bytes per second) on cumulative average during the +transfer, the transfer will pause to keep the average rate less than or equal +to the parameter value. Defaults to unlimited speed. + +This option doesn't affect transfer speeds done with FILE:// URLs. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +All except file:// +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.15.5 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAX_RECV_SPEED_LARGE "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NETRC.3 b/docs/libcurl/opts/CURLOPT_NETRC.3 new file mode 100644 index 0000000..9fb13b3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NETRC.3 @@ -0,0 +1,73 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NETRC 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NETRC \- request that .netrc is used +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level); +.SH DESCRIPTION +This parameter controls the preference \fIlevel\fP of libcurl between using +user names and passwords from your \fI~/.netrc\fP file, relative to user names +and passwords in the URL supplied with \fICURLOPT_URL(3)\fP. + +libcurl uses a user name (and supplied or prompted password) supplied with +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP in preference to any of +the options controlled by this parameter. + +Only machine name, user name and password are taken into account (init macros +and similar things aren't supported). + +libcurl does not verify that the file has the correct properties set (as the +standard Unix ftp client does). It should only be readable by user. + +\fIlevel\fP should be set to one of the values described below. + +.IP CURL_NETRC_OPTIONAL +The use of your \fI~/.netrc\fP file is optional, and information in the URL is +to be preferred. The file will be scanned for the host and user name (to +find the password only) or for the host only, to find the first user name and +password after that \fImachine\fP, which ever information is not specified in +the URL. + +Undefined values of the option will have this effect. +.IP CURL_NETRC_IGNORED +The library will ignore the file and use only the information in the URL. + +This is the default. +.IP CURL_NETRC_REQUIRED +This value tells the library that use of the file is required, to ignore the +information in the URL, and to search the file for the host only. +.SH DEFAULT +CURL_NETRC_IGNORED +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_USERPWD "(3), " CURLOPT_USERNAME "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 new file mode 100644 index 0000000..7291999 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NETRC_FILE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NETRC_FILE \- file name to read .netrc info from +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC_FILE, char *file); +.SH DESCRIPTION +Pass a char * as parameter, pointing to a zero terminated string containing +the full path name to the \fIfile\fP you want libcurl to use as .netrc +file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl +will attempt to find a .netrc file in the current user's home +directory. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.10.9 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_NETRC "(3), " CURLOPT_USERNAME "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 new file mode 100644 index 0000000..2d22595 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NEW_DIRECTORY_PERMS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_DIRECTORY_PERMS, + long mode); +.SH DESCRIPTION +Pass a long as a parameter, containing the value of the permissions that will +be assigned to newly created directories on the remote server. The default value is +\fI0755\fP, but any valid value can be used. The only protocols that can use +this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. +.SH DEFAULT +0755 +.SH PROTOCOLS +SFTP, SCP and FILE +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_NEW_FILE_PERMS "(3), " CURLOPT_UPLOAD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 new file mode 100644 index 0000000..eb51f46 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NEW_FILE_PERMS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NEW_FILE_PERMS, + long mode); +.SH DESCRIPTION +Pass a long as a parameter, containing the value of the permissions that will +be assigned to newly created files on the remote server. The default value is +\fI0644\fP, but any valid value can be used. The only protocols that can use +this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. +.SH DEFAULT +0644 +.SH PROTOCOLS +SFTP, SCP and FILE +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_NEW_DIRECTORY_PERMS "(3), " CURLOPT_UPLOAD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.3 b/docs/libcurl/opts/CURLOPT_NOBODY.3 new file mode 100644 index 0000000..b303b95 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOBODY.3 @@ -0,0 +1,59 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NOBODY 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NOBODY \- do the download request without getting the body +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOBODY, long opt); +.SH DESCRIPTION +A long parameter set to 1 tells libcurl to not include the body-part in the +output when doing what would otherwise be a download. For HTTP(S), this makes +libcurl do a HEAD request. For most other protocols it means just not asking +to transfer the body data. + +Enabling this option means asking for a download but without a body. +.SH DEFAULT +0, the body is transferred +.SH PROTOCOLS +Most +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* get us the resource without a body! */ + curl_easy_setopt(curl, CURLOPT_NOBODY, 1L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_HTTPGET "(3), " CURLOPT_POST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 new file mode 100644 index 0000000..ebdecb0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 @@ -0,0 +1,42 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NOPROGRESS 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NOPROGRESS \- switch off the progress meter +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROGRESS, long onoff); +.SH DESCRIPTION +If \fIonoff\fP is to 1, it tells the library to shut off the progress meter +completely for requests done with this \fIhandle\fP. It will also prevent the +\fICURLOPT_PROGRESSFUNCTION(3)\fP from getting called. + +Future versions of libcurl are likely to not have any built-in progress meter +at all. +.SH DEFAULT +1, meaning it normally runs without a progress meter. +.SH RETURN VALUE +Returns CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_PROGRESSFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.3 b/docs/libcurl/opts/CURLOPT_NOPROXY.3 new file mode 100644 index 0000000..7e2e719 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NOPROXY 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NOPROXY \- disable proxy use for specific hosts +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOPROXY, char *noproxy); +.SH DESCRIPTION +Pass a pointer to a zero terminated string. The string consists of a comma +separated list of host names that do not require a proxy to get reached, even +if one is specified. The only wildcard available is a single * character, +which matches all hosts, and effectively disables the proxy. Each name in this +list is matched as either a domain which contains the hostname, or the +hostname itself. For example, example.com would match example.com, +example.com:80, and www.example.com, but not www.notanexample.com or +example.com.othertld. +.SH DEFAULT +NULL +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYAUTH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 new file mode 100644 index 0000000..27fe158 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 @@ -0,0 +1,55 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_NOSIGNAL 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_NOSIGNAL \- skip all signal handling +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NOSIGNAL, long onoff); +.SH DESCRIPTION +If \fIonoff\fP is 1, libcurl will not use any functions that install signal +handlers or any functions that cause signals to be sent to the process. This +option is here to allow multi-threaded unix applications to still set/use all +timeout options etc, without risking getting signals. + +If this option is set and libcurl has been built with the standard name +resolver, timeouts will not occur while the name resolve takes place. +Consider building libcurl with the c-ares or threaded resolver backends to +enable asynchronous DNS lookups, to enable timeouts for name resolves without +the use of signals. + +Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to +ignore SIGPIPE signals, which otherwise are sent by the system when trying to +send data to a socket which is closed in the other end. libcurl makes an +effort to never cause such SIGPIPEs to trigger, but some operating systems +have no way to avoid them and even on those that have there are some corner +cases when they may still happen, contrary to our desire. In addition, using +\fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be +raised. +.SH DEFAULT +0 +.SH AVAILABILITY +Added in 7.10 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 new file mode 100644 index 0000000..a397c3e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_OPENSOCKETDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_OPENSOCKETDATA \- custom pointer passed to open socket callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETDATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. +.SH DEFAULT +The default value of this parameter is NULL. +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_OPENSOCKETFUNCTION "(3), " CURLOPT_SOCKOPTFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 new file mode 100644 index 0000000..d5f461d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 @@ -0,0 +1,90 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_OPENSOCKETFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_OPENSOCKETFUNCTION \- set callback for opening sockets +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +typedef enum { + CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */ + CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */ + CURLSOCKTYPE_LAST /* never use */ +} curlsocktype; + +struct curl_sockaddr { + int family; + int socktype; + int protocol; + unsigned int addrlen; + struct sockaddr addr; +}; + +curl_socket_t opensocket_callback(void *clientp, + curlsocktype purpose, + struct curl_sockaddr *address); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl instead of the \fIsocket(2)\fP +call. The callback's \fIpurpose\fP argument identifies the exact purpose for +this particular socket: \fICURLSOCKTYPE_IPCXN\fP is for IP based connections +and \fICURLSOCKTYPE_ACCEPT\fP is for sockets created after accept() - such as +when doing active FTP. Future versions of libcurl may support more +purposes. + +The \fIclientp\fP pointer contains whatever user-defined value set using the +\fICURLOPT_OPENSOCKETDATA(3)\fP function. + +The callback gets the resolved peer address as the \fIaddress\fP argument and +is allowed to modify the address or refuse to connect completely. The callback +function should return the newly created socket or \fICURL_SOCKET_BAD\fP in +case no connection could be established or another error was detected. Any +additional \fIsetsockopt(2)\fP calls can of course be done on the socket at +the user's discretion. A \fICURL_SOCKET_BAD\fP return value from the callback +function will signal an unrecoverable error to libcurl and it will return +\fICURLE_COULDNT_CONNECT\fP from the function that triggered this callback. +This return code can be used for IP address blacklisting. + +If you want to pass in a socket with an already established connection, pass +the socket back with this callback and then use +\fICURLOPT_SOCKOPTFUNCTION(3)\fP to signal that it already is connected. +.SH DEFAULT +The default behavior is the equivalent of this: +.nf + return socket(addr->family, addr->socktype, addr->protocol); +.fi +.SH PROTOCOLS +All +.SH EXAMPLE +.SH AVAILABILITY +Added in 7.17.1. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_OPENSOCKETDATA "(3), " CURLOPT_SOCKOPTFUNCTION "(3), " +.BR CURLOPT_CLOSESOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_PASSWORD.3 new file mode 100644 index 0000000..b460658 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PASSWORD.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PASSWORD 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PASSWORD \- password to use in authentication +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PASSWORD, char *pwd); +.SH DESCRIPTION +Pass a char * as parameter, which should be pointing to the zero terminated +password to use for the transfer. + +The \fICURLOPT_PASSWORD(3)\fP option should be used in conjunction with the +\fICURLOPT_USERNAME(3)\fP option. +.SH DEFAULT +blank +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_USERPWD "(3), " CURLOPT_USERNAME "(3), " +.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)" + diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 new file mode 100644 index 0000000..490aca0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 @@ -0,0 +1,63 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_PATH_AS_IS 3 "17 Jun 2014" "libcurl 7.42.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PATH_AS_IS \- do not handle dot dot sequences +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PATH_AS_IS, long leaveit); +.SH DESCRIPTION +By setting the long \fIleavit\fP to 1, to explicitly tell libcurl to not alter +the given path before passing it on to the server. + +This tells libcurl to NOT squash sequences of "/../" or "/./" that may exist +in the URL's path part and that is supposed to be removed according to RFC +3986 section 5.2.4. + +Some server implementations are known to (erroneously) require the dot dot +sequences to remain in the path and some clients want to pass these on in +order to try out server implementations. + +By default libcurl will merge such sequences before using the path. +.SH DEFAULT +0 +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/../../etc/password"); + + curl_easy_setopt(curl, CURLOPT_PATH_AS_IS, 1L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Aded in 7.42.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 new file mode 100644 index 0000000..94cad31 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 @@ -0,0 +1,76 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PINNEDPUBLICKEY 3 "27 Aug 2014" "libcurl 7.38.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PINNEDPUBLICKEY \- set pinned public key +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY, char *pinnedpubkey); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your pinned public key. The format expected is "PEM" or "DER". + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. A public key is extracted from this certificate and +if it does not exactly match the public key provided to this option, curl will +abort the connection before sending or receiving any data. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "/etc/publickey.der"); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH PUBLIC KEY EXTRACTION +If you do not have the server's public key file you can extract it from the +server's certificate. +.nf +openssl x509 -in www.test.com.pem -pubkey -noout > www.test.com.pubkey.pem +.fi +The public key is output in PEM format and contains a header, base64 data and a +footer: +.nf +-----BEGIN PUBLIC KEY----- +[BASE 64 DATA] +-----END PUBLIC KEY----- +.fi +.SH AVAILABILITY +Added in 7.39.0 for OpenSSL, GnuTLS and GSKit. Added in 7.43.0 for +NSS and wolfSSL/CyaSSL. Other SSL backends not supported. +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSL_VERIFYPEER "(3), " +.BR CURLOPT_SSL_VERIFYHOST "(3), " +.BR CURLOPT_CAINFO "(3), " +.BR CURLOPT_CAPATH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 new file mode 100644 index 0000000..5f64195 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 @@ -0,0 +1,63 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_PIPEWAIT 3 "12 May 2015" "libcurl 7.43.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PIPEWAIT \- wait for pipelining/multiplexing +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PIPEWAIT, long wait); +.SH DESCRIPTION +Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to +confirm or deny that it can do pipelining or multiplexing before continuing. + +When about to perform a new transfer that allows pipelining or multiplexing, +libcurl will check for existing connections to re-use and pipeline on. If no +such connection exists it will immediately continue and create a fresh new +connection to use. + +By setting this option to 1 - and having \fICURLMOPT_PIPELINE\fP enabled for +the multi handle this transfer is associated with - libcurl will instead wait +for the connection to reveal if it is possible to pipeline/multiplex on before +it continues. This enables libcurl to much better keep the number of +connections to a minimum when using pipelining or multiplexing protocols. + +The effect thus becomes that with this option set, libcurl prefers to wait and +re-use an existing connection for pipelining rather than the opposite: prefer +to open a new connection rather than waiting. + +The waiting time is as long as it takes for the connection to get up and for +libcurl to get the necessary response back that informs it about its protocol +and support level. +.SH DEFAULT +0 (off) +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.SH AVAILABILITY +Added in 7.43.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), " +.BR CURLMOPT_PIPELINING "(3), " CURLMOPT_MAX_HOST_CONNECTIONS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3 new file mode 100644 index 0000000..5fd19c7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PORT.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PORT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PORT \- set remote port number to work with +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number); +.SH DESCRIPTION +This option sets \fInumber\fP to be the remote port number to connect to, +instead of the one specified in the URL or the default port for the used +protocol. + +Usually, you just let the URL decide which port to use but this allows the +application to override that. + +While this option accepts a 'long', a port number is usually a 16 bit number +and therefore using a port number over 65535 will cause a run-time error. +.SH DEFAULT +By default this is 0 which makes it not used. +.SH PROTOCOLS +Used for all protocols that speak to a port number. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POST.3 b/docs/libcurl/opts/CURLOPT_POST.3 new file mode 100644 index 0000000..cd6b6d4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POST.3 @@ -0,0 +1,77 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_POST 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_POST \- request a HTTP POST +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POST, long post); +.SH DESCRIPTION +A parameter set to 1 tells libcurl to do a regular HTTP post. This will also +make the library use a "Content-Type: application/x-www-form-urlencoded" +header. (This is by far the most commonly used POST method). + +Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP +options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or +\fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP to set the data size. + +Optionally, you can provide data to POST using the +\fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_READDATA(3)\fP options but then +you must make sure to not set \fICURLOPT_POSTFIELDS(3)\fP to anything but +NULL. When providing data with a callback, you must transmit it using chunked +transfer-encoding or you must set the size of the data with the +\fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP +options. To enable chunked encoding, you simply pass in the appropriate +Transfer-Encoding header, see the post-callback.c example. + +You can override the default POST Content-Type: header by setting your own +with \fICURLOPT_HTTPHEADER(3)\fP. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +If you use POST to a HTTP 1.1 server, you can send data without knowing the +size before starting the POST if you use chunked encoding. You enable this by +adding a header like "Transfer-Encoding: chunked" with +\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you +must specify the size in the request. + +When setting \fICURLOPT_POST(3)\fP to 1, it will automatically set +\fICURLOPT_NOBODY(3)\fP to 0. + +If you issue a POST request and then want to make a HEAD or GET using the same +re-used handle, you must explicitly set the new request type using +\fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_HTTPPOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 new file mode 100644 index 0000000..27e4510 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 @@ -0,0 +1,87 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_POSTFIELDS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_POSTFIELDS \- specify data to POST to server +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDS, char *postdata); +.SH DESCRIPTION +Pass a char * as parameter, pointing to the full data to send in a HTTP POST +operation. You must make sure that the data is formatted the way you want the +server to receive it. libcurl will not convert or encode it for you in any +way. For example, the web server may assume that this data is url-encoded. + +The data pointed to is NOT copied by the library: as a consequence, it must be +preserved by the calling application until the associated transfer finishes. +This behaviour can be changed (so libcurl does copy the data) by setting the +\fICURLOPT_COPYPOSTFIELDS(3)\fP option. + +This POST is a normal application/x-www-form-urlencoded kind (and libcurl will +set that Content-Type by default when this option is used), which is commonly +used by HTML forms. Change Content-Type with \fICURLOPT_HTTPHEADER(3)\fP. + +Using \fICURLOPT_POSTFIELDS(3)\fP implies \fICURLOPT_POST(3)\fP. + +You can use \fIcurl_easy_escape(3)\fP to url-encode your data, if necessary. It +returns a pointer to an encoded string that can be passed as \fIpostdata\fP. + +If you want to do a zero-byte POST, you need to set +\fICURLOPT_POSTFIELDSIZE(3)\fP explicitly to zero, as simply setting +\fICURLOPT_POSTFIELDS(3)\fP to NULL or "" just effectively disables the +sending of the specified string. libcurl will instead assume that you'll send +the POST data using the read callback! + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +To make multipart/formdata posts (aka RFC2388-posts), check out the +\fICURLOPT_HTTPPOST(3)\fP option combined with \fIcurl_formadd(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* pass in a pointer to the data - libcurl will not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_POSTFIELDSIZE "(3), " CURLOPT_READFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 new file mode 100644 index 0000000..0166805 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 @@ -0,0 +1,62 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_POSTFIELDSIZE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_POSTFIELDSIZE \- size of POST data pointed to +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE, long size); +.SH DESCRIPTION +If you want to post data to the server without having libcurl do a strlen() to +measure the data size, this option must be used. When this option is used you +can post fully binary data, which otherwise is likely to fail. If this size is +set to -1, the library will use strlen() to get the size. + +If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. +.SH DEFAULT +-1 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data)); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_POSTFIELDSIZE_LARGE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 new file mode 100644 index 0000000..50fc351 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_POSTFIELDSIZE_LARGE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_POSTFIELDSIZE_LARGE \- size of POST data pointed to +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTFIELDSIZE_LARGE, + curl_off_t size); +.SH DESCRIPTION +If you want to post data to the server without having libcurl do a strlen() to +measure the data size, this option must be used. When this option is used you +can post fully binary data, which otherwise is likely to fail. If this size is +set to -1, the library will use strlen() to get the size. +.SH DEFAULT +-1 +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + const char *data = large_chunk; + curl_off_t length_of_data; /* set somehow */ + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_POSTFIELDS "(3), " CURLOPT_COPYPOSTFIELDS "(3), " +.BR CURLOPT_POSTFIELDSIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 new file mode 100644 index 0000000..72692fd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_POSTQUOTE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_POSTQUOTE \- (S)FTP commands to run after the transfer +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTQUOTE, struct curl_slist *cmds); +.SH DESCRIPTION +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +after your FTP transfer request. The commands will only be run if no error +occurred. The linked list should be a fully valid list of struct curl_slist +structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP. + +Disable this operation again by setting a NULL to this option. +.SH DEFAULT +NULL +.SH PROTOCOLS +SFTP and FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +If support for the protocols are built-in. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_QUOTE "(3), " CURLOPT_PREQUOTE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 new file mode 100644 index 0000000..aa36bd0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 @@ -0,0 +1,73 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_POSTREDIR 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_POSTREDIR \- how to act on a HTTP POST redirect +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_POSTREDIR, + long bitmask); +.SH DESCRIPTION +Pass a bitmask to control how libcurl acts on redirects after POSTs that get a +301, 302 or 303 response back. A parameter with bit 0 set (value +\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC2616/10.3.2 and not +convert POST requests into GET requests when following a 301 redirection. +Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes libcurl maintain the +request method after a 302 redirect whilst setting bit 2 (value +\fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method after a +303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience define that +sets all three bits. + +The non-RFC behaviour is ubiquitous in web browsers, so the library does the +conversion by default to maintain consistency. However, a server may require a +POST to remain a POST after such a redirection. This option is meaningful only +when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP(S) +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* a silly POST example */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true"); + + /* example.com is redirected, so we tell libcurl to send POST on 301, 302 and + 303 HTTP response codes */ + curl_easy_setopt(curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.17.1. This option was known as CURLOPT_POST301 up to 7.19.0 as it +only supported the 301 then. CURL_REDIR_POST_303 was added in 7.26.0. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_POSTFIELDS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.3 b/docs/libcurl/opts/CURLOPT_PREQUOTE.3 new file mode 100644 index 0000000..e4163e8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PREQUOTE.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PREQUOTE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PREQUOTE \- commands to run before FTP or SFTP transfer +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREQUOTE, char *cmds); +.SH DESCRIPTION +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +after the transfer type is set. The linked list should be a fully valid list +of struct curl_slist structs properly filled in as described for +\fICURLOPT_QUOTE(3)\fP. Disable this operation again by setting a NULL to this +option. +.SH DEFAULT +NULL +.SH PROTOCOLS +FTP and SFTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with the protocol support +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_QUOTE "(3), " CURLOPT_POSTQUOTE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.3 b/docs/libcurl/opts/CURLOPT_PRIVATE.3 new file mode 100644 index 0000000..9907f97 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PRIVATE.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_PRIVATE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PRIVATE \- store a private pointer +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PRIVATE, void *pointer); +.SH DESCRIPTION +Pass a void * as parameter, pointing to data that should be associated with +this curl handle. The pointer can subsequently be retrieved using +\fIcurl_easy_getinfo(3)\fP with the CURLINFO_PRIVATE option. libcurl itself +never does nothing with this data. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +struct private secrets; +if(curl) { + struct private *extracted; + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* store a pointer to our private struct */ + curl_easy_setopt(curl, CURLOPT_PRIVATE, &secrets); + + curl_easy_perform(curl); + + /* we can extract the private pointer again too */ + curl_easy_getinfo(curl, CURLINFO_PRIVATE, &extracted); +} +.fi +.SH AVAILABILITY +Added in 7.10.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_STDERR "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 new file mode 100644 index 0000000..c4785dc --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROGRESSDATA 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROGRESSDATA \- custom pointer passed to the progress callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSDATA, 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_PROGRESSFUNCTION(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 +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_PROGRESSFUNCTION "(3), " CURLOPT_XFERINFOFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 new file mode 100644 index 0000000..d8e7a66 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 @@ -0,0 +1,84 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROGRESSFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROGRESSFUNCTION \- callback to progress meter function +.SH SYNOPSIS +#include <curl/curl.h> + +int progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION, progress_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +We encourage users to use the newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, +if you can. + +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_PROGRESSDATA(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 +Always +.SH RETURN VALUE +Returns CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 new file mode 100644 index 0000000..958eeeb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 @@ -0,0 +1,92 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROTOCOLS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROTOCOLS \- set allowed protocols +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask); +.SH DESCRIPTION +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in the transfer. This allows you to have +a libcurl built to support a wide range of protocols but still limit specific +transfers to only be allowed to use a subset of them. By default libcurl will +accept all protocols it supports (\fICURLPROTO_ALL\fP). See also +\fICURLOPT_REDIR_PROTOCOLS(3)\fP. + +These are the available protocol defines: +.nf +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMB +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +.fi +.SH DEFAULT +All protocols built-in +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow HTTP, TFTP and SFTP */ + curl_easy_setopt(curl, CURLOPT_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_REDIR_PROTOCOLS "(3), " CURLOPT_URL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3 new file mode 100644 index 0000000..b419e51 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY.3 @@ -0,0 +1,85 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXY 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXY \- set proxy to use +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY, char *proxy); +.SH DESCRIPTION +Set the \fIproxy\fP to use for the upcoming request. The parameter should be a +char * to a zero terminated string holding the host name or dotted IP +address. + +To specify port number in this string, append :[port] to the end of the host +name. The proxy's port number may optionally be specified with the separate +option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl will default to +using port 1080 for proxies. + +The proxy string may be prefixed with [scheme]:// to specify which kind of +proxy is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last +one to enable socks5 and asking the proxy to do the resolving, also known as +\fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to +be used. No protocol specified, http:// and all others will be treated as HTTP +proxies. + +Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify +which kind of proxy the string identifies. + +When you tell the library to use a HTTP proxy, libcurl will transparently +convert operations to HTTP even if you specify an FTP URL etc. This may have +an impact on what other features of the library you can use, such as +\fICURLOPT_QUOTE(3)\fP and similar FTP specifics that don't work unless you +tunnel through the HTTP proxy. Such tunneling is activated with +\fICURLOPT_HTTPPROXYTUNNEL(3)\fP. + +libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP, +\fBall_proxy\fP etc, if any of those are set. The \fICURLOPT_PROXY(3)\fP +option does however override any possibly set environment variables. + +Setting the proxy string to "" (an empty string) will explicitly disable the +use of a proxy, even if there is an environment variable set for it. + +A proxy host string given in an environment variable can also include protocol +scheme (http://) and embedded user + password. +.SH DEFAULT +Default is NULL, meaning no proxy is used. + +When you set a host name to use, do not assume that there's any particular +single port number used widely for proxies. Specify it! +.SH PROTOCOLS +All except file://. Note that some protocols don't do very well over proxy. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Since 7.14.1 the proxy environment variable names can include the protocol +scheme. + +Since 7.21.7 the proxy string supports the socks protocols as "schemes". +.SH RETURN VALUE +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXYPORT "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), " +.BR CURLOPT_PROXYTYPE "(3)" diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 new file mode 100644 index 0000000..fe742c0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 @@ -0,0 +1,55 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYAUTH 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYAUTH \- set HTTP proxy authentication methods to try +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYAUTH, long bitmask); +.SH DESCRIPTION +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +HTTP authentication method(s) you want it to use for your proxy +authentication. If more than one bit is set, libcurl will first query the +site to see what authentication methods it supports and then pick the best one +you allow it to use. For some methods, this will induce an extra network +round-trip. Set the actual name and password with the +\fICURLOPT_PROXYUSERPWD(3)\fP option. + +The bitmask can be constructed by or'ing together the bits fully listed and +described in the \fICURLOPT_HTTPAUTH(3)\fP man page. +.SH DEFAULT +CURLAUTH_BASIC +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.10.7 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication +methods. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " +.BR CURLOPT_PROXYUSERPWD "(3), " CURLOPT_PROXYPORT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 new file mode 100644 index 0000000..bfa7a7a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYHEADER 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYHEADER \- custom HTTP headers to pass to proxy +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYHEADER, + struct curl_slist *headers); +.SH DESCRIPTION +Pass a pointer to a linked list of HTTP headers to pass in your HTTP request +sent to a proxy. The rules for this list is identical to the +\fICURLOPT_HTTPHEADER(3)\fP option's. + +The headers set with this option is only ever used in requests sent to a proxy +- when there's also a request sent to a host. + +The first line in a request (containing the method, usually a GET or POST) is +NOT a header and cannot be replaced using this option. Only the lines +following the request-line are headers. Adding this method line in this list +of headers will only cause your request to send an invalid header. + +Pass a NULL to this to reset back to no custom headers. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.37.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 new file mode 100644 index 0000000..43536ca --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYPASSWORD 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYPASSWORD \- password to use with proxy authentication +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPASSWORD, char *pwd); +.SH DESCRIPTION +Pass a char * as parameter, which should be pointing to the zero terminated +password to use for authentication with the proxy. + +The \fICURLOPT_PROXYPASSWORD(3)\fP option should be used in conjunction with +the \fICURLOPT_PROXYUSERNAME(3)\fP option. +.SH DEFAULT +blank +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PASSWORD "(3), " CURLOPT_PROXYUSERNAME "(3), " +.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)" diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.3 b/docs/libcurl/opts/CURLOPT_PROXYPORT.3 new file mode 100644 index 0000000..d8a1bb1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYPORT.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYPORT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYPORT \- port number the proxy listens on +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPORT, long port); +.SH DESCRIPTION +Pass a long with this option to set the proxy port to connect to unless it is +specified in the proxy string \fICURLOPT_PROXY(3)\fP or uses the default one. + +While this accepts a 'long', the port number is 16 bit so it can't be larger +than 65535. +.SH DEFAULT +0, not specified which makes it use the default port +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 new file mode 100644 index 0000000..2ce0cc0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYTYPE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYTYPE \- proxy protocol type +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYTYPE, long type); +.SH DESCRIPTION +Pass a long with this option to set type of the proxy. Available options for +this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP +\fICURLPROXY_SOCKS4\fP, \fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP and +\fICURLPROXY_SOCKS5_HOSTNAME\fP. The HTTP type is default. + +If you set \fBCURLOPT_PROXYTYPE(3)\fP to \fICURLPROXY_HTTP_1_0\fP, it will +only affect how libcurl speaks to a proxy when CONNECT is used. The HTTP +version used for "regular" HTTP requests is instead controlled with +\fICURLOPT_HTTP_VERSION(3)\fP. + +Often it is more convenient to specify the proxy type with the scheme part of +the \fICURLOPT_PROXY(3)\fP string. +.SH DEFAULT +CURLPROXY_HTTP +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYPORT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 new file mode 100644 index 0000000..c342ec4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYUSERNAME 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYUSERNAME \- user name to use for proxy authentication +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERNAME, + char *username); +.SH DESCRIPTION +Pass a char * as parameter, which should be pointing to the zero terminated +user name to use for the transfer. + +\fBCURLOPT_PROXYUSERNAME(3)\fP sets the user name to be used in protocol +authentication with the proxy. + +To specify the proxy password use the \fICURLOPT_PROXYPASSWORD(3)\fP. +.SH DEFAULT +blank +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXYPASSWORD "(3), " CURLOPT_USERNAME "(3), " +.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)" diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 new file mode 100644 index 0000000..bbf0da5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXYUSERPWD 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXYUSERPWD \- user name and password to use for proxy authentication +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYUSERPWD, char *userpwd); +.SH DESCRIPTION +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection to the HTTP proxy. Both the name and the password will be URL +decoded before use, so to include for example a colon in the user name you +should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is +used - beware.) + +Use \fICURLOPT_PROXYAUTH(3)\fP to specify the authentication method. +.SH DEFAULT +This is NULL by default. +.SH PROTOCOLS +Used with all protocols that can use a proxy +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK if proxies are supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 new file mode 100644 index 0000000..a6224fb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_PROXY_SERVICE_NAME 3 "17 Jun 2015" "libcurl 7.43.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXY_SERVICE_NAME \- proxy service name +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME, char *name); +.SH DESCRIPTION +Pass a char * as parameter to a string holding the \fIname\fP of the +service. The default service name is "HTTP". This option allows you to change it. +..SH DEFAULT +See above +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.43.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 new file mode 100644 index 0000000..ae5ede7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PROXY_TRANSFER_MODE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PROXY_TRANSFER_MODE \- append FTP transfer mode to URL for proxy +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TRANSFER_MODE, long enabled); +.SH DESCRIPTION +Pass a long. If the value is set to 1 (one), it tells libcurl to set the +transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by +appending ;type=a or ;type=i to the URL. Without this setting, or it being set +to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT(3)\fP has no effect when +doing FTP via a proxy. Beware that not all proxies support this feature. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +FTP over proxy +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.18.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if the +enabled value is not supported. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_HTTPPROXYTUNNEL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PUT.3 b/docs/libcurl/opts/CURLOPT_PUT.3 new file mode 100644 index 0000000..bd40b7f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PUT.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_PUT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_PUT \- make a HTTP PUT request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PUT, long put); +.SH DESCRIPTION +A parameter set to 1 tells the library to use HTTP PUT to transfer data. The +data should be set with \fICURLOPT_READDATA(3)\fP and +\fICURLOPT_INFILESIZE(3)\fP. + +This option is \fBdeprecated\fP since version 7.12.1. Use +\fICURLOPT_UPLOAD(3)\fP! +.SH DEFAULT +0, disabled +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Deprecated since 7.12.1. Do not use. +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_UPLOAD "(3), " CURLOPT_HTTPGET "(3), " diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.3 b/docs/libcurl/opts/CURLOPT_QUOTE.3 new file mode 100644 index 0000000..8bf3c14 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_QUOTE.3 @@ -0,0 +1,86 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_QUOTE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_QUOTE \- (S)FTP commands to run before transfer +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_QUOTE, struct curl_slist *cmds); +.SH DESCRIPTION +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +prior to your request. This will be done before any other commands are issued +(even before the CWD command for FTP). The linked list should be a fully valid +list of 'struct curl_slist' structs properly filled in with text strings. Use +\fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear +the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this +operation again by setting a NULL to this option. When speaking to a FTP +server, prefix the command with an asterisk (*) to make libcurl continue even +if the command fails as by default libcurl will stop at first failure. + +The set of valid FTP commands depends on the server (see RFC959 for a list of +mandatory commands). + +The valid SFTP commands are: +.RS +.IP "chgrp group file" +The chgrp command sets the group ID of the file named by the file operand to +the group ID specified by the group operand. The group operand is a decimal +integer group ID. +.IP "chmod mode file" +The chmod command modifies the file mode bits of the specified file. The +mode operand is an octal integer mode number. +.IP "chown user file" +The chown command sets the owner of the file named by the file operand to the +user ID specified by the user operand. The user operand is a decimal +integer user ID. +.IP "ln source_file target_file" +The ln and symlink commands create a symbolic link at the target_file location +pointing to the source_file location. +.IP "mkdir directory_name" +The mkdir command creates the directory named by the directory_name operand. +.IP "pwd" +The pwd command returns the absolute pathname of the current working directory. +.IP "rename source target" +The rename command renames the file or directory named by the source +operand to the destination path named by the target operand. +.IP "rm file" +The rm command removes the file specified by the file operand. +.IP "rmdir directory" +The rmdir command removes the directory entry specified by the directory +operand, provided it is empty. +.IP "symlink source_file target_file" +See ln. +.RE +.SH DEFAULT +NULL +.SH PROTOCOLS +SFTP and FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +SFTP support added in 7.16.3. *-prefix for SFTP added in 7.24.0 +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_POSTQUOTE "(3), " CURLOPT_PREQUOTE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 new file mode 100644 index 0000000..0c2d688 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RANDOM_FILE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RANDOM_FILE \- specify a source for random data +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANDOM_FILE, char *path); +.SH DESCRIPTION +Pass a char * to a zero terminated file name. The file will be used to read +from to seed the random engine for SSL and more. +.SH DEFAULT +NULL, not used +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_EGDSOCKET "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RANGE.3 b/docs/libcurl/opts/CURLOPT_RANGE.3 new file mode 100644 index 0000000..f5dd555 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RANGE.3 @@ -0,0 +1,66 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RANGE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RANGE \- set byte range to request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RANGE, char *range); +.SH DESCRIPTION +Pass a char * as parameter, which should contain the specified range you want +to retrieve. It should be in the format "X-Y", where either X or Y may be left +out and X and Y are byte indexes. + +HTTP transfers also support several intervals, separated with commas as in +\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP +server to send the response document in pieces (using standard MIME separation +techniques). For RTSP, the formatting of a range should follow RFC2326 Section +12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should +be given in npt, utc, or smpte formats. + +Pass a NULL to this option to disable the use of ranges. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP, FTP, FILE, RTSP and SFTP. +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* get the first 200 bytes */ + curl_easy_setopt(curl, CURLOPT_RANGE, "0-199"); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +FILE since 7.18.0, RTSP since 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_RESUME_FROM "(3), " diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3 new file mode 100644 index 0000000..a67f415 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_READDATA.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_READDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_READDATA \- custom pointer passed to the read callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READDATA, void *pointer); +.SH DESCRIPTION +Data \fIpointer\fP to pass to the file read function. If you use the +\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you'll get as +input in the 4th argument to the callback. + +If you don't specify a read callback but instead rely on the default internal +read function, this data must be a valid readable FILE * (cast to 'void *'). + +If you're using libcurl as a win32 DLL, you MUST use a +\fICURLOPT_READFUNCTION(3)\fP if you set this option. +.SH DEFAULT +By default, this is a FILE * to stdin. +.SH PROTOCOLS +This is used for all protocols when sending data. +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +struct MyData this; +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* pass pointer that gets passed in to the + CURLOPT_READFUNCTION callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, &this); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +This option was once known by the older name \fICURLOPT_INFILE\fP, the name +\fICURLOPT_READDATA\fP was introduced in 7.9.7. +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_READFUNCTION "(3), " CURLOPT_WRITEDATA "(3), " diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 new file mode 100644 index 0000000..edd9bdb --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 @@ -0,0 +1,79 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_READFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_READFUNCTION \- read callback for data uploads +.SH SYNOPSIS +#include <curl/curl.h> + +size_t read_callback(char *buffer, size_t size, size_t nitems, void *instream); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback); + +.SH DESCRIPTION +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 - 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 +it to stop the current transfer. + +If you stop the current transfer by returning 0 "pre-maturely" (i.e before the +server expected it, like when you've said you will upload N bytes and you +upload less than N bytes), you may experience that the server "hangs" waiting +for the rest of the data that won't come. + +The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current +operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error +code from the transfer. + +The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this +connection to pause. See \fIcurl_easy_pause(3)\fP for further details. + +\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data +that the callback wants, or it will be considered the final packet by the +server end and the transfer will end there. + +If you set this callback pointer to NULL, or don't set it at all, the default +internal read function will be used. It is doing an fread() on the FILE * +userdata set with \fICURLOPT_READDATA(3)\fP. +.SH DEFAULT +The default internal read callback is fread(). +.SH PROTOCOLS +This is used for all protocols when doing uploads. +.SH EXAMPLE +Here's an example setting a read callback for reading that to upload to an FTP +site: http://curl.haxx.se/libcurl/c/ftpupload.html +.SH AVAILABILITY +CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT +was added in 7.12.1. +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_READDATA "(3), " CURLOPT_WRITEFUNCTION "(3), " +.BR CURLOPT_SEEKFUNCTION "(3), " CURLOPT_UPLOAD "(3), " CURLOPT_POST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 new file mode 100644 index 0000000..fbec9f5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 @@ -0,0 +1,92 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_REDIR_PROTOCOLS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_REDIR_PROTOCOLS \- set protocols allowed to redirect to +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS, long bitmask); +.SH DESCRIPTION +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in a transfer that it follows to in a +redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to +limit specific transfers to only be allowed to use a subset of protocols in +redirections. By default libcurl will allow all protocols except for FILE and +SCP. + +These are the available protocol defines: +.nf +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMB +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +.fi +.SH DEFAULT +All protocols except for FILE, SCP and SMB. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow redirects to HTTP and HTTPS URLs */ + curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_HTTPS); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.19.4, before then it would follow all protocols. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_PROTOCOLS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_REFERER.3 b/docs/libcurl/opts/CURLOPT_REFERER.3 new file mode 100644 index 0000000..bcb1625 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_REFERER.3 @@ -0,0 +1,57 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_REFERER 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_REFERER \- set the HTTP referer header +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REFERER, char *where); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It will be used to +set the Referer: header in the http request sent to the remote server. This +can be used to fool servers or scripts. You can also set any custom header +with \fICURLOPT_HTTPHEADER(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* tell it where we found the link to this place */ + curl_easy_setopt(curl, CURLOPT_REFERER, "http://example.com/aboutme.html"); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +If built with HTTP support +.SH RETURN VALUE +Returns CURLE_OK if HTTP support is enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_USERAGENT "(3), " CURLOPT_HTTPHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.3 new file mode 100644 index 0000000..06a393a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.3 @@ -0,0 +1,82 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RESOLVE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RESOLVE \- provide custom host name to IP address resolves +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVE, + struct curl_slist *hosts); +.SH DESCRIPTION +Pass a pointer to a linked list of strings with host name resolve information +to use for requests with this handle. The linked list should be a fully valid +list of \fBstruct curl_slist\fP structs properly filled in. Use +\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP +to clean up an entire list. + +Each single name resolve string should be written using the format +HOST:PORT:ADDRESS where HOST is the name libcurl will try to resolve, PORT is +the port number of the service where libcurl wants to connect to the HOST and +ADDRESS is the numerical IP address. If libcurl is built to support IPv6, +ADDRESS can of course be either IPv4 or IPv6 style addressing. + +This option effectively pre-populates the DNS cache with entries for the +host+port pair so redirects and everything that operations against the +HOST+PORT will instead use your provided ADDRESS. Addresses to set with +\fICURL_RESOLVE\fP will not time-out from the DNS cache like ordinary +entries. + +You can remove names from the DNS cache again, to stop providing these fake +resolves, by including a string in the linked list that uses the format +\&"-HOST:PORT". The host name must be prefixed with a dash, and the host name +and port number must exactly match what was already added previously. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl; +struct curl_slist *host = NULL; +host = curl_slist_append(NULL, "example.com:80:127.0.0.1"); + +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_RESOLVE, host); + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + res = curl_easy_perform(curl); + + /* always cleanup */ + curl_easy_cleanup(curl); +} + +curl_slist_free_all(host); +.fi +.SH AVAILABILITY +Added in 7.21.3 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 new file mode 100644 index 0000000..c25c646 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 @@ -0,0 +1,72 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RESUME_FROM 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RESUME_FROM \- set a point to resume transfer from +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM, long from); +.SH DESCRIPTION +Pass a long as parameter. It contains the offset in number of bytes that you +want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). For FTP, set this +option to -1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it will then append the +source file to the remote target file. + +If you need to resume a transfer beyond the 2GB limit, use +\fICURLOPT_RESUME_FROM_LARGE(3)\fP instead. +.SH DEFAULT +0, not used +.SH PROTOCOLS +HTTP, FTP, SFTP, FILE +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + /* resume upload at byte index 200 */ + curl_easy_setopt(curl, CURLOPT_RESUME_FROM, 200L); + + /* ask for upload */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* set total data amount to expect */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE, size_of_file); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_RESUME_FROM_LARGE "(3), " CURLOPT_RANGE "(3), " +.BR CURLOPT_INFILESIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 new file mode 100644 index 0000000..bcb30af --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 @@ -0,0 +1,74 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RESUME_FROM_LARGE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RESUME_FROM_LARGE \- set a point to resume transfer from +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESUME_FROM_LARGE, + curl_off_t from); +.SH DESCRIPTION +Pass a curl_off_t as parameter. It contains the offset in number of bytes that +you want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). For FTP, set this +option to -1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it will then append the +source file to the remote target file. +.SH DEFAULT +0, not used +.SH PROTOCOLS +HTTP, FTP, SFTP, FILE +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_off_t resume_position = GET_IT_SOMEHOW; + curl_off_t file_size = GET_IT_SOMEHOW_AS_WELL; + + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); + + /* resuming upload at this position, possibly beyond 2GB */ + curl_easy_setopt(curl, CURLOPT_RESUME_FROM_LARGE, resume_position); + + /* ask for upload */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* set total data amount to expect */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_size); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.11.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_RESUME_FROM "(3), " CURLOPT_RANGE "(3), " +.BR CURLOPT_INFILESIZE_LARGE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 new file mode 100644 index 0000000..c951016 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RTSP_CLIENT_CSEQ 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RTSP_CLIENT_CSEQ \- set the RTSP client CSEQ number +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq); +.SH DESCRIPTION +Pass a long to set the the CSEQ number to issue for the next RTSP +request. Useful if the application is resuming a previously broken +connection. The CSEQ will increment from this new number henceforth. +.SH DEFAULT +0 +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_RTSP_SERVER_CSEQ "(3), " CURLOPT_RTSP_REQUEST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 new file mode 100644 index 0000000..9ab175d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 @@ -0,0 +1,101 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RTSP_REQUEST 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RTSP_REQUEST \- specify RTSP request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_REQUEST, long request); +.SH DESCRIPTION +Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP +enum values as a long in the \fIrequest\fP argument. Unless noted otherwise, +commands require the Session ID to be initialized. +.IP CURL_RTSPREQ_OPTIONS +Used to retrieve the available methods of the server. The application is +responsible for parsing and obeying the response. \fB(The session ID is not +needed for this method.)\fP +.IP CURL_RTSPREQ_DESCRIBE +Used to get the low level description of a stream. The application should note +what formats it understands in the \fI'Accept:'\fP header. Unless set +manually, libcurl will automatically fill in \fI'Accept: +application/sdp'\fP. Time-condition headers will be added to Describe requests +if the \fICURLOPT_TIMECONDITION(3)\fP option is active. \fB(The session ID is +not needed for this method)\fP +.IP CURL_RTSPREQ_ANNOUNCE +When sent by a client, this method changes the description of the session. For +example, if a client is using the server to record a meeting, the client can +use Announce to inform the server of all the meta-information about the +session. ANNOUNCE acts like a HTTP PUT or POST just like +\fICURL_RTSPREQ_SET_PARAMETER\fP +.IP CURL_RTSPREQ_SETUP +Setup is used to initialize the transport layer for the session. The +application must set the desired Transport options for a session by using the +\fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session +ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl will +extract and use the session ID in the response to this request. \fB(The +session ID is not needed for this method).\fP +.IP CURL_RTSPREQ_PLAY +Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to +modify the playback time (e.g. 'npt=10-15'). +.IP CURL_RTSPREQ_PAUSE +Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with +a single value to indicate when the stream should be halted. (e.g. npt='25') +.IP CURL_RTSPREQ_TEARDOWN +This command terminates an RTSP session. Simply closing a connection does not +terminate the RTSP session since it is valid to control an RTSP session over +different connections. +.IP CURL_RTSPREQ_GET_PARAMETER +Retrieve a parameter from the server. By default, libcurl will automatically +include a \fIContent-Type: text/parameters\fP header on all non-empty requests +unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST +(see \fICURL_RTSPREQ_SET_PARAMETER\fP). +Applications wishing to send a heartbeat message (e.g. in the presence of a +server-specified timeout) should send use an empty GET_PARAMETER request. +.IP CURL_RTSPREQ_SET_PARAMETER +Set a parameter on the server. By default, libcurl will automatically include +a \fIContent-Type: text/parameters\fP header unless a custom one is set. The +interaction with SET_PARAMETER is much like a HTTP PUT or POST. An application +may either use \fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like a +HTTP PUT, or it may use \fICURLOPT_POSTFIELDS(3)\fP like a HTTP POST. No +chunked transfers are allowed, so the application must set the +\fICURLOPT_INFILESIZE(3)\fP in the former and \fICURLOPT_POSTFIELDSIZE(3)\fP +in the latter. Also, there is no use of multi-part POSTs within RTSP. +.IP CURL_RTSPREQ_RECORD +Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP +option to modify the record time. +.IP CURL_RTSPREQ_RECEIVE +This is a special request because it does not send any data to the server. The +application may call this function in order to receive interleaved RTP +data. It will return after processing one read buffer of data in order to give +the application a chance to run. +.SH DEFAULT +.SH PROTOCOLS +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_RTSP_SESSION_ID "(3), " CURLOPT_RTSP_STREAM_URI "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 new file mode 100644 index 0000000..9e7cf3a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RTSP_SERVER_CSEQ 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RTSP_SERVER_CSEQ \- set the RTSP server CSEQ number +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq); +.SH DESCRIPTION +Pass a long to set the CSEQ number to expect for the next RTSP Server->Client +request. \fBNOTE\fP: this feature (listening for Server requests) is +unimplemented. +.SH DEFAULT +0 +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_RTSP_CLIENT_CSEQ "(3), " CURLOPT_RTSP_STREAM_URI "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 new file mode 100644 index 0000000..ec3d387 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RTSP_SESSION_ID 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RTSP_SESSION_ID \- set RTSP session ID +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_SESSION_ID, char *id); +.SH DESCRIPTION +Pass a char * as a parameter to set the value of the current RTSP Session ID +for the handle. Useful for resuming an in-progress session. Once this value is +set to any non-NULL value, libcurl will return \fICURLE_RTSP_SESSION_ERROR\fP +if ID received from the server does not match. If unset (or set to NULL), +libcurl will automatically set the ID the first time the server sets it in a +response. +.SH DEFAULT +NULL +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_RTSP_REQUEST "(3), " CURLOPT_RTSP_STREAM_URI "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 new file mode 100644 index 0000000..6a10ea0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RTSP_STREAM_URI 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RTSP_STREAM_URI \- set RTSP stream URI +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_STREAM_URI, char *URI); +.SH DESCRIPTION +Set the stream \fIURI\fP to operate on by passing a char * . For example, a +single session may be controlling \fIrtsp://foo/twister/audio\fP and +\fIrtsp://foo/twister/video\fP and the application can switch to the +appropriate stream using this option. If unset, libcurl will default to +operating on generic server options by passing '*' in the place of the RTSP +Stream URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working +with RTSP, the \fICURLOPT_STREAM_URI(3)\fP indicates what URL to send to the +server in the request header while the \fICURLOPT_URL(3)\fP indicates where to +make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above examples +might be set to \fIrtsp://foo/twister\fP +.SH DEFAULT +'*' +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_RTSP_REQUEST "(3), " CURLOPT_RTSP_TRANSPORT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 new file mode 100644 index 0000000..4d0a4c0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_RTSP_TRANSPORT 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_RTSP_TRANSPORT \- set RTSP Transport: header +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RTSP_TRANSPORT, + char *transport); +.SH DESCRIPTION +Pass a char * to tell libcurl what to pass for the Transport: header for this +RTSP session. This is mainly a convenience method to avoid needing to set a +custom Transport: header for every SETUP request. The application must set a +Transport: header before issuing a SETUP request. +.SH DEFAULT +NULL +.SH PROTOCOLS +RTSP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.20.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_RTSP_REQUEST "(3), " CURLOPT_RTSP_SESSION_ID "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.3 b/docs/libcurl/opts/CURLOPT_SASL_IR.3 new file mode 100644 index 0000000..7714217 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SASL_IR 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SASL_IR \- enable sending initial response in first packet +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SASL_IR, long enable); +.SH DESCRIPTION +Pass a long. If the value is 1, curl will send the initial response to the +server in the first authentication packet in order to reduce the number of +ping pong requests. Only applicable to the following supporting SASL +authentication mechanisms: + +* Login +* Plain +* GSSAPI +* NTLM +* OAuth 2.0 + +Note: Whilst IMAP supports this option there is no need to explicitly set it, +as libcurl can determine the feature itself when the server supports the +SASL-IR CAPABILITY. +.SH DEFAULT +0 +.SH PROTOCOLS +IMAP, POP3 and SMTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.31.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAIL_AUTH "(3), " CURLOPT_MAIL_FROM "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 new file mode 100644 index 0000000..830f099 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 @@ -0,0 +1,43 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SEEKDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SEEKDATA \- custom pointer passed to the seek callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKDATA, void *pointer); +.SH DESCRIPTION +Data \fIpointer\fP to pass to the seek callback function. If you use the +\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you'll get as +input. +.SH DEFAULT +If you don't set this, NULL is passed to the callback. +.SH PROTOCOLS +HTTP, FTP, SFTP +.SH EXAMPLE +.SH AVAILABILITY +Added in 7.18.0 +.SH RETURN VALUE +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 new file mode 100644 index 0000000..bf7e304 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 @@ -0,0 +1,76 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_SEEKFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +/* These are the return codes for the seek callbacks */ +#define CURL_SEEKFUNC_OK 0 +#define CURL_SEEKFUNC_FAIL 1 /* fail the entire transfer */ +#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking can't be done, so + libcurl might try other means instead */ + +int seek_callback(void *userp, curl_off_t offset, int origin); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SEEKFUNCTION, seek_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This function gets called by libcurl to seek to a certain position in the +input stream and can be used to fast forward a file in a resumed upload +(instead of reading all uploaded bytes with the normal read +function/callback). It is also called to rewind a stream when data has already +been sent to the server and needs to be sent again. This may happen when doing +a HTTP PUT or POST with a multi-pass authentication method, or when an +existing HTTP connection is reused too late and the server closes the +connection. The function shall work like fseek(3) or lseek(3) and it gets +SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, although libcurl +currently only passes SEEK_SET. + +\fIuserp\fP is the pointer you set with \fICURLOPT_SEEKDATA(3)\fP. + +The callback function must return \fICURL_SEEKFUNC_OK\fP on success, +\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or +\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl +is free to work around the problem if possible. The latter can sometimes be +done by instead reading from the input or similar. + +If you forward the input arguments directly to fseek(3) or lseek(3), note that +the data type for \fIoffset\fP is not the same as defined for curl_off_t on +many systems! +.SH DEFAULT +By default, this is NULL and unused. +.SH PROTOCOLS +HTTP, FTP, SFTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.18.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SEEKDATA "(3), " CURLOPT_IOCTLFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 new file mode 100644 index 0000000..116fdbe --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 @@ -0,0 +1,46 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_SERVICE_NAME 3 "17 Jun 2015" "libcurl 7.43.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SERVICE_NAME \- SPNEGO service name +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVICE_NAME, char *name); +.SH DESCRIPTION +Pass a char * as parameter to a string holding the \fIname\fP of the +service. The default service name is "HTTP". This option allows you to +change it. +..SH DEFAULT +See above +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.43.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SHARE.3 b/docs/libcurl/opts/CURLOPT_SHARE.3 new file mode 100644 index 0000000..a483540 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SHARE.3 @@ -0,0 +1,59 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SHARE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SHARE \- specify share handle to use +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SHARE, CURLSH *share); +.SH DESCRIPTION +Pass a \fIshare\fP handle as a parameter. The share handle must have been +created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, +will make this curl handle use the data from the shared handle instead of +keeping the data to itself. This enables several curl handles to share +data. If the curl handles are used simultaneously in multiple threads, you +\fBMUST\fP use the locking methods in the share handle. See +\fIcurl_share_setopt(3)\fP for details. + +If you add a share that is set to share cookies, your easy handle will use +that cookie cache and get the cookie engine enabled. If you unshare an object +that was using cookies (or change to another object that doesn't share +cookies), the easy handle will get its cookie engine disabled. + +Data that the share object is not set to share will be dealt with the usual +way, as if no share was used. + +Set this option to NULL again to stop using that share object. +.SH DEFAULT +NULL +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_COOKIE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 new file mode 100644 index 0000000..61c2b5e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SOCKOPTDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SOCKOPTDATA \- custom pointer to pass to sockopt callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTDATA, void *pointer); +.SH DESCRIPTION +Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first +argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP. +.SH DEFAULT +The default value of this parameter is NULL. +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.0 +.SH RETURN VALUE +Returns \fICURLE_OK\fP if the option is supported, and \fICURLE_UNKNOWN_OPTION\fP if not. +.SH "SEE ALSO" +.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 new file mode 100644 index 0000000..e99fb79 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 @@ -0,0 +1,88 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SOCKOPTFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SOCKOPTFUNCTION \- set callback for setting socket options +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +typedef enum { + CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */ + CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */ + CURLSOCKTYPE_LAST /* never use */ +} curlsocktype; + +#define CURL_SOCKOPT_OK 0 +#define CURL_SOCKOPT_ERROR 1 /* causes libcurl to abort and return + CURLE_ABORTED_BY_CALLBACK */ +#define CURL_SOCKOPT_ALREADY_CONNECTED 2 + +int sockopt_callback(void *clientp, + curl_socket_t curlfd, + curlsocktype purpose); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +When set, this callback function gets called by libcurl when the socket has +been created, but before the connect call to allow applications to change +specific socket options. The callback's \fIpurpose\fP argument identifies the +exact purpose for this particular socket: + +\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0 +\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV +(in earlier versions these sockets weren't passed to this callback). + +Future versions of libcurl may support more purposes. libcurl passes the newly +created socket descriptor to the callback in the \fIcurlfd\fP parameter so +additional setsockopt() calls can be done at the user's discretion. + +The \fIclientp\fP pointer contains whatever user-defined value set using the +\fICURLOPT_SOCKOPTDATA(3)\fP function. + +Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return +\fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable +error to the library and it will close the socket and return +\fICURLE_COULDNT_CONNECT\fP. +Alternatively, the callback function can return +\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is +already connected and then libcurl will not attempt to connect it. This allows +an application to pass in an already connected socket with +\fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl +not attempt to connect (again). +.SH DEFAULT +By default, this callback is NULL and unused. +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.0. The \fICURL_SOCKOPT_ALREADY_CONNECTED\fP return code was +added in 7.21.5. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SOCKOPTDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 new file mode 100644 index 0000000..cb318fc --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SOCKS5_GSSAPI_NEC 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SOCKS5_GSSAPI_NEC \- set socks proxy gssapi negotiation protection +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec); +.SH DESCRIPTION +Pass a long set to 1 to enable or 0 to disable. As part of the gssapi +negotiation a protection mode is negotiated. The RFC1961 says in section +4.3/4.4 it should be protected, but the NEC reference implementation does not. +If enabled, this option allows the unprotected exchange of the protection mode +negotiation. +.SH DEFAULT +? +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SOCKS5_GSSAPI_SERVICE "(3), " CURLOPT_PROXY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 new file mode 100644 index 0000000..d18ea9f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.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_SOCKS5_GSSAPI_SERVICE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SOCKS5_GSSAPI_SERVICE \- proxy socks gssapi service name +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKS5_GSSAPI_SERVICE, char *name); +.SH DESCRIPTION +Pass a char * as parameter to a string holding the \fIname\fP of the +service. The default service name for a SOCKS5 server is +rcmd/server-fqdn. This option allows you to change it. +.SH DEFAULT +See above +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXY "(3), " CURLOPT_PROXYTYPE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 new file mode 100644 index 0000000..966f746 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_AUTH_TYPES 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_AUTH_TYPES \- set desired auth types for SFTP and SCP +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_AUTH_TYPES, long bitmask); +.SH DESCRIPTION +Pass a long set to a bitmask consisting of one or more of +CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, +CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. + +Set \fICURLSSH_AUTH_ANY\fP to let libcurl pick a suitable one. Currently +CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl +attempts to connect to ssh-agent or pageant and let the agent attempt the +authentication. +.SH DEFAULT +None +.SH PROTOCOLS +SFTP and SCP +.SH EXAMPLE +TODO +.SH AVAILABILITY +CURLSSH_AUTH_HOST was added in 7.16.1, CURLSSH_AUTH_AGENT was added in 7.28.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 "(3), " CURLOPT_SSH_PUBLIC_KEYFILE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 new file mode 100644 index 0000000..12e7720 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_HOST_PUBLIC_KEY_MD5 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- checksum of SSH server public key +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, + char *md5); +.SH DESCRIPTION +Pass a char * pointing to a string containing 32 hexadecimal digits. The +string should be the 128 bit MD5 checksum of the remote host's public key, and +libcurl will reject the connection to the host unless the md5sums match. +.SH DEFAULT +NULL +.SH PROTOCOLS +SCP and SFTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.17.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 new file mode 100644 index 0000000..45e7d7a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 @@ -0,0 +1,44 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_KEYDATA 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_KEYDATA \- pointer to pass to the SSH key callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYDATA, void *pointer); +.SH DESCRIPTION +Pass a void * as parameter. This \fIpointer\fP will be passed along verbatim +to the callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +SFTP and SCP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSH_KEYDATA "(3), " CURLOPT_SSH_KNOWNHOSTS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 new file mode 100644 index 0000000..4af9a3b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 @@ -0,0 +1,105 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_KEYFUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +enum curl_khstat { + CURLKHSTAT_FINE_ADD_TO_FILE, + CURLKHSTAT_FINE, + CURLKHSTAT_REJECT, /* reject the connection, return an error */ + CURLKHSTAT_DEFER, /* do not accept it, but we can't answer right + now so this causes a CURLE_DEFER error but + otherwise the connection will be left intact + etc */ +}; + +enum curl_khmatch { + CURLKHMATCH_OK, /* match */ + CURLKHMATCH_MISMATCH, /* host found, key mismatch! */ + CURLKHMATCH_MISSING, /* no matching host/key found */ +}; + +struct curl_khkey { + const char *key; /* points to a zero-terminated string encoded with + base64 if len is zero, otherwise to the "raw" + data */ + size_t len; + enum curl_khtype keytype; +}; + +int ssh_keycallback(CURL *easy, + const struct curl_khkey *knownkey, + const struct curl_khkey *foundkey, + enum curl_khmatch, + void *clientp); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION, + ssh_keycallback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +It gets called when the known_host matching has been done, to allow the +application to act and decide for libcurl how to proceed. The callback will +only be called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set. + +This callback function gets passed the CURL handle, the key from the +known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP, +info from libcurl on the matching status and a custom pointer (set with +\fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return +codes to tell libcurl how to act: + +.IP CURLKHSTAT_FINE_ADD_TO_FILE +The host+key is accepted and libcurl will append it to the known_hosts file +before continuing with the connection. This will also add the host+key combo +to the known_host pool kept in memory if it wasn't already present there. The +adding of data to the file is done by completely replacing the file with a new +copy, so the permissions of the file must allow this. +.IP CURLKHSTAT_FINE +The host+key is accepted libcurl will continue with the connection. This will +also add the host+key combo to the known_host pool kept in memory if it wasn't +already present there. +.IP CURLKHSTAT_REJECT +The host+key is rejected. libcurl will deny the connection to continue and it +will be closed. +.IP CURLKHSTAT_DEFER +The host+key is rejected, but the SSH connection is asked to be kept alive. +This feature could be used when the app wants to somehow return back and act +on the host+key situation and then retry without needing the overhead of +setting it up from scratch again. +.SH DEFAULT +NULL +.SH PROTOCOLS +SFTP and SCP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSH_KEYDATA "(3), " CURLOPT_SSH_KNOWNHOSTS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 new file mode 100644 index 0000000..85574ce --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_KNOWNHOSTS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_KNOWNHOSTS \- file name holding the SSH known hosts +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KNOWNHOSTS, char *fname); +.SH DESCRIPTION +Pass a pointer to a zero terminated string holding the file name of the +known_host file to use. The known_hosts file should use the OpenSSH file +format as supported by libssh2. If this file is specified, libcurl will only +accept connections with hosts that are known and present in that file, with a +matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default +behavior on host and key (mis)matching. +.SH DEFAULT +NULL +.SH PROTOCOLS +SFTP and SCP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSH_AUTH_TYPES "(3), " CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 new file mode 100644 index 0000000..f357f2c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_PRIVATE_KEYFILE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_PRIVATE_KEYFILE \- set private key file for SSH auth +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PRIVATE_KEYFILE, + char *filename); +.SH DESCRIPTION +Pass a char * pointing to a \fIfilename\fP for your private key. If not used, +libcurl defaults to \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable +is set, and just "id_dsa" in the current directory if HOME is not set. + +If the file is password-protected, set the password with +\fICURLOPT_KEYPASSWD(3)\fP. +.SH DEFAULT +As explained above +.SH PROTOCOLS +SFTP and SCP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 new file mode 100644 index 0000000..35f2a19 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSH_PUBLIC_KEYFILE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSH_PUBLIC_KEYFILE \- set public key file for SSH auth +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_PUBLIC_KEYFILE, + char *filename); +.SH DESCRIPTION +Pass a char * pointing to a \fIfilename\fP for your public key. If not used, +libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment +variable is set, and just "id_dsa.pub" in the current directory if HOME is not +set. + +If an empty string is passed, libcurl will pass no public key to libssh2 which +then tries to compute it from the private key, this is known to work when +libssh2 1.4.0+ is linked against OpenSSL. +.SH DEFAULT +As explained above +.SH PROTOCOLS +SFTP and SCP +.SH EXAMPLE +TODO +.SH AVAILABILITY +The "" trick was added in 7.26.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSH_PRIVATE_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.3 b/docs/libcurl/opts/CURLOPT_SSLCERT.3 new file mode 100644 index 0000000..7ae54f1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.3 @@ -0,0 +1,55 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLCERT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLCERT \- set SSL client certificate +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERT, char *cert); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your client certificate. The default format is "P12" on +Secure Transport and "PEM" on other engines, and can be changed with +\fICURLOPT_SSLCERTTYPE(3)\fP. + +With NSS or Secure Transport, this can also be the nickname of the certificate +you wish to authenticate with as it is named in the security database. If you +want to use a file from the current directory, please precede it with "./" +prefix, in order to avoid confusion with a nickname. + +When using a client certificate, you most likely also need to provide a +private key with \fICURLOPT_SSLKEY(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLCERTTYPE "(3), " CURLOPT_SSLKEY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 new file mode 100644 index 0000000..b19d517 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLCERTTYPE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLCERTTYPE \- specify type of the client SSL certificate +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLCERTTYPE, char *type); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your certificate. Supported formats are "PEM" and "DER", except +with Secure Transport. OpenSSL (versions 0.9.3 and later) and Secure Transport +(on iOS 5 or later, or OS X 10.7 or later) also support "P12" for +PKCS#12-encoded files. +.SH DEFAULT +"PEM" +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. Added in 7.9.3 +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLCERT "(3), " CURLOPT_SSLKEY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 new file mode 100644 index 0000000..a88a5a7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLENGINE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLENGINE \- set SSL engine identifier +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE, char *id); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It will be used as +the identifier for the crypto engine you want to use for your private key. + +If the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is +returned. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLENGINE_DEFAULT "(3), " CURLOPT_SSLKEY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 new file mode 100644 index 0000000..6570df1 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLENGINE_DEFAULT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLENGINE_DEFAULT \- make SSL engine default +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLENGINE_DEFAULT, long val); +.SH DESCRIPTION +Pass a long set to 1 as parameter. Sets the actual crypto engine as the +default for (asymmetric) crypto operations. + +If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is +returned. +.SH DEFAULT +None +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLENGINE "(3), " CURLOPT_SSLCERT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_SSLKEY.3 new file mode 100644 index 0000000..add69d8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLKEY 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLKEY \- specify private keyfile for TLS and SSL client cert +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEY, char *keyfile); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your private key. The default format is "PEM" and can be +changed with \fICURLOPT_SSLKEYTYPE(3)\fP. + +(iOS and Mac OS X only) This option is ignored if curl was built against +Secure Transport. Secure Transport expects the private key to be already +present in the keychain or PKCS#12 file containing the certificate. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLKEYTYPE "(3), " CURLOPT_SSLCERT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 new file mode 100644 index 0000000..d491634 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 @@ -0,0 +1,50 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLKEYTYPE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLKEYTYPE \- set type of the private key file +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLKEYTYPE, char *type); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". + +The format "ENG" enables you to load the private key from a crypto engine. In +this case \fICURLOPT_SSLKEY(3)\fP is used as an identifier passed to the +engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE(3)\fP. +\&"DER" format key file currently does not work because of a bug in OpenSSL. +.SH DEFAULT +"PEM" +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLKEY "(3), " CURLOPT_SSLCERT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_SSLVERSION.3 new file mode 100644 index 0000000..a10dabd --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.3 @@ -0,0 +1,78 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSLVERSION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSLVERSION \- set preferred TLS/SSL version +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSLVERSION, long version); +.SH DESCRIPTION +Pass a long as parameter to control which version of SSL/TLS to attempt to +use. + +Use one of the available defines for this purpose. The available options are: +.RS +.IP CURL_SSLVERSION_DEFAULT +The default action. This will attempt to figure out the remote SSL protocol +version. +.IP CURL_SSLVERSION_TLSv1 +TLSv1.x +.IP CURL_SSLVERSION_SSLv2 +SSLv2 +.IP CURL_SSLVERSION_SSLv3 +SSLv3 +.IP CURL_SSLVERSION_TLSv1_0 +TLSv1.0 (Added in 7.34.0) +.IP CURL_SSLVERSION_TLSv1_1 +TLSv1.1 (Added in 7.34.0) +.IP CURL_SSLVERSION_TLSv1_2 +TLSv1.2 (Added in 7.34.0) +.RE +.SH DEFAULT +CURL_SSLVERSION_DEFAULT +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* ask libcurl to use TLS version 1.0 or later */ + curl_easy_setopt(curl, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +SSLv2 is disabled by default since 7.18.1. Other SSL versions availability may +vary depending on which backend libcurl has been built to use. + +SSLv3 is disabled by default since 7.39.0. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_USE_SSL "(3), " CURLOPT_HTTP_VERSION "(3), " +.BR CURLOPT_IPRESOLVE "(3) " diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 new file mode 100644 index 0000000..7e05a59 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 @@ -0,0 +1,65 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSL_CIPHER_LIST 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_CIPHER_LIST \- specify ciphers to use for TLS +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list); +.SH DESCRIPTION +Pass a char *, pointing to a zero terminated string holding the list of +ciphers to use for the SSL connection. The list must be syntactically correct, +it consists of one or more cipher strings separated by colons. Commas or +spaces are also acceptable separators but colons are normally used, \&!, \&- +and \&+ can be used as operators. + +For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', +\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you +compile OpenSSL. + +You'll find more details about cipher lists on this URL: + + http://www.openssl.org/docs/apps/ciphers.html + +For NSS, valid examples of cipher lists include 'rsa_rc4_128_md5', +\'rsa_aes_128_sha\', etc. With NSS you don't add/remove ciphers. If one uses +this option then all known ciphers are disabled and only those passed in are +enabled. + +You'll find more details about the NSS cipher lists on this URL: + + http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives +.SH DEFAULT +NULL, use internal default +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSLVERSION "(3), " CURLOPT_USE_SSL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 new file mode 100644 index 0000000..977cc12 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.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_SSL_CTX_DATA 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_CTX_DATA \- custom pointer passed to ssl_ctx callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_DATA, void *pointer); +.SH DESCRIPTION +Data \fIpointer\fP to pass to the ssl context callback set by the option +\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you'll get as third +parameter. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.11.0 for OpenSSL. Added in 7.42.0 for wolfSSL/CyaSSL. Other SSL +backends not supported. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSL_CTX_FUNCTION "(3), " CURLOPT_SSLVERSION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 new file mode 100644 index 0000000..e3e0170 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 @@ -0,0 +1,71 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSL_CTX_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_CTX_FUNCTION \- SSL context callback for OpenSSL or wolfSSL/CyaSSL +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *userptr); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION, + ssl_ctx_callback); +.SH DESCRIPTION +This option only works for libcurl powered by OpenSSL or wolfSSL/CyaSSL. If +libcurl was built against another SSL library this functionality is absent. + +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl just before the initialization +of an SSL connection after having processed all other SSL related options to +give a last chance to an application to modify the behaviour of the SSL +initialization. The \fIssl_ctx\fP parameter is actually a pointer to the SSL +library's \fISSL_CTX\fP. If an error is returned from the callback no attempt +to establish a connection is made and the perform operation will return the +callback's error code. Set the \fIuserptr\fP argument with the +\fICURLOPT_SSL_CTX_DATA(3)\fP option. + +This function will get called on all new connections made to a server, during +the SSL negotiation. The SSL_CTX pointer will be a new one every time. + +To use this properly, a non-trivial amount of knowledge of your SSL library +is necessary. For example, you can use this function to call library-specific +callbacks to add additional validation code for certificates, and even to +change the actual URI of a HTTPS request (example used in the lib509 test +case). See also the example section for a replacement of the key, certificate +and trust file settings. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.11.0 for OpenSSL. Added in 7.42.0 for wolfSSL/CyaSSL. Other SSL +backends not supported. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSL_CTX_DATA "(3), " CURLOPT_SSL_VERIFYPEER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 new file mode 100644 index 0000000..6716f72 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSL_ENABLE_ALPN 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_ENABLE_ALPN \- enable ALPN +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_ALPN, long npn); +.SH DESCRIPTION +Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This +option enables/disables ALPN in the SSL handshake (if the SSL backend libcurl +is built to use supports it), which can be used to negotiate http2. +.SH DEFAULT +1, enabled +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.36.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSL_ENABLE_NPN "(3), " CURLOPT_SSL_OPTIONS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 new file mode 100644 index 0000000..5db9b51 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSL_ENABLE_NPN 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_ENABLE_NPN \- enable NPN +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_ENABLE_NPN, long npn); +.SH DESCRIPTION +Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This +option enables/disables NPN in the SSL handshake (if the SSL backend libcurl +is built to use supports it), which can be used to negotiate http2. +.SH DEFAULT +1, enabled +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.36.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSL_ENABLE_ALPN "(3), " CURLOPT_SSL_OPTIONS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 new file mode 100644 index 0000000..31a05e6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_SSL_FALSESTART 3 "14 Feb 2015" "libcurl 7.41.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_FALSESTART \- enable TLS false start +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable); +.SH DESCRIPTION +Pass a long as parameter set to 1 to enable or 0 to disable. + +This option determines whether libcurl should use false start during the TLS +handshake. False start is a mode where a TLS client will start sending +application data before verifying the server's Finished message, thus saving a +round trip when performing a full handshake. +.SH DEFAULT +0 +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.42.0. This option is currently only supported by the NSS and +Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends. +.SH RETURN VALUE +Returns CURLE_OK if false start is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 new file mode 100644 index 0000000..09bcb96 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSL_OPTIONS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_OPTIONS \- set SSL behavior options +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask); +.SH DESCRIPTION +Pass a long with a bitmask to tell libcurl about specific SSL behaviors. + +\fICURLSSLOPT_ALLOW_BEAST\fP is the only supported bit and by setting this the +user will tell libcurl to not attempt to use any workarounds for a security +flaw in the SSL3 and TLS1.0 protocols. If this option isn't used or this bit +is set to 0, the SSL layer libcurl uses may use a work-around for this flaw +although it might cause interoperability problems with some (older) SSL +implementations. WARNING: avoiding this work-around lessens the security, and +by setting this option to 1 you ask for exactly that. +.SH DEFAULT +0 +.SH PROTOCOLS +All TLS-based protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSLVERSION "(3), " CURLOPT_SSL_CIPHER_LIST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 new file mode 100644 index 0000000..4baa061 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_SSL_SESSIONID_CACHE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_SESSIONID_CACHE \- enable/disable use of the SSL session-ID cache +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_SESSIONID_CACHE, + long enabled); +.SH DESCRIPTION +Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set +this to 1 to enable it. By default all transfers are done using the cache +enabled. While nothing ever should get hurt by attempting to reuse SSL +session-IDs, there seem to be or have been broken SSL implementations in the +wild that may require you to disable this in order for you to succeed. +.SH DEFAULT +1 +.SH PROTOCOLS +All TLS-based +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.16.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_SSLVERSION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 new file mode 100644 index 0000000..fbf2042 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 @@ -0,0 +1,87 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_SSL_VERIFYHOST 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_VERIFYHOST \- verify the certificate's name against host +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify); +.SH DESCRIPTION +Pass a long as parameter specifying what to \fIverify\fP. + +This option determines whether libcurl verifies that the server cert is for +the server it is known as. + +When negotiating TLS and SSL connections, the server sends a certificate +indicating its identity. + +When \fICURLOPT_SSL_VERIFYHOST(3)\fP is 2, that certificate must indicate that +the server is the server to which you meant to connect, or the connection +fails. Simply put, it means it has to have the same name in the certificate as +is in the URL you operate against. + +Curl considers the server the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the host name in the +URL to which you told Curl to connect. + +When the \fIverify\fP value is 1, \fIcurl_easy_setopt\fP will return an error +and the option value will not be changed. It was previously (in 7.28.0 and +earlier) a debug option of some sorts, but it is no longer supported due to +frequently leading to programmer mistakes. Future versions will stop returning +an error for 1 and just treat 1 and 2 the same. + +When the \fIverify\fP value is 0, the connection succeeds regardless of the +names in the certificate. Use that ability with caution! + +The default value for this option is 2. + +This option controls checking the server's certificate's claimed identity. +The server could be lying. To control lying, see +\fICURLOPT_SSL_VERIFYPEER(3)\fP. If libcurl is built against NSS and +\fICURLOPT_SSL_VERIFYPEER(3)\fP is zero, \fICURLOPT_SSL_VERIFYHOST(3)\fP is +also set to zero and cannot be overridden. +.SH DEFAULT +2 +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict name check please */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not. + +If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned. +.SH "SEE ALSO" +.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_CAINFO "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 new file mode 100644 index 0000000..81bb593 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 @@ -0,0 +1,81 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_SSL_VERIFYPEER 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_VERIFYPEER \- verify the peer's SSL certificate +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYPEER, long verify); +.SH DESCRIPTION +Pass a long as parameter to enable or disable. + +This option determines whether curl verifies the authenticity of the peer's +certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. + +When negotiating a TLS or SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is authentic, +i.e. that you can trust that the server is who the certificate says it is. +This trust is based on a chain of digital signatures, rooted in certification +authority (CA) certificates you supply. curl uses a default bundle of CA +certificates (the path for that is determined at build time) and you can +specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the +\fICURLOPT_CAPATH(3)\fP option. + +When \fICURLOPT_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to +prove that the certificate is authentic, the connection fails. When the +option is zero, the peer certificate verification succeeds regardless. + +Authenticating the certificate is not enough to be sure about the server. You +typically also want to ensure that the server is the server you mean to be +talking to. Use \fICURLOPT_SSL_VERIFYHOST(3)\fP for that. The check that the +host name in the certificate is valid for the host name you're connecting to +is done independently of the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. + +WARNING: disabling verification of the certificate allows bad guys to +man-in-the-middle the communication without you knowing it. Disabling +verification makes the communication insecure. Just having encryption on a +transfer is not enough as you cannot be sure that you are communicating with +the correct end-point. +.SH DEFAULT +By default, curl assumes a value of 1. +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); + + /* Set the default value: strict certificate check please */ + curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 new file mode 100644 index 0000000..d7f011a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 @@ -0,0 +1,53 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_SSL_VERIFYSTATUS 3 "04 Dec 2014" "libcurl 7.40.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_SSL_VERIFYSTATUS \- verify the certificate's status +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYSTATUS, long verify); +.SH DESCRIPTION +Pass a long as parameter set to 1 to enable or 0 to disable. + +This option determines whether libcurl verifies the status of the server cert +using the "Certificate Status Request" TLS extension (aka. OCSP stapling). + +Note that if this option is enabled but the server does not support the TLS +extension, the verification will fail. +.SH DEFAULT +0 +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc. +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.41.0. This option is currently only supported by the OpenSSL, GnuTLS +and NSS TLS backends. +.SH RETURN VALUE +Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. +.SH "SEE ALSO" +.BR CURLOPT_SSL_VERIFYHOST "(3), " +.BR CURLOPT_SSL_VERIFYPEER "(3), " +.BR CURLOPT_CAINFO "(3), " diff --git a/docs/libcurl/opts/CURLOPT_STDERR.3 b/docs/libcurl/opts/CURLOPT_STDERR.3 new file mode 100644 index 0000000..8ef1a32 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_STDERR.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_STDERR 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_STDERR \- redirect stderr to another stream +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STDERR, FILE *stream); +.SH DESCRIPTION +Pass a FILE * as parameter. Tell libcurl to use this \fIstream\fP instead of +stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP +data. +.SH DEFAULT +stderr +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +FILE *filep = fopen("dump", "wb"); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + curl_easy_setopt(curl, CURLOPT_STDERR, filep); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 new file mode 100644 index 0000000..941cc48 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 @@ -0,0 +1,63 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_TCP_KEEPALIVE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TCP_KEEPALIVE \- enable TCP keep-alive probing +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPALIVE, long probe); +.SH DESCRIPTION +Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and +frequency of these probes can be controlled by the +\fICURLOPT_TCP_KEEPIDLE(3)\fP and \fICURLOPT_TCP_KEEPINTVL(3)\fP options, +provided the operating system supports them. Set to 0 (default behavior) to +disable keepalive probes +.SH DEFAULT +0 +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_TCP_KEEPIDLE "(3), " CURLOPT_TCP_KEEPINTVL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 new file mode 100644 index 0000000..d60a3df --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_TCP_KEEPIDLE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TCP_KEEPIDLE \- set TCP keep-alive idle time wait +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPIDLE, long delay); +.SH DESCRIPTION +Pass a long. Sets the \fIdelay\fP, in seconds, that the operating system will +wait while the connection is idle before sending keepalive probes. Not all +operating systems support this option. +.SH DEFAULT +? +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* set keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.25.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_TCP_KEEPALIVE "(3), " CURLOPT_TCP_KEEPINTVL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 new file mode 100644 index 0000000..42bc0b4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 @@ -0,0 +1,59 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_TCP_KEEPINTVL 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TCP_KEEPINTVL \- set TCP keep-alive interval +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_KEEPINTVL, long interval); +.SH DESCRIPTION +Pass a long. Sets the interval, in seconds, that the operating system will +wait between sending keepalive probes. Not all operating systems support this +option. (Added in 7.25.0) +.SH DEFAULT +.SH PROTOCOLS +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* enable TCP keep-alive for this transfer */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); + + /* keep-alive idle time to 120 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); + + /* interval time between keep-alive probes: 60 seconds */ + curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_TCP_KEEPALIVE "(3), " CURLOPT_TCP_KEEPIDLE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 new file mode 100644 index 0000000..bd13516 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TCP_NODELAY 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TCP_NODELAY \- set the TCP_NODELAY option +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay); +.SH DESCRIPTION +Pass a long specifying whether the TCP_NODELAY option is to be set or cleared +(1 = set, 0 = clear). The option is cleared by default. This will have no +effect after the connection has been established. + +Setting this option will disable TCP's Nagle algorithm. The purpose of this +algorithm is to try to minimize the number of small packets on the network +(where "small packets" means TCP segments less than the Maximum Segment Size +(MSS) for the network). + +Maximizing the amount of data sent per TCP segment is good because it +amortizes the overhead of the send. However, in some cases small segments may +need to be sent without delay. This is less efficient than sending larger +amounts of data at a time, and can contribute to congestion on the network if +overdone. +.SH DEFAULT +0 +.SH PROTOCOLS +All +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_SOCKOPTFUNCTION "(3), " CURLOPT_TCP_KEEPALIVE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 new file mode 100644 index 0000000..f5a9bc5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TELNETOPTIONS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TELNETOPTIONS \- custom telnet options +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TELNETOPTIONS, + struct curl_slist *cmds); +.SH DESCRIPTION +Provide a pointer to a curl_slist with variables to pass to the telnet +negotiations. The variables should be in the format <option=value>. libcurl +supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. See the TELNET +standard for details. +.SH DEFAULT +NULL +.SH PROTOCOLS +TELNET +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with TELNET +.SH RETURN VALUE +Returns CURLE_OK if TELNET is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HTTPHEADER "(3), " CURLOPT_QUOTE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 new file mode 100644 index 0000000..05bc639 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TFTP_BLKSIZE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TFTP_BLKSIZE \- TFTP block size +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TFTP_BLKSIZE, long blocksize); +.SH DESCRIPTION +Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per +RFC2348 is 8-65464 bytes. The default of 512 bytes will be used if this option +is not specified. The specified block size will only be used pending support +by the remote server. If the server does not return an option acknowledgement +or returns an option acknowledgement with no blksize, the default of 512 bytes +will be used. +.SH DEFAULT +512 +.SH PROTOCOLS +TFTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_MAXFILESIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 new file mode 100644 index 0000000..66c34ff --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TIMECONDITION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TIMECONDITION \- select condition for a time request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMECONDITION, long cond); +.SH DESCRIPTION +Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE(3)\fP time +value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP +or \fICURL_TIMECOND_IFUNMODSINCE\fP. + +The last modification time of a file is not always known and in such instances +this feature will have no effect even if the given time condition would not +have been met. \fIcurl_easy_getinfo(3)\fP with the +\fICURLINFO_CONDITION_UNMET\fP option can be used after a transfer to learn if +a zero-byte successful "transfer" was due to this condition not matching. +.SH DEFAULT +CURL_TIMECOND_NONE (0) +.SH PROTOCOLS +HTTP, FTP, RTSP, and FILE +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMEVALUE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 new file mode 100644 index 0000000..6440ffe --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_TIMEOUT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TIMEOUT \- set maximum time the request is allowed to take +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT, long timeout); +.SH DESCRIPTION +Pass a long as parameter containing \fItimeout\fP - the maximum time in +seconds that you allow the libcurl transfer operation to take. Normally, name +lookups can take a considerable time and limiting operations to less than a +few minutes risk aborting perfectly normal operations. This option may cause +libcurl to use the SIGALRM signal to timeout system calls. + +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL(3)\fP is set. + +If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the +value set last will be used. + +Since this puts a hard limit for how long time a request is allowed to take, +it has limited use in dynamic use cases with varying transfer times. You are +then advised to explore \fICURLOPT_LOW_SPEED_LIMIT(3)\fP, +\fICURLOPT_LOW_SPEED_TIME(3)\fP or using \fICURLOPT_PROGRESSFUNCTION(3)\fP to +implement your own timeout logic. +.SH DEFAULT +Default timeout is 0 (zero) which means it never times out during transfer. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* complete within 20 seconds */ + curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT_MS "(3), " +.BR CURLOPT_CONNECTTIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 new file mode 100644 index 0000000..3727133 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 @@ -0,0 +1,74 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_TIMEOUT_MS 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TIMEOUT_MS \- set maximum time the request is allowed to take +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEOUT_MS, long timeout); +.SH DESCRIPTION +Pass a long as parameter containing \fItimeout\fP - the maximum time in +milliseconds that you allow the libcurl transfer operation to take. Normally, +name lookups can take a considerable time and limiting operations to less than +a few minutes risk aborting perfectly normal operations. This option may cause +libcurl to use the SIGALRM signal to timeout system calls. + +If libcurl is built to use the standard system name resolver, that portion of +the transfer will still use full-second resolution for timeouts with a minimum +timeout allowed of one second. + +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL(3)\fP is set. + +If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the +value set last will be used. + +Since this puts a hard limit for how long time a request is allowed to take, +it has limited use in dynamic use cases with varying transfer times. You are +then advised to explore \fICURLOPT_LOW_SPEED_LIMIT(3)\fP, +\fICURLOPT_LOW_SPEED_TIME(3)\fP or using \fICURLOPT_PROGRESSFUNCTION(3)\fP to +implement your own timeout logic. +.SH DEFAULT +Default timeout is 0 (zero) which means it never times out during transfer. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* complete within 20000 milliseconds */ + curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 20000L); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT "(3), " +.BR CURLOPT_CONNECTTIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 new file mode 100644 index 0000000..43a3871 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 @@ -0,0 +1,45 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TIMEVALUE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TIMEVALUE \- set time value for conditional +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TIMEVALUE, long val); +.SH DESCRIPTION +Pass a long \fIval\fP as parameter. This should be the time counted as seconds +since 1 Jan 1970, and the time will be used in a condition as specified with +\fICURLOPT_TIMECONDITION(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP, FTP, RTSP, and FILE +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_TIMECONDITION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 new file mode 100644 index 0000000..1c8697f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TLSAUTH_PASSWORD 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TLSAUTH_PASSWORD \- password to use for TLS authentication +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_PASSWORD, char *pwd); +.SH DESCRIPTION +Pass a char * as parameter, which should point to the zero terminated password +to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the +\fICURLOPT_TLSAUTH_USERNAME(3)\fP option also be set. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS-based protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_TLSAUTH_TYPE "(3), " CURLOPT_TLSAUTH_USERNAME "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 new file mode 100644 index 0000000..b5cdd5b --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 @@ -0,0 +1,52 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TLSAUTH_TYPE 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TLSAUTH_TYPE \- set TLS authentication methods +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_TYPE, long bitmask); +.SH DESCRIPTION +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) you want it to use for TLS authentication. + +.IP CURL_TLSAUTH_SRP +TLS-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC5054 and provides mutual authentication if both sides have a +shared secret. To use TLS-SRP, you must also set the +\fICURLOPT_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_TLSAUTH_PASSWORD(3)\fP +options. +.SH DEFAULT +CURL_TLSAUTH_NONE (0) +.SH PROTOCOLS +All TLS-based protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this +to work. Added in 7.21.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_TLSAUTH_USERNAME "(3), " CURLOPT_TLSAUTH_PASSWORD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 new file mode 100644 index 0000000..c5bb2df --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TLSAUTH_USERNAME 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TLSAUTH_USERNAME \- user name to use for TLS authentication +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_USERNAME, char *user); +.SH DESCRIPTION +Pass a char * as parameter, which should point to the zero terminated username +to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the +\fICURLOPT_TLSAUTH_PASSWORD(3)\fP option also be set. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS-based protocols +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.4 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_TLSAUTH_TYPE "(3), " CURLOPT_TLSAUTH_PASSWORD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 new file mode 100644 index 0000000..6e62413 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 @@ -0,0 +1,51 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TRANSFERTEXT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TRANSFERTEXT \- request a text based transfer for FTP +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFERTEXT, long text); +.SH DESCRIPTION +A parameter set to 1 tells the library to use ASCII mode for FTP transfers, +instead of the default binary transfer. For win32 systems it does not set the +stdout to binary mode. This option can be usable when transferring text data +between systems with different views on certain characters, such as newlines +or similar. + +libcurl does not do a complete ASCII conversion when doing ASCII transfers +over FTP. This is a known limitation/flaw that nobody has rectified. libcurl +simply sets the mode to ASCII and performs a standard transfer. +.SH DEFAULT +0, disabled +.SH PROTOCOLS +FTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with FTP +.SH RETURN VALUE +Returns CURLE_OK if FTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_CRLF "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 new file mode 100644 index 0000000..7f2a11c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 @@ -0,0 +1,54 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TRANSFER_ENCODING 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING, long enable); +.SH DESCRIPTION +Pass a long set to 1 to \fIenable\fP or 0 to disable. + +Adds a request for compressed Transfer Encoding in the outgoing HTTP +request. If the server supports this and so desires, it can respond with the +HTTP response sent using a compressed Transfer-Encoding that will be +automatically uncompressed by libcurl on reception. + +Transfer-Encoding differs slightly from the Content-Encoding you ask for with +\fBCURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer-Encoding is strictly meant +to be for the transfer and thus MUST be decoded before the data arrives in the +client. Traditionally, Transfer-Encoding has been much less used and supported +by both HTTP clients and HTTP servers. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.21.6 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_ACCEPT_ENCODING "(3), " CURLOPT_HTTP_TRANSFER_DECODING "(3), " diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 new file mode 100644 index 0000000..a659cd2 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 @@ -0,0 +1,78 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_UNIX_SOCKET_PATH 3 "09 Oct 2014" "libcurl 7.40.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_UNIX_SOCKET_PATH \- set Unix domain socket +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNIX_SOCKET_PATH, char *path); +.SH DESCRIPTION +Enables the use of Unix domain sockets as connection endpoint and sets the path +to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are disabled. An +empty string will result in an error at some point, it will not disable use of +Unix domain sockets. + +When enabled, cURL will connect to the Unix domain socket instead of +establishing a TCP connection to a host. Since no TCP connection is created, +cURL does not need to resolve the DNS hostname in the URL. + +The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms +it might be even less. + +Proxy and TCP options such as +.BR CURLOPT_TCP_NODELAY "(3) +are not supported. Proxy options such as +.BR CURLOPT_PROXY "(3) +have no effect either as these are TCP-oriented, and asking a proxy server to +connect to a certain Unix domain socket is not possible. +.SH DEFAULT +Default is NULL, meaning that no Unix domain sockets are used. +.SH PROTOCOLS +All protocols except for file:// and FTP are supported in theory. HTTP, IMAP, +POP3 and SMTP should in particular work (including their SSL/TLS variants). +.SH EXAMPLE +Given that you have an nginx server running, listening on /tmp/nginx.sock, you +can request a HTTP resource with: + +.nf + curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock"); + curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/"); +.fi + +If you are on Linux and somehow have a need for paths larger than 107 bytes, you +could use the proc filesystem to bypass the limitation: + +.nf + int dirfd = open(long_directory_path_to_socket, O_DIRECTORY | O_RDONLY); + char path[108]; + snprintf(path, sizeof(path), "/proc/self/fd/%d/nginx.sock", dirfd); + curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path); + /* Be sure to keep dirfd valid until you discard the handle */ +.fi +.SH AVAILABILITY +Since 7.40.0. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_OPENSOCKETFUNCTION "(3), " unix "(7), " diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 new file mode 100644 index 0000000..68c3860 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_UNRESTRICTED_AUTH 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH, + long goahead); +.SH DESCRIPTION +A long parameter set to 1 tells libcurl it can continue to send authentication +(user+password) credentials when following locations, even when hostname +changed. This option is meaningful only when setting +\fICURLOPT_FOLLOWLOCATION(3)\fP. +.SH DEFAULT +0 +.SH PROTOCOLS +HTTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Along with HTTP +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FOLLOWLOCATION "(3), " CURLOPT_USERPWD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.3 b/docs/libcurl/opts/CURLOPT_UPLOAD.3 new file mode 100644 index 0000000..d24bd28 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_UPLOAD.3 @@ -0,0 +1,78 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_UPLOAD 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_UPLOAD \- enable data upload +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UPLOAD, long upload); +.SH DESCRIPTION +The long parameter \fIupload\fP set to 1 tells the library to prepare for and +perform an upload. The \fICURLOPT_READDATA(3)\fP and +\fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP options are +also interesting for uploads. If the protocol is HTTP, uploading means using +the PUT request unless you tell libcurl otherwise. + +Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. + +If you use PUT to a HTTP 1.1 server, you can upload data without knowing the +size before starting the transfer if you use chunked encoding. You enable this +by adding a header like "Transfer-Encoding: chunked" with +\fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you +must specify the size. +.SH DEFAULT +0, default is download +.SH PROTOCOLS +Most +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + /* we want to use our own read function */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); + + /* enable uploading */ + curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); + + /* specify target */ + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); + + /* now specify which pointer to pass to our callback */ + curl_easy_setopt(curl, CURLOPT_READDATA, hd_src); + + /* Set the size of the file to upload */ + curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); + + /* Now run off and do what you've been told! */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_PUT "(3), " CURLOPT_READFUNCTION "(3), " +.BR CURLOPT_INFILESIZE_LARGE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.3 new file mode 100644 index 0000000..6e4824a --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_URL.3 @@ -0,0 +1,333 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_URL 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_URL \- provide the URL to use in the request +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_URL, char *URL); +.SH DESCRIPTION +Pass in a pointer to the \fIURL\fP to work with. The parameter should be a +char * to a zero terminated string which must be URL-encoded in the following +format: + +scheme://host:port/path + +For a greater explanation of the format please see RFC3986. + +libcurl doesn't validate the syntax or use this variable until the transfer is +issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP will +still return \fICURLE_OK\fP. + +If the given URL lacks the scheme (such as "http://" or "ftp://" etc) then +libcurl will attempt to resolve the protocol based on one of the following +given host names: HTTP, FTP, DICT, LDAP, IMAP, POP3 or SMTP + +Should the protocol, either that specified by the scheme or deduced by libcurl +from the host name, not be supported by libcurl then +\fICURLE_UNSUPPORTED_PROTOCOL\fP will be returned from either the +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you +call them. Use \fIcurl_version_info(3)\fP for detailed information of which +protocols are supported by the build of libcurl you are using. + +\fICURLOPT_PROTOCOLS(3)\fP can be used to limit what protocols libcurl will +use for this transfer, independent of what libcurl has been compiled to +support. That may be useful if you accept the URL from an external source and +want to limit the accessibility. + +\fICURLOPT_URL(3)\fP is the only option that \fBmust\fP be set before a +transfer is started. + +The host part of the URL contains the address of the server that you want to +connect to. This can be the fully qualified domain name of the server, the +local network name of the machine on your network or the IP address of the +server or machine represented by either an IPv4 or IPv6 address. For example: + +http://www.example.com/ + +http://hostname/ + +http://192.168.0.1/ + +http://[2001:1890:1112:1::20]/ + +It is also possible to specify the user name, password and any supported login +options as part of the host, for the following protocols, when connecting to +servers that require authentication: + +http://user:password@www.example.com + +ftp://user:password@ftp.example.com + +smb://domain%2fuser:password@server.example.com + +imap://user:password;options@mail.example.com + +pop3://user:password;options@mail.example.com + +smtp://user:password;options@mail.example.com + +At present only IMAP, POP3 and SMTP support login options as part of the host. +For more information about the login options in URL syntax please see RFC2384, +RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). + +The port is optional and when not specified libcurl will use the default port +based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25 +for SMTP, etc. The following examples show how to specify the port: + +http://www.example.com:8080/ - This will connect to a web server using port +8080 rather than 80. + +smtp://mail.example.com:587/ - This will connect to a SMTP server on the +alternative mail port. + +The path part of the URL is protocol specific and whilst some examples are +given below this list is not conclusive: + +.IP HTTP +The path part of a HTTP request specifies the file to retrieve and from what +directory. If the directory is not specified then the web server's root +directory is used. If the file is omitted then the default document will be +retrieved for either the directory specified or the root directory. The exact +resource returned for each URL is entirely dependent on the server's +configuration. + +http://www.example.com - This gets the main page from the web server. + +http://www.example.com/index.html - This returns the main page by explicitly +requesting it. + +http://www.example.com/contactus/ - This returns the default document from +the contactus directory. + +.IP FTP +The path part of an FTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the directory is omitted then +the directory listing for the root / home directory will be returned. + +ftp://ftp.example.com - This retrieves the directory listing for the root +directory. + +ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the +root directory. + +ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the +libcurl directory. + +ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt +file from the user's home directory. When a username and password is +specified, everything that is specified in the path part is relative to the +user's home directory. To retrieve files from the root directory or a +directory underneath the root directory then the absolute path must be +specified by prepending an additional forward slash to the beginning of the +path. + +ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt +from the root directory when logging in as a specified user. + +.IP SMTP +The path part of a SMTP request specifies the host name to present during +communication with the mail server. If the path is omitted then libcurl will +attempt to resolve the local computer's host name. However, this may not +return the fully qualified domain name that is required by some mail servers +and specifying this path allows you to set an alternative name, such as +your machine's fully qualified domain name, which you might have obtained +from an external function such as gethostname or getaddrinfo. + +smtp://mail.example.com - This connects to the mail server at example.com and +sends your local computer's host name in the HELO / EHLO command. + +smtp://mail.example.com/client.example.com - This will send client.example.com in +the HELO / EHLO command to the mail server at example.com. + +.IP POP3 +The path part of a POP3 request specifies the message ID to retrieve. If the +ID is not specified then a list of waiting messages is returned instead. + +pop3://user:password@mail.example.com - This lists the available messages for +the user + +pop3://user:password@mail.example.com/1 - This retrieves the first message for +the user + +.IP IMAP +The path part of an IMAP request not only specifies the mailbox to list (Added +in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the +mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets +(Added in 7.37.0) of the message to fetch and to specify what messages to +search for (Added in 7.37.0). + +imap://user:password@mail.example.com - Performs a top level folder list + +imap://user:password@mail.example.com/INBOX - Performs a folder list on the +user's inbox + +imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox +and fetches message 1 + +imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects +the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches +message 2 if it is + +imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the +user's inbox and fetches the text portion of message 3 + +imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects +the user's inbox and fetches the first 1024 octets of message 4 + +imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and +checks for NEW messages + +imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the +user's inbox and searches for messages containing "shadows" in the subject +line + +For more information about the individual components of an IMAP URL please +see RFC5092. + +.IP SCP +The path part of a SCP request specifies the file to retrieve and from what +directory. The file part may not be omitted. The file is taken as an absolute +path from the root directory on the server. To specify a path relative to the +user's home directory on the server, prepend ~/ to the path portion. If the +user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. + +scp://user@example.com/etc/issue - This specifies the file /etc/issue + +scp://example.com/~/my-file - This specifies the file my-file in the +user's home directory on the server + +.IP SFTP +The path part of a SFTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the path ends in a / then a directory +listing is returned instead of a file. If the path is omitted entirely then +the directory listing for the root / home directory will be returned. If the +user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. + +sftp://user:password@example.com/etc/issue - This specifies the file +/etc/issue + +sftp://user@example.com/~/my-file - This specifies the file my-file in the +user's home directory + +sftp://ssh.example.com/~/Documents/ - This requests a directory listing +of the Documents directory under the user's home directory + +.IP SMB +The path part of a SMB request specifies the file to retrieve and from what +share and directory or the share to upload to and as such, may not be omitted. +If the user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name +is embedded in the URL then it must contain the domain name and as such, the +backslash must be URL encoded as %2f. + +smb://server.example.com/files/issue - This specifies the file "issue" located +in the root of the "files" share + +smb://server.example.com/files/ -T issue - This specifies the file "issue" will +be uploaded to the root of the "files" share. + +.IP LDAP +The path part of a LDAP request can be used to specify the: Distinguished +Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field +is separated by a question mark and when that field is not required an empty +string with the question mark separator should be included. + +ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search +with the DN as My Organisation. + +ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform +the same search but will only return postalAddress attributes. + +ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN +and requests information about the rootDomainNamingContext attribute for an +Active Directory server. + +For more information about the individual components of a LDAP URL please +see RFC4516. +.IP RTMP +There's no official URL spec for RTMP so libcurl uses the URL syntax supported +by the underlying librtmp library. It has a syntax where it wants a +traditional URL, followed by a space and a series of space-separated +name=value pairs. + +While space is not typically a "legal" letter, libcurl accepts them. When a +user wants to pass in a '#' (hash) character it will be treated as a fragment +and get cut off by libcurl if provided literally. You will instead have to +escape it by providing it as backslash and its ASCII value in hexadecimal: +"\\23". +.SH DEFAULT +There is no default URL. If this option isn't set, no transfer can be +performed. +.SH SECURITY CONCERNS +Applications may at times find it convenient to allow users to specify URLs +for various purposes and that string would then end up fed to this option. + +Getting a URL from an external untrusted party will bring reasons for several +security concerns: + +If you have an application that runs as or in a server application, getting an +unfiltered URL can easily trick your application to access a local resource +instead of a remote. Protecting yourself against localhost accesses is very +hard when accepting user provided URLs. + +Such custom URLs can also access other ports than you planned as port numbers +are part of the regular URL format. The combination of a local host and a +custom port number can allow external users to play tricks with your local +services. + +Accepting external URLs may also use other protocols than http:// or other +common ones. Restrict what accept with \fICURLOPT_PROTOCOLS(3)\fP. + +User provided URLs can also be made to point to sites that redirect further on +(possibly to other protocols too). Consider your +\fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS(3)\fP settings. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +POP3 and SMTP were added in 7.31.0 +.SH RETURN VALUE +Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient +heap space. + +Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so +given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or +similar is called. +.SH "SEE ALSO" +.BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), " +.BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), " +.BR curl_easy_perform "(3)" diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.3 b/docs/libcurl/opts/CURLOPT_USERAGENT.3 new file mode 100644 index 0000000..4d7036d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.3 @@ -0,0 +1,56 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_USERAGENT 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_USERAGENT \- set HTTP user-agent header +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERAGENT, char *ua); +.SH DESCRIPTION +Pass a pointer to a zero terminated string as parameter. It will be used to +set the User-Agent: header in the HTTP request sent to the remote server. This +can be used to fool servers or scripts. You can also set any custom header +with \fICURLOPT_HTTPHEADER(3)\fP. +.SH DEFAULT +NULL, no User-Agent: header is used by default. +.SH PROTOCOLS +HTTP, HTTPS +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0"); + + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +As long as HTTP is supported +.SH RETURN VALUE +Returns CURLE_OK if HTTP is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_REFERER "(3), " CURLOPT_HTTPHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.3 b/docs/libcurl/opts/CURLOPT_USERNAME.3 new file mode 100644 index 0000000..7546f74 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERNAME.3 @@ -0,0 +1,71 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_USERNAME 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_USERNAME \- user name to use in authentication +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME, + char *username); +.SH DESCRIPTION +Pass a char * as parameter, which should be pointing to the zero terminated +user name to use for the transfer. + +\fBCURLOPT_USERNAME(3)\fP sets the user name to be used in protocol +authentication. You should not use this option together with the (older) +\fICURLOPT_USERPWD(3)\fP option. + +When using Kerberos V5 authentication with a Windows based server, you should +include the domain name in order for the server to successfully obtain a +Kerberos Ticket. If you don't then the initial part of the authentication +handshake may fail. + +When using NTLM, the user name can be specified simply as the user name +without the domain name should the server be part of a single domain and +forest. + +To include the domain name use either Down-Level Logon Name or UPN (User +Principal Name) formats. For example, EXAMPLE\\user and user@example.com +respectively. + +Some HTTP servers (on Windows) support inclusion of the domain for Basic +authentication as well. + +To specify the password and login options, along with the user name, use the +\fICURLOPT_PASSWORD(3)\fP and \fICURLOPT_LOGIN_OPTIONS(3)\fP options. +.SH DEFAULT +blank +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.19.1 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_USERPWD "(3), " CURLOPT_PASSWORD "(3), " +.BR CURLOPT_HTTPAUTH "(3), " CURLOPT_PROXYAUTH "(3)" diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.3 b/docs/libcurl/opts/CURLOPT_USERPWD.3 new file mode 100644 index 0000000..22e920f --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USERPWD.3 @@ -0,0 +1,76 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_USERPWD 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_USERPWD \- user name and password to use in authentication +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd); +.SH DESCRIPTION +Pass a char * as parameter, pointing to a zero terminated login details string +for the connection. The format of which is: [user name]:[password]. + +When using Kerberos V5 authentication with a Windows based server, you should +specify the user name part with the domain name in order for the server to +successfully obtain a Kerberos Ticket. If you don't then the initial part of +the authentication handshake may fail. + +When using NTLM, the user name can be specified simply as the user name +without the domain name should the server be part of a single domain and +forest. + +To specify the domain name use either Down-Level Logon Name or UPN (User +Principal Name) formats. For example, EXAMPLE\\user and user@example.com +respectively. + +Some HTTP servers (on Windows) support inclusion of the domain for Basic +authentication as well. + +When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform +several requests to possibly different hosts. libcurl will only send this user +and password information to hosts using the initial host name (unless +\fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows locations to +other hosts it will not send the user and password to those. This is enforced +to prevent accidental information leakage. + +Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP +based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and +SMTP options. + +The user and password strings are not URL decoded, so there's no way to send +in a user name containing a colon using this option. Use +\fICURLOPT_USERNAME(3)\fP for that, or include it in the URL. +.SH DEFAULT +NULL +.SH PROTOCOLS +Most +.SH EXAMPLE +TODO +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK on success or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_USERNAME "(3), " CURLOPT_PASSWORD "(3), " diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.3 b/docs/libcurl/opts/CURLOPT_USE_SSL.3 new file mode 100644 index 0000000..348f1b0 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.3 @@ -0,0 +1,69 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_USE_SSL 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_USE_SSL \- request using SSL / TLS for the transfer +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USE_SSL, long level); +.SH DESCRIPTION +Pass a long using one of the values from below, to make libcurl use your +desired \fIlevel\fP of SSL for the transfer. + +These are all protocols that start out plain text and get "upgraded" to SSL +using the STARTTLS command. + +This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. +.IP CURLUSESSL_NONE +Don't attempt to use SSL. +.IP CURLUSESSL_TRY +Try using SSL, proceed as normal otherwise. +.IP CURLUSESSL_CONTROL +Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. +.IP CURLUSESSL_ALL +Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. +.SH DEFAULT +CURLUSESSL_NONE +.SH PROTOCOLS +FTP, SMTP, POP3, IMAP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext"); + + /* require use of SSL for this, or fail */ + curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_ALL); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and +the constants were known as CURLFTPSSL_* +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_SSLVERSION "(3), " CURLOPT_SSL_OPTIONS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.3 b/docs/libcurl/opts/CURLOPT_VERBOSE.3 new file mode 100644 index 0000000..732b8c4 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.3 @@ -0,0 +1,63 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_VERBOSE 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_VERBOSE \- set verbose mode on/off +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_VERBOSE, long onoff); +.SH DESCRIPTION +Set the \fIonoff\fP parameter to 1 to make the library display a lot of +verbose information about its operations on this \fIhandle\fP. Very useful for +libcurl and/or protocol debugging and understanding. The verbose information +will be sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. + +You hardly ever want this set in production use, you will almost always want +this when you debug/report problems. + +To also get all the protocol data sent and received, consider using the +\fICURLOPT_DEBUGFUNCTION(3)\fP. +.SH DEFAULT +0, meaning disabled. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* ask libcurl to show us the verbose output */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 new file mode 100644 index 0000000..b567045 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 @@ -0,0 +1,87 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_WILDCARDMATCH 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_WILDCARDMATCH \- enable directory wildcard transfers +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WILDCARDMATCH, long onoff); +.SH DESCRIPTION +Set \fIonoff\fP to 1 if you want to transfer multiple files according to a +file name pattern. The pattern can be specified as part of the +\fICURLOPT_URL(3)\fP option, using an fnmatch-like pattern (Shell Pattern +Matching) in the last part of URL (file name). + +By default, libcurl uses its internal wildcard matching implementation. You +can provide your own matching function by the +\fICURLOPT_FNMATCH_FUNCTION(3)\fP option. + +A brief introduction of its syntax follows: +.RS +.IP "* - ASTERISK" +\&ftp://example.com/some/path/\fB*.txt\fP (for all txt's from the root +directory) +.RE +.RS +.IP "? - QUESTION MARK" +Question mark matches any (exactly one) character. + +\&ftp://example.com/some/path/\fBphoto?.jpeg\fP +.RE +.RS +.IP "[ - BRACKET EXPRESSION" +The left bracket opens a bracket expression. The question mark and asterisk have +no special meaning in a bracket expression. Each bracket expression ends by the +right bracket and matches exactly one character. Some examples follow: + +\fB[a-zA-Z0\-9]\fP or \fB[f\-gF\-G]\fP \- character interval + +\fB[abc]\fP - character enumeration + +\fB[^abc]\fP or \fB[!abc]\fP - negation + +\fB[[:\fP\fIname\fP\fB:]]\fP class expression. Supported classes are +\fBalnum\fP,\fBlower\fP, \fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP, +\fBupper\fP, \fBblank\fP, \fBgraph\fP, \fBxdigit\fP. + +\fB[][-!^]\fP - special case \- matches only '\-', ']', '[', '!' or '^'. These +characters have no special purpose. + +\fB[\\[\\]\\\\]\fP - escape syntax. Matches '[', ']' or '\\'. + +Using the rules above, a file name pattern can be constructed: + +\&ftp://example.com/some/path/\fB[a-z[:upper:]\\\\].jpeg\fP +.RE +.PP +.SH PROTOCOLS +This feature is only supported for FTP download. +.SH EXAMPLE +See http://curl.haxx.se/libcurl/c/ftp-wildcard.html +.SH AVAILABILITY +Added in 7.21.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_FNMATCH_FUNCTION "(3), " CURLOPT_URL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 new file mode 100644 index 0000000..0b7a502 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 @@ -0,0 +1,60 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * 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 +.\" * 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_WRITEDATA 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_WRITEDATA \- custom pointer passed to the write callback +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEDATA, void *pointer); +.SH DESCRIPTION +A data \fIpointer\fP to pass to the write callback. If you use the +\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you'll get in that +callback's 4th argument. If you don't use a write callback, you must make +\fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass this to +\fIfwrite(3)\fP when writing data. + +The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE * +given with this option, or to stdout if this option hasn't been set. + +If you're using libcurl as a win32 DLL, you \fBMUST\fP use the +\fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience +crashes. +.SH DEFAULT +By default, this is a FILE * to stdout. +.SH PROTOCOLS +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 +\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(3)\fP was introduced in +7.9.7. +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_WRITEFUNCTION "(3), " CURLOPT_READDATA "(3), " diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 new file mode 100644 index 0000000..f5a45a3 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.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_WRITEFUNCTION 3 "16 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_WRITEFUNCTION \- set callback for writing received data +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata); + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +shown above. + +This callback function gets called by libcurl as soon as there is data +received that needs to be saved. \fIptr\fP points to the delivered data, and +the size of that data is \fIsize\fP multiplied with \fInmemb\fP. + +The callback function will be passed as much data as possible in all invokes, +but you must not make any assumptions. It may be one byte, it may be +thousands. The maximum amount of body data that will be passed to the write +callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the +usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes +header data get passed to the write callback, you can get up to +\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually +means 100K. + +This function may be called with zero bytes data if the transferred file is +empty. + +The data passed to this function will not be zero terminated! + +Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option. + +Your callback should return the number of bytes actually taken care of. If +that amount differs from the amount passed to your callback function, it'll +signal an error condition to the library. This will cause the transfer to get +aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP. + +If your callback function returns CURL_WRITEFUNC_PAUSE it will cause this +transfer to become paused. See \fIcurl_easy_pause(3)\fP for further details. + +Set this option to NULL to get the internal default function used instead of +your callback. The internal default function will write the data to the FILE * +given with \fICURLOPT_WRITEDATA(3)\fP. +.SH DEFAULT +libcurl will use 'fwrite' as a callback by default. +.SH PROTOCOLS +For all protocols +.SH AVAILABILITY +Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. +.SH RETURN VALUE +This will return CURLE_OK. +.SH EXAMPLE +A common technique is to use this callback to store the incoming data into a +dynamically growing allocated buffer. Like in the getinmemory example: +http://curl.haxx.se/libcurl/c/getinmemory.html +.SH "SEE ALSO" +.BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 new file mode 100644 index 0000000..b2c170f --- /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 0000000..cad8118 --- /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), " diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 new file mode 100644 index 0000000..2644c88 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 @@ -0,0 +1,49 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_XOAUTH2_BEARER 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_XOAUTH2_BEARER \- specify OAuth 2.0 access token +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XOAUTH2_BEARER, char *token); +.SH DESCRIPTION +Pass a char * as parameter, which should point to the zero terminated OAuth +2.0 Bearer Access Token for use with IMAP, POP3 and SMTP servers that support +the OAuth 2.0 Authorization Framework. + +Note: The user name used to generate the Bearer Token should be supplied via +the \fICURLOPT_USERNAME(3)\fP option. +.SH DEFAULT +NULL +.SH PROTOCOLS +IMAP, POP3 and SMTP +.SH EXAMPLE +TODO +.SH AVAILABILITY +Added in 7.33.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_MAIL_AUTH "(3), " CURLOPT_USERNAME "(3), " diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am new file mode 100644 index 0000000..5517811 --- /dev/null +++ b/docs/libcurl/opts/Makefile.am @@ -0,0 +1,355 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# 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 +# 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. +# +########################################################################### + +AUTOMAKE_OPTIONS = foreign no-dependencies + +man_MANS = CURLOPT_ACCEPT_ENCODING.3 CURLOPT_ACCEPTTIMEOUT_MS.3 \ + CURLOPT_ADDRESS_SCOPE.3 CURLOPT_APPEND.3 CURLOPT_AUTOREFERER.3 \ + CURLOPT_BUFFERSIZE.3 CURLOPT_CAINFO.3 CURLOPT_CAPATH.3 \ + CURLOPT_CERTINFO.3 CURLOPT_CHUNK_BGN_FUNCTION.3 CURLOPT_CHUNK_DATA.3 \ + CURLOPT_CHUNK_END_FUNCTION.3 CURLOPT_CLOSESOCKETDATA.3 \ + CURLOPT_CLOSESOCKETFUNCTION.3 CURLOPT_CONNECT_ONLY.3 \ + CURLOPT_CONNECTTIMEOUT.3 CURLOPT_CONNECTTIMEOUT_MS.3 \ + CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 CURLOPT_CONV_FROM_UTF8_FUNCTION.3 \ + CURLOPT_CONV_TO_NETWORK_FUNCTION.3 CURLOPT_COOKIE.3 \ + CURLOPT_COOKIEFILE.3 CURLOPT_COOKIEJAR.3 CURLOPT_COOKIELIST.3 \ + CURLOPT_COOKIESESSION.3 CURLOPT_COPYPOSTFIELDS.3 CURLOPT_CRLF.3 \ + CURLOPT_CRLFILE.3 CURLOPT_CUSTOMREQUEST.3 CURLOPT_DEBUGDATA.3 \ + CURLOPT_DEBUGFUNCTION.3 CURLOPT_DIRLISTONLY.3 \ + CURLOPT_DNS_CACHE_TIMEOUT.3 CURLOPT_DNS_INTERFACE.3 \ + CURLOPT_DNS_LOCAL_IP4.3 CURLOPT_DNS_LOCAL_IP6.3 CURLOPT_DNS_SERVERS.3 \ + CURLOPT_DNS_USE_GLOBAL_CACHE.3 CURLOPT_EGDSOCKET.3 \ + CURLOPT_ERRORBUFFER.3 CURLOPT_EXPECT_100_TIMEOUT_MS.3 \ + CURLOPT_FAILONERROR.3 CURLOPT_FILETIME.3 CURLOPT_FNMATCH_DATA.3 \ + CURLOPT_FNMATCH_FUNCTION.3 CURLOPT_FOLLOWLOCATION.3 \ + CURLOPT_FORBID_REUSE.3 CURLOPT_FRESH_CONNECT.3 CURLOPT_FTP_ACCOUNT.3 \ + CURLOPT_FTP_ALTERNATIVE_TO_USER.3 CURLOPT_FTP_CREATE_MISSING_DIRS.3 \ + CURLOPT_FTP_FILEMETHOD.3 CURLOPT_FTPPORT.3 \ + CURLOPT_FTP_RESPONSE_TIMEOUT.3 CURLOPT_FTP_SKIP_PASV_IP.3 \ + CURLOPT_FTPSSLAUTH.3 CURLOPT_FTP_SSL_CCC.3 CURLOPT_FTP_USE_EPRT.3 \ + CURLOPT_FTP_USE_EPSV.3 CURLOPT_FTP_USE_PRET.3 \ + CURLOPT_GSSAPI_DELEGATION.3 CURLOPT_HEADER.3 CURLOPT_HEADERDATA.3 \ + CURLOPT_HEADERFUNCTION.3 CURLOPT_HEADEROPT.3 CURLOPT_HTTP200ALIASES.3 \ + CURLOPT_HTTPAUTH.3 CURLOPT_HTTP_CONTENT_DECODING.3 CURLOPT_HTTPGET.3 \ + CURLOPT_HTTPHEADER.3 CURLOPT_HTTPPOST.3 CURLOPT_HTTPPROXYTUNNEL.3 \ + CURLOPT_HTTP_TRANSFER_DECODING.3 CURLOPT_HTTP_VERSION.3 \ + CURLOPT_IGNORE_CONTENT_LENGTH.3 CURLOPT_INFILESIZE.3 \ + CURLOPT_INFILESIZE_LARGE.3 CURLOPT_INTERFACE.3 \ + CURLOPT_INTERLEAVEDATA.3 CURLOPT_INTERLEAVEFUNCTION.3 \ + CURLOPT_IOCTLDATA.3 CURLOPT_IOCTLFUNCTION.3 CURLOPT_IPRESOLVE.3 \ + CURLOPT_ISSUERCERT.3 CURLOPT_KEYPASSWD.3 CURLOPT_KRBLEVEL.3 \ + CURLOPT_LOCALPORT.3 CURLOPT_LOCALPORTRANGE.3 CURLOPT_LOGIN_OPTIONS.3 \ + CURLOPT_LOW_SPEED_LIMIT.3 CURLOPT_LOW_SPEED_TIME.3 CURLOPT_MAIL_AUTH.3 \ + CURLOPT_MAIL_FROM.3 CURLOPT_MAIL_RCPT.3 CURLOPT_MAXCONNECTS.3 \ + CURLOPT_MAXFILESIZE.3 CURLOPT_MAXFILESIZE_LARGE.3 \ + CURLOPT_MAX_RECV_SPEED_LARGE.3 CURLOPT_MAXREDIRS.3 \ + CURLOPT_MAX_SEND_SPEED_LARGE.3 CURLOPT_NETRC.3 CURLOPT_NETRC_FILE.3 \ + CURLOPT_NEW_DIRECTORY_PERMS.3 CURLOPT_NEW_FILE_PERMS.3 \ + CURLOPT_NOBODY.3 CURLOPT_NOPROGRESS.3 CURLOPT_NOPROXY.3 \ + CURLOPT_NOSIGNAL.3 CURLOPT_OPENSOCKETDATA.3 \ + CURLOPT_OPENSOCKETFUNCTION.3 CURLOPT_PASSWORD.3 \ + CURLOPT_PINNEDPUBLICKEY.3 CURLOPT_PORT.3 CURLOPT_POST.3 \ + CURLOPT_POSTFIELDS.3 CURLOPT_POSTFIELDSIZE.3 \ + CURLOPT_POSTFIELDSIZE_LARGE.3 CURLOPT_POSTQUOTE.3 CURLOPT_POSTREDIR.3 \ + CURLOPT_PREQUOTE.3 CURLOPT_PRIVATE.3 CURLOPT_PROGRESSDATA.3 \ + CURLOPT_PROGRESSFUNCTION.3 CURLOPT_PROTOCOLS.3 CURLOPT_PROXY.3 \ + CURLOPT_PROXYAUTH.3 CURLOPT_PROXYHEADER.3 CURLOPT_PROXYPASSWORD.3 \ + CURLOPT_PROXYPORT.3 CURLOPT_PROXY_TRANSFER_MODE.3 CURLOPT_PROXYTYPE.3 \ + CURLOPT_PROXYUSERNAME.3 CURLOPT_PROXYUSERPWD.3 CURLOPT_PUT.3 \ + CURLOPT_QUOTE.3 CURLOPT_RANDOM_FILE.3 CURLOPT_RANGE.3 \ + CURLOPT_READDATA.3 CURLOPT_READFUNCTION.3 CURLOPT_REDIR_PROTOCOLS.3 \ + CURLOPT_REFERER.3 CURLOPT_RESOLVE.3 CURLOPT_RESUME_FROM.3 \ + CURLOPT_RESUME_FROM_LARGE.3 CURLOPT_RTSP_CLIENT_CSEQ.3 \ + CURLOPT_RTSP_REQUEST.3 CURLOPT_RTSP_SERVER_CSEQ.3 \ + CURLOPT_RTSP_SESSION_ID.3 CURLOPT_RTSP_STREAM_URI.3 \ + CURLOPT_RTSP_TRANSPORT.3 CURLOPT_SASL_IR.3 CURLOPT_SEEKDATA.3 \ + CURLOPT_SEEKFUNCTION.3 CURLOPT_SHARE.3 CURLOPT_SOCKOPTDATA.3 \ + CURLOPT_SOCKOPTFUNCTION.3 CURLOPT_SOCKS5_GSSAPI_NEC.3 \ + CURLOPT_SOCKS5_GSSAPI_SERVICE.3 CURLOPT_SSH_AUTH_TYPES.3 \ + CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 CURLOPT_SSH_KEYDATA.3 \ + CURLOPT_SSH_KEYFUNCTION.3 CURLOPT_SSH_KNOWNHOSTS.3 \ + CURLOPT_SSH_PRIVATE_KEYFILE.3 CURLOPT_SSH_PUBLIC_KEYFILE.3 \ + CURLOPT_SSLCERT.3 CURLOPT_SSLCERTTYPE.3 CURLOPT_SSL_CIPHER_LIST.3 \ + CURLOPT_SSL_CTX_DATA.3 CURLOPT_SSL_CTX_FUNCTION.3 \ + CURLOPT_SSL_ENABLE_ALPN.3 CURLOPT_SSL_ENABLE_NPN.3 CURLOPT_SSLENGINE.3 \ + CURLOPT_SSLENGINE_DEFAULT.3 CURLOPT_SSL_FALSESTART.3 CURLOPT_SSLKEY.3 \ + CURLOPT_SSLKEYTYPE.3 CURLOPT_SSL_OPTIONS.3 \ + CURLOPT_SSL_SESSIONID_CACHE.3 CURLOPT_SSL_VERIFYHOST.3 \ + CURLOPT_SSL_VERIFYPEER.3 CURLOPT_SSL_VERIFYSTATUS.3 \ + CURLOPT_SSLVERSION.3 CURLOPT_STDERR.3 CURLOPT_TCP_KEEPALIVE.3 \ + CURLOPT_TCP_KEEPIDLE.3 CURLOPT_TCP_KEEPINTVL.3 CURLOPT_TCP_NODELAY.3 \ + CURLOPT_TELNETOPTIONS.3 CURLOPT_TFTP_BLKSIZE.3 CURLOPT_TIMECONDITION.3 \ + CURLOPT_TIMEOUT.3 CURLOPT_TIMEOUT_MS.3 CURLOPT_TIMEVALUE.3 \ + CURLOPT_TLSAUTH_PASSWORD.3 CURLOPT_TLSAUTH_TYPE.3 \ + CURLOPT_TLSAUTH_USERNAME.3 CURLOPT_TRANSFER_ENCODING.3 \ + CURLOPT_TRANSFERTEXT.3 CURLOPT_UNRESTRICTED_AUTH.3 CURLOPT_UPLOAD.3 \ + CURLOPT_URL.3 CURLOPT_USERAGENT.3 CURLOPT_USERNAME.3 CURLOPT_USERPWD.3 \ + CURLOPT_USE_SSL.3 CURLOPT_VERBOSE.3 CURLOPT_WILDCARDMATCH.3 \ + CURLOPT_WRITEDATA.3 CURLOPT_WRITEFUNCTION.3 CURLOPT_XFERINFODATA.3 \ + CURLOPT_XFERINFOFUNCTION.3 CURLOPT_XOAUTH2_BEARER.3 \ + CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 \ + CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 CURLMOPT_MAXCONNECTS.3 \ + CURLMOPT_MAX_HOST_CONNECTIONS.3 CURLMOPT_MAX_PIPELINE_LENGTH.3 \ + CURLMOPT_MAX_TOTAL_CONNECTIONS.3 CURLMOPT_PIPELINING.3 \ + CURLMOPT_PIPELINING_SERVER_BL.3 CURLMOPT_PIPELINING_SITE_BL.3 \ + CURLMOPT_SOCKETDATA.3 CURLMOPT_SOCKETFUNCTION.3 CURLMOPT_TIMERDATA.3 \ + CURLMOPT_TIMERFUNCTION.3 CURLOPT_UNIX_SOCKET_PATH.3 \ + CURLOPT_PATH_AS_IS.3 CURLOPT_PROXY_SERVICE_NAME.3 \ + CURLOPT_SERVICE_NAME.3 CURLOPT_PIPEWAIT.3 + +HTMLPAGES = CURLOPT_ACCEPT_ENCODING.html CURLOPT_ACCEPTTIMEOUT_MS.html \ + CURLOPT_ADDRESS_SCOPE.html CURLOPT_APPEND.html \ + CURLOPT_AUTOREFERER.html CURLOPT_BUFFERSIZE.html CURLOPT_CAINFO.html \ + CURLOPT_CAPATH.html CURLOPT_CERTINFO.html \ + CURLOPT_CHUNK_BGN_FUNCTION.html CURLOPT_CHUNK_DATA.html \ + CURLOPT_CHUNK_END_FUNCTION.html CURLOPT_CLOSESOCKETDATA.html \ + CURLOPT_CLOSESOCKETFUNCTION.html CURLOPT_CONNECT_ONLY.html \ + CURLOPT_CONNECTTIMEOUT.html CURLOPT_CONNECTTIMEOUT_MS.html \ + CURLOPT_CONV_FROM_NETWORK_FUNCTION.html \ + CURLOPT_CONV_FROM_UTF8_FUNCTION.html \ + CURLOPT_CONV_TO_NETWORK_FUNCTION.html CURLOPT_COOKIE.html \ + CURLOPT_COOKIEFILE.html CURLOPT_COOKIEJAR.html CURLOPT_COOKIELIST.html \ + CURLOPT_COOKIESESSION.html CURLOPT_COPYPOSTFIELDS.html \ + CURLOPT_CRLF.html CURLOPT_CRLFILE.html CURLOPT_CUSTOMREQUEST.html \ + CURLOPT_DEBUGDATA.html CURLOPT_DEBUGFUNCTION.html \ + CURLOPT_DIRLISTONLY.html CURLOPT_DNS_CACHE_TIMEOUT.html \ + CURLOPT_DNS_INTERFACE.html CURLOPT_DNS_LOCAL_IP4.html \ + CURLOPT_DNS_LOCAL_IP6.html CURLOPT_DNS_SERVERS.html \ + CURLOPT_DNS_USE_GLOBAL_CACHE.html CURLOPT_EGDSOCKET.html \ + CURLOPT_ERRORBUFFER.html CURLOPT_EXPECT_100_TIMEOUT_MS.html \ + CURLOPT_FAILONERROR.html CURLOPT_FILETIME.html \ + CURLOPT_FNMATCH_DATA.html CURLOPT_FNMATCH_FUNCTION.html \ + CURLOPT_FOLLOWLOCATION.html CURLOPT_FORBID_REUSE.html \ + CURLOPT_FRESH_CONNECT.html CURLOPT_FTP_ACCOUNT.html \ + CURLOPT_FTP_ALTERNATIVE_TO_USER.html \ + CURLOPT_FTP_CREATE_MISSING_DIRS.html CURLOPT_FTP_FILEMETHOD.html \ + CURLOPT_FTPPORT.html CURLOPT_FTP_RESPONSE_TIMEOUT.html \ + CURLOPT_FTP_SKIP_PASV_IP.html CURLOPT_FTPSSLAUTH.html \ + CURLOPT_FTP_SSL_CCC.html CURLOPT_FTP_USE_EPRT.html \ + CURLOPT_FTP_USE_EPSV.html CURLOPT_FTP_USE_PRET.html \ + CURLOPT_GSSAPI_DELEGATION.html CURLOPT_HEADER.html \ + CURLOPT_HEADERDATA.html CURLOPT_HEADERFUNCTION.html \ + CURLOPT_HEADEROPT.html CURLOPT_HTTP200ALIASES.html \ + CURLOPT_HTTPAUTH.html CURLOPT_HTTP_CONTENT_DECODING.html \ + CURLOPT_HTTPGET.html CURLOPT_HTTPHEADER.html CURLOPT_HTTPPOST.html \ + CURLOPT_HTTPPROXYTUNNEL.html CURLOPT_HTTP_TRANSFER_DECODING.html \ + CURLOPT_HTTP_VERSION.html CURLOPT_IGNORE_CONTENT_LENGTH.html \ + CURLOPT_INFILESIZE.html CURLOPT_INFILESIZE_LARGE.html \ + CURLOPT_INTERFACE.html CURLOPT_INTERLEAVEDATA.html \ + CURLOPT_INTERLEAVEFUNCTION.html CURLOPT_IOCTLDATA.html \ + CURLOPT_IOCTLFUNCTION.html CURLOPT_IPRESOLVE.html \ + CURLOPT_ISSUERCERT.html CURLOPT_KEYPASSWD.html CURLOPT_KRBLEVEL.html \ + CURLOPT_LOCALPORT.html CURLOPT_LOCALPORTRANGE.html \ + CURLOPT_LOGIN_OPTIONS.html CURLOPT_LOW_SPEED_LIMIT.html \ + CURLOPT_LOW_SPEED_TIME.html CURLOPT_MAIL_AUTH.html \ + CURLOPT_MAIL_FROM.html CURLOPT_MAIL_RCPT.html CURLOPT_MAXCONNECTS.html \ + CURLOPT_MAXFILESIZE.html CURLOPT_MAXFILESIZE_LARGE.html \ + CURLOPT_MAX_RECV_SPEED_LARGE.html CURLOPT_MAXREDIRS.html \ + CURLOPT_MAX_SEND_SPEED_LARGE.html CURLOPT_NETRC.html \ + CURLOPT_NETRC_FILE.html CURLOPT_NEW_DIRECTORY_PERMS.html \ + CURLOPT_NEW_FILE_PERMS.html CURLOPT_NOBODY.html \ + CURLOPT_NOPROGRESS.html CURLOPT_NOPROXY.html CURLOPT_NOSIGNAL.html \ + CURLOPT_OPENSOCKETDATA.html CURLOPT_OPENSOCKETFUNCTION.html \ + CURLOPT_PASSWORD.html CURLOPT_PINNEDPUBLICKEY.html CURLOPT_PORT.html \ + CURLOPT_POST.html CURLOPT_POSTFIELDS.html CURLOPT_POSTFIELDSIZE.html \ + CURLOPT_POSTFIELDSIZE_LARGE.html CURLOPT_POSTQUOTE.html \ + CURLOPT_POSTREDIR.html CURLOPT_PREQUOTE.html CURLOPT_PRIVATE.html \ + CURLOPT_PROGRESSDATA.html CURLOPT_PROGRESSFUNCTION.html \ + CURLOPT_PROTOCOLS.html CURLOPT_PROXY.html CURLOPT_PROXYAUTH.html \ + CURLOPT_PROXYHEADER.html CURLOPT_PROXYPASSWORD.html \ + CURLOPT_PROXYPORT.html CURLOPT_PROXY_TRANSFER_MODE.html \ + CURLOPT_PROXYTYPE.html CURLOPT_PROXYUSERNAME.html \ + CURLOPT_PROXYUSERPWD.html CURLOPT_PUT.html CURLOPT_QUOTE.html \ + CURLOPT_RANDOM_FILE.html CURLOPT_RANGE.html CURLOPT_READDATA.html \ + CURLOPT_READFUNCTION.html CURLOPT_REDIR_PROTOCOLS.html \ + CURLOPT_REFERER.html CURLOPT_RESOLVE.html CURLOPT_RESUME_FROM.html \ + CURLOPT_RESUME_FROM_LARGE.html CURLOPT_RTSP_CLIENT_CSEQ.html \ + CURLOPT_RTSP_REQUEST.html CURLOPT_RTSP_SERVER_CSEQ.html \ + CURLOPT_RTSP_SESSION_ID.html CURLOPT_RTSP_STREAM_URI.html \ + CURLOPT_RTSP_TRANSPORT.html CURLOPT_SASL_IR.html CURLOPT_SEEKDATA.html \ + CURLOPT_SEEKFUNCTION.html CURLOPT_SHARE.html CURLOPT_SOCKOPTDATA.html \ + CURLOPT_SOCKOPTFUNCTION.html CURLOPT_SOCKS5_GSSAPI_NEC.html \ + CURLOPT_SOCKS5_GSSAPI_SERVICE.html CURLOPT_SSH_AUTH_TYPES.html \ + CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.html CURLOPT_SSH_KEYDATA.html \ + CURLOPT_SSH_KEYFUNCTION.html CURLOPT_SSH_KNOWNHOSTS.html \ + CURLOPT_SSH_PRIVATE_KEYFILE.html CURLOPT_SSH_PUBLIC_KEYFILE.html \ + CURLOPT_SSLCERT.html CURLOPT_SSLCERTTYPE.html \ + CURLOPT_SSL_CIPHER_LIST.html CURLOPT_SSL_CTX_DATA.html \ + CURLOPT_SSL_CTX_FUNCTION.html CURLOPT_SSL_ENABLE_ALPN.html \ + CURLOPT_SSL_ENABLE_NPN.html CURLOPT_SSLENGINE.html \ + CURLOPT_SSLENGINE_DEFAULT.html CURLOPT_SSL_FALSESTART.html \ + CURLOPT_SSLKEY.html CURLOPT_SSLKEYTYPE.html CURLOPT_SSL_OPTIONS.html \ + CURLOPT_SSL_SESSIONID_CACHE.html CURLOPT_SSL_VERIFYHOST.html \ + CURLOPT_SSL_VERIFYPEER.html CURLOPT_SSL_VERIFYSTATUS.html \ + CURLOPT_SSLVERSION.html CURLOPT_STDERR.html CURLOPT_TCP_KEEPALIVE.html \ + CURLOPT_TCP_KEEPIDLE.html CURLOPT_TCP_KEEPINTVL.html \ + CURLOPT_TCP_NODELAY.html CURLOPT_TELNETOPTIONS.html \ + CURLOPT_TFTP_BLKSIZE.html CURLOPT_TIMECONDITION.html \ + CURLOPT_TIMEOUT.html CURLOPT_TIMEOUT_MS.html CURLOPT_TIMEVALUE.html \ + CURLOPT_TLSAUTH_PASSWORD.html CURLOPT_TLSAUTH_TYPE.html \ + CURLOPT_TLSAUTH_USERNAME.html CURLOPT_TRANSFER_ENCODING.html \ + CURLOPT_TRANSFERTEXT.html CURLOPT_UNRESTRICTED_AUTH.html \ + CURLOPT_UPLOAD.html CURLOPT_URL.html CURLOPT_USERAGENT.html \ + CURLOPT_USERNAME.html CURLOPT_USERPWD.html CURLOPT_USE_SSL.html \ + CURLOPT_VERBOSE.html CURLOPT_WILDCARDMATCH.html CURLOPT_WRITEDATA.html \ + CURLOPT_WRITEFUNCTION.html CURLOPT_XFERINFODATA.html \ + CURLOPT_XFERINFOFUNCTION.html CURLOPT_XOAUTH2_BEARER.html \ + CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.html \ + CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.html CURLMOPT_MAXCONNECTS.html \ + CURLMOPT_MAX_HOST_CONNECTIONS.html CURLMOPT_MAX_PIPELINE_LENGTH.html \ + CURLMOPT_MAX_TOTAL_CONNECTIONS.html CURLMOPT_PIPELINING.html \ + CURLMOPT_PIPELINING_SERVER_BL.html CURLMOPT_PIPELINING_SITE_BL.html \ + CURLMOPT_SOCKETDATA.html CURLMOPT_SOCKETFUNCTION.html \ + CURLMOPT_TIMERDATA.html CURLMOPT_TIMERFUNCTION.html \ + CURLOPT_UNIX_SOCKET_PATH.html CURLOPT_PATH_AS_IS.html \ + CURLOPT_PROXY_SERVICE_NAME.html CURLOPT_SERVICE_NAME.html \ + CURLOPT_PIPEWAIT.html + +PDFPAGES = CURLOPT_ACCEPT_ENCODING.pdf CURLOPT_ACCEPTTIMEOUT_MS.pdf \ + CURLOPT_ADDRESS_SCOPE.pdf CURLOPT_APPEND.pdf CURLOPT_AUTOREFERER.pdf \ + CURLOPT_BUFFERSIZE.pdf CURLOPT_CAINFO.pdf CURLOPT_CAPATH.pdf \ + CURLOPT_CERTINFO.pdf CURLOPT_CHUNK_BGN_FUNCTION.pdf \ + CURLOPT_CHUNK_DATA.pdf CURLOPT_CHUNK_END_FUNCTION.pdf \ + CURLOPT_CLOSESOCKETDATA.pdf CURLOPT_CLOSESOCKETFUNCTION.pdf \ + CURLOPT_CONNECT_ONLY.pdf CURLOPT_CONNECTTIMEOUT.pdf \ + CURLOPT_CONNECTTIMEOUT_MS.pdf CURLOPT_CONV_FROM_NETWORK_FUNCTION.pdf \ + CURLOPT_CONV_FROM_UTF8_FUNCTION.pdf \ + CURLOPT_CONV_TO_NETWORK_FUNCTION.pdf CURLOPT_COOKIE.pdf \ + CURLOPT_COOKIEFILE.pdf CURLOPT_COOKIEJAR.pdf CURLOPT_COOKIELIST.pdf \ + CURLOPT_COOKIESESSION.pdf CURLOPT_COPYPOSTFIELDS.pdf CURLOPT_CRLF.pdf \ + CURLOPT_CRLFILE.pdf CURLOPT_CUSTOMREQUEST.pdf CURLOPT_DEBUGDATA.pdf \ + CURLOPT_DEBUGFUNCTION.pdf CURLOPT_DIRLISTONLY.pdf \ + CURLOPT_DNS_CACHE_TIMEOUT.pdf CURLOPT_DNS_INTERFACE.pdf \ + CURLOPT_DNS_LOCAL_IP4.pdf CURLOPT_DNS_LOCAL_IP6.pdf \ + CURLOPT_DNS_SERVERS.pdf CURLOPT_DNS_USE_GLOBAL_CACHE.pdf \ + CURLOPT_EGDSOCKET.pdf CURLOPT_ERRORBUFFER.pdf \ + CURLOPT_EXPECT_100_TIMEOUT_MS.pdf CURLOPT_FAILONERROR.pdf \ + CURLOPT_FILETIME.pdf CURLOPT_FNMATCH_DATA.pdf \ + CURLOPT_FNMATCH_FUNCTION.pdf CURLOPT_FOLLOWLOCATION.pdf \ + CURLOPT_FORBID_REUSE.pdf CURLOPT_FRESH_CONNECT.pdf \ + CURLOPT_FTP_ACCOUNT.pdf CURLOPT_FTP_ALTERNATIVE_TO_USER.pdf \ + CURLOPT_FTP_CREATE_MISSING_DIRS.pdf CURLOPT_FTP_FILEMETHOD.pdf \ + CURLOPT_FTPPORT.pdf CURLOPT_FTP_RESPONSE_TIMEOUT.pdf \ + CURLOPT_FTP_SKIP_PASV_IP.pdf CURLOPT_FTPSSLAUTH.pdf \ + CURLOPT_FTP_SSL_CCC.pdf CURLOPT_FTP_USE_EPRT.pdf \ + CURLOPT_FTP_USE_EPSV.pdf CURLOPT_FTP_USE_PRET.pdf \ + CURLOPT_GSSAPI_DELEGATION.pdf CURLOPT_HEADER.pdf \ + CURLOPT_HEADERDATA.pdf CURLOPT_HEADERFUNCTION.pdf \ + CURLOPT_HEADEROPT.pdf CURLOPT_HTTP200ALIASES.pdf CURLOPT_HTTPAUTH.pdf \ + CURLOPT_HTTP_CONTENT_DECODING.pdf CURLOPT_HTTPGET.pdf \ + CURLOPT_HTTPHEADER.pdf CURLOPT_HTTPPOST.pdf \ + CURLOPT_HTTPPROXYTUNNEL.pdf CURLOPT_HTTP_TRANSFER_DECODING.pdf \ + CURLOPT_HTTP_VERSION.pdf CURLOPT_IGNORE_CONTENT_LENGTH.pdf \ + CURLOPT_INFILESIZE.pdf CURLOPT_INFILESIZE_LARGE.pdf \ + CURLOPT_INTERFACE.pdf CURLOPT_INTERLEAVEDATA.pdf \ + CURLOPT_INTERLEAVEFUNCTION.pdf CURLOPT_IOCTLDATA.pdf \ + CURLOPT_IOCTLFUNCTION.pdf CURLOPT_IPRESOLVE.pdf CURLOPT_ISSUERCERT.pdf \ + CURLOPT_KEYPASSWD.pdf CURLOPT_KRBLEVEL.pdf CURLOPT_LOCALPORT.pdf \ + CURLOPT_LOCALPORTRANGE.pdf CURLOPT_LOGIN_OPTIONS.pdf \ + CURLOPT_LOW_SPEED_LIMIT.pdf CURLOPT_LOW_SPEED_TIME.pdf \ + CURLOPT_MAIL_AUTH.pdf CURLOPT_MAIL_FROM.pdf CURLOPT_MAIL_RCPT.pdf \ + CURLOPT_MAXCONNECTS.pdf CURLOPT_MAXFILESIZE.pdf \ + CURLOPT_MAXFILESIZE_LARGE.pdf CURLOPT_MAX_RECV_SPEED_LARGE.pdf \ + CURLOPT_MAXREDIRS.pdf CURLOPT_MAX_SEND_SPEED_LARGE.pdf \ + CURLOPT_NETRC.pdf CURLOPT_NETRC_FILE.pdf \ + CURLOPT_NEW_DIRECTORY_PERMS.pdf CURLOPT_NEW_FILE_PERMS.pdf \ + CURLOPT_NOBODY.pdf CURLOPT_NOPROGRESS.pdf CURLOPT_NOPROXY.pdf \ + CURLOPT_NOSIGNAL.pdf CURLOPT_OPENSOCKETDATA.pdf \ + CURLOPT_OPENSOCKETFUNCTION.pdf CURLOPT_PASSWORD.pdf \ + CURLOPT_PINNEDPUBLICKEY.pdf CURLOPT_PORT.pdf CURLOPT_POST.pdf \ + CURLOPT_POSTFIELDS.pdf CURLOPT_POSTFIELDSIZE.pdf \ + CURLOPT_POSTFIELDSIZE_LARGE.pdf CURLOPT_POSTQUOTE.pdf \ + CURLOPT_POSTREDIR.pdf CURLOPT_PREQUOTE.pdf CURLOPT_PRIVATE.pdf \ + CURLOPT_PROGRESSDATA.pdf CURLOPT_PROGRESSFUNCTION.pdf \ + CURLOPT_PROTOCOLS.pdf CURLOPT_PROXY.pdf CURLOPT_PROXYAUTH.pdf \ + CURLOPT_PROXYHEADER.pdf CURLOPT_PROXYPASSWORD.pdf \ + CURLOPT_PROXYPORT.pdf CURLOPT_PROXY_TRANSFER_MODE.pdf \ + CURLOPT_PROXYTYPE.pdf CURLOPT_PROXYUSERNAME.pdf \ + CURLOPT_PROXYUSERPWD.pdf CURLOPT_PUT.pdf CURLOPT_QUOTE.pdf \ + CURLOPT_RANDOM_FILE.pdf CURLOPT_RANGE.pdf CURLOPT_READDATA.pdf \ + CURLOPT_READFUNCTION.pdf CURLOPT_REDIR_PROTOCOLS.pdf \ + CURLOPT_REFERER.pdf CURLOPT_RESOLVE.pdf CURLOPT_RESUME_FROM.pdf \ + CURLOPT_RESUME_FROM_LARGE.pdf CURLOPT_RTSP_CLIENT_CSEQ.pdf \ + CURLOPT_RTSP_REQUEST.pdf CURLOPT_RTSP_SERVER_CSEQ.pdf \ + CURLOPT_RTSP_SESSION_ID.pdf CURLOPT_RTSP_STREAM_URI.pdf \ + CURLOPT_RTSP_TRANSPORT.pdf CURLOPT_SASL_IR.pdf CURLOPT_SEEKDATA.pdf \ + CURLOPT_SEEKFUNCTION.pdf CURLOPT_SHARE.pdf CURLOPT_SOCKOPTDATA.pdf \ + CURLOPT_SOCKOPTFUNCTION.pdf CURLOPT_SOCKS5_GSSAPI_NEC.pdf \ + CURLOPT_SOCKS5_GSSAPI_SERVICE.pdf CURLOPT_SSH_AUTH_TYPES.pdf \ + CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.pdf CURLOPT_SSH_KEYDATA.pdf \ + CURLOPT_SSH_KEYFUNCTION.pdf CURLOPT_SSH_KNOWNHOSTS.pdf \ + CURLOPT_SSH_PRIVATE_KEYFILE.pdf CURLOPT_SSH_PUBLIC_KEYFILE.pdf \ + CURLOPT_SSLCERT.pdf CURLOPT_SSLCERTTYPE.pdf \ + CURLOPT_SSL_CIPHER_LIST.pdf CURLOPT_SSL_CTX_DATA.pdf \ + CURLOPT_SSL_CTX_FUNCTION.pdf CURLOPT_SSL_ENABLE_ALPN.pdf \ + CURLOPT_SSL_ENABLE_NPN.pdf CURLOPT_SSLENGINE.pdf \ + CURLOPT_SSLENGINE_DEFAULT.pdf CURLOPT_SSL_FALSESTART.pdf \ + CURLOPT_SSLKEY.pdf CURLOPT_SSLKEYTYPE.pdf CURLOPT_SSL_OPTIONS.pdf \ + CURLOPT_SSL_SESSIONID_CACHE.pdf CURLOPT_SSL_VERIFYHOST.pdf \ + CURLOPT_SSL_VERIFYPEER.pdf CURLOPT_SSL_VERIFYSTATUS.pdf \ + CURLOPT_SSLVERSION.pdf CURLOPT_STDERR.pdf CURLOPT_TCP_KEEPALIVE.pdf \ + CURLOPT_TCP_KEEPIDLE.pdf CURLOPT_TCP_KEEPINTVL.pdf \ + CURLOPT_TCP_NODELAY.pdf CURLOPT_TELNETOPTIONS.pdf \ + CURLOPT_TFTP_BLKSIZE.pdf CURLOPT_TIMECONDITION.pdf CURLOPT_TIMEOUT.pdf \ + CURLOPT_TIMEOUT_MS.pdf CURLOPT_TIMEVALUE.pdf \ + CURLOPT_TLSAUTH_PASSWORD.pdf CURLOPT_TLSAUTH_TYPE.pdf \ + CURLOPT_TLSAUTH_USERNAME.pdf CURLOPT_TRANSFER_ENCODING.pdf \ + CURLOPT_TRANSFERTEXT.pdf CURLOPT_UNRESTRICTED_AUTH.pdf \ + CURLOPT_UPLOAD.pdf CURLOPT_URL.pdf CURLOPT_USERAGENT.pdf \ + CURLOPT_USERNAME.pdf CURLOPT_USERPWD.pdf CURLOPT_USE_SSL.pdf \ + CURLOPT_VERBOSE.pdf CURLOPT_WILDCARDMATCH.pdf CURLOPT_WRITEDATA.pdf \ + CURLOPT_WRITEFUNCTION.pdf CURLOPT_XFERINFODATA.pdf \ + CURLOPT_XFERINFOFUNCTION.pdf CURLOPT_XOAUTH2_BEARER.pdf \ + CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.pdf \ + CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.pdf CURLMOPT_MAXCONNECTS.pdf \ + CURLMOPT_MAX_HOST_CONNECTIONS.pdf CURLMOPT_MAX_PIPELINE_LENGTH.pdf \ + CURLMOPT_MAX_TOTAL_CONNECTIONS.pdf CURLMOPT_PIPELINING.pdf \ + CURLMOPT_PIPELINING_SERVER_BL.pdf CURLMOPT_PIPELINING_SITE_BL.pdf \ + CURLMOPT_SOCKETDATA.pdf CURLMOPT_SOCKETFUNCTION.pdf \ + CURLMOPT_TIMERDATA.pdf CURLMOPT_TIMERFUNCTION.pdf \ + CURLOPT_UNIX_SOCKET_PATH.pdf CURLOPT_PATH_AS_IS.pdf \ + CURLOPT_PROXY_SERVICE_NAME.pdf CURLOPT_SERVICE_NAME.pdf \ + CURLOPT_PIPEWAIT.pdf + +CLEANFILES = $(HTMLPAGES) $(PDFPAGES) + +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) $(PDFPAGES) +MAN2HTML= roffit --mandir=. < $< >$@ + +SUFFIXES = .3 .html + +html: $(HTMLPAGES) + +.3.html: + $(MAN2HTML) + +pdf: $(PDFPAGES) + +.3.pdf: + @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ + groff -Tps -man $< >$$foo.ps; \ + ps2pdf $$foo.ps $@; \ + rm $$foo.ps; \ + echo "converted $< to $@") + +mancheck: + @cd $(top_srcdir)/docs/libcurl/opts && ls `awk -F, '!/OBSOLETE/ && /^ CINIT/ { a=substr($$1, 9); print "CURLOPT_" a ".3"}' $(top_srcdir)/include/curl/curl.h` diff --git a/docs/libcurl/opts/template.3 b/docs/libcurl/opts/template.3 new file mode 100644 index 0000000..184e471 --- /dev/null +++ b/docs/libcurl/opts/template.3 @@ -0,0 +1,38 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * 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_TEMPLATE 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_TEMPLATE \- [short desc] +.SH SYNOPSIS +#include <curl/curl.h> + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TEMPLATE, [argument]); +.SH DESCRIPTION +.SH DEFAULT +.SH PROTOCOLS +.SH EXAMPLE +.SH AVAILABILITY +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " |