opts: 4 more options with stand-alone man pages

.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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), "

.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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), "

.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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_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 doing a HTTP PUT

or POST with a multi-pass authentication method. 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), "

.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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 so additional setsockopt() calls can

be done at the user's discretion.  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

CURLE_OK

.SH "SEE ALSO"

.BR CURLOPT_SOCKOPTDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "