Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_SOCKOPTFUNCTION(3) curl_easy_setopt options CURLOPT_SOCKOPTFUNCTION(3)

NAME
       CURLOPT_SOCKOPTFUNCTION - set callback for setting socket options

SYNOPSIS
       #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);

DESCRIPTION
       Pass a pointer to your callback function, which should match the	proto-
       type 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 purpose argument identi-
       fies the	exact purpose for this particular socket:

       CURLSOCKTYPE_IPCXN  for	actively  created  connections or since	7.28.0
       CURLSOCKTYPE_ACCEPT  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 curlfd pa-
       rameter so additional setsockopt() calls	can be done at the user's dis-
       cretion.

       The  clientp pointer contains whatever user-defined value set using the
       CURLOPT_SOCKOPTDATA(3) function.

       Return CURL_SOCKOPT_OK from the callback	on success. Return  CURL_SOCK-
       OPT_ERROR  from	the callback function to signal	an unrecoverable error
       to  the	library	 and   it   will   close   the	 socket	  and	return
       CURLE_COULDNT_CONNECT.  Alternatively, the callback function can	return
       CURL_SOCKOPT_ALREADY_CONNECTED, to tell libcurl that the	socket is  al-
       ready  connected	 and then libcurl will not attempt to connect it. This
       allows an application to	pass in	an already connected socket with  CUR-
       LOPT_OPENSOCKETFUNCTION(3) and then have	this function make libcurl not
       attempt to connect (again).

DEFAULT
       By default, this	callback is NULL and unused.

PROTOCOLS
       All

EXAMPLE
       /* make libcurl use the already established socket 'sockfd' */

       static curl_socket_t opensocket(void *clientp,
				       curlsocktype purpose,
				       struct curl_sockaddr *address)
       {
	 curl_socket_t sockfd;
	 sockfd	= *(curl_socket_t *)clientp;
	 /* the	actual externally set socket is	passed in via the OPENSOCKETDATA
	    option */
	 return	sockfd;
       }

       static int sockopt_callback(void	*clientp, curl_socket_t	curlfd,
				   curlsocktype	purpose)
       {
	 /* This return	code was added in libcurl 7.21.5 */
	 return	CURL_SOCKOPT_ALREADY_CONNECTED;
       }

       curl = curl_easy_init();
       if(curl)	{
	 /* libcurl will internally think that you connect to the host
	  * and	port that you specify in the URL option. */
	 curl_easy_setopt(curl,	CURLOPT_URL, "http://99.99.99.99:9999");
	 /* call this function to get a	socket */
	 curl_easy_setopt(curl,	CURLOPT_OPENSOCKETFUNCTION, opensocket);
	 curl_easy_setopt(curl,	CURLOPT_OPENSOCKETDATA,	&sockfd);

	 /* call this function to set options for the socket */
	 curl_easy_setopt(curl,	CURLOPT_SOCKOPTFUNCTION, sockopt_callback);

	 res = curl_easy_perform(curl);

	 curl_easy_cleanup(curl);

AVAILABILITY
       Added in	7.16.0.	The  CURL_SOCKOPT_ALREADY_CONNECTED  return  code  was
       added in	7.21.5.

RETURN VALUE
       Returns	CURLE_OK  if the option	is supported, and CURLE_UNKNOWN_OPTION
       if not.

SEE ALSO
       CURLOPT_SOCKOPTDATA(3), CURLOPT_OPENSOCKETFUNCTION(3),

libcurl	7.54.1			 May 15, 2017	    CURLOPT_SOCKOPTFUNCTION(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CURLOPT_SOCKOPTFUNCTION&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help