Artifactspublic-v0

curl

master
ply4 git calls192 ms289 KiB2 cachedprotocol v2
141 lines4.1 KiBRaw

NAME

CURLOPT_OPENSOCKETFUNCTION - callback for opening socket

SYNOPSIS

c
#include <curl/curl.h>

typedef enum {
  CURLSOCKTYPE_IPCXN,  /* socket created for a specific IP connection */
} 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);

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 socket(2) call. The callback's purpose argument identifies the exact purpose for this particular socket. CURLSOCKTYPE_IPCXN is for IP based connections and is the only purpose currently used in libcurl. Future versions of libcurl may support more purposes.

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

The callback gets the resolved peer address as the address argument and is allowed to modify the address or refuse to connect completely. The callback function should return the newly created socket or CURL_SOCKET_BAD in case no connection could be established or another error was detected. Any additional setsockopt(2) calls can of course be done on the socket at the user's discretion.

If CURL_SOCKET_BAD is returned by the callback then libcurl treats it as a failed connection and tries to open a socket to connect to a different IP address associated with the transfer. If there are no more addresses to try then libcurl fails the transfer with error code CURLE_COULDNT_CONNECT.

You can get the IP address that curl is opening the socket for by casting address->addr to sockaddr_in if address->family is AF_INET, or to sockaddr_in6 if address->family is AF_INET6. For an example of how that data can be compared against refer to docs/examples/block_ip.c.

If you want to pass in a socket with an already established connection, pass the socket back with this callback and then use CURLOPT_SOCKOPTFUNCTION(3) to signal that it already is connected.

DEFAULT

The equivalent of this:

c
  return socket(addr->family, addr->socktype, addr->protocol);

%PROTOCOLS%

EXAMPLE

c
/* 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)
{
  return CURL_SOCKOPT_ALREADY_CONNECTED;
}

extern int sockfd; /* the already connected one */

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    /* libcurl thinks 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);

    result = curl_easy_perform(curl);

    curl_easy_cleanup(curl);
  }
}

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_OPENSOCKETFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_CLOSESOCKETFUNCTION (3)
9 - CURLOPT_OPENSOCKETFUNCTION (3)
10 - CURLOPT_SOCKOPTFUNCTION (3)
11Protocol:
12 - All
13Added-in: 7.17.1
14---
16# NAME
18CURLOPT_OPENSOCKETFUNCTION - callback for opening socket
20# SYNOPSIS
22~~~c
23#include <curl/curl.h>
25typedef enum {
26 CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
27} curlsocktype;
29struct curl_sockaddr {
30 int family;
31 int socktype;
32 int protocol;
33 unsigned int addrlen;
34 struct sockaddr addr;
35};
37curl_socket_t opensocket_callback(void *clientp,
38 curlsocktype purpose,
39 struct curl_sockaddr *address);
41CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback);
42~~~
44# DESCRIPTION
46Pass a pointer to your callback function, which should match the prototype
47shown above.
49This callback function gets called by libcurl instead of the *socket(2)*
50call. The callback's *purpose* argument identifies the exact purpose for
51this particular socket. *CURLSOCKTYPE_IPCXN* is for IP based connections
52and is the only purpose currently used in libcurl. Future versions of libcurl
53may support more purposes.
55The *clientp* pointer contains whatever user-defined value set using the
56CURLOPT_OPENSOCKETDATA(3) function.
58The callback gets the resolved peer address as the *address* argument and
59is allowed to modify the address or refuse to connect completely. The callback
60function should return the newly created socket or *CURL_SOCKET_BAD* in
61case no connection could be established or another error was detected. Any
62additional *setsockopt(2)* calls can of course be done on the socket at
63the user's discretion.
65If *CURL_SOCKET_BAD* is returned by the callback then libcurl treats it as a
66failed connection and tries to open a socket to connect to a different IP
67address associated with the transfer. If there are no more addresses to try
68then libcurl fails the transfer with error code *CURLE_COULDNT_CONNECT*.
70You can get the IP address that curl is opening the socket for by casting
71*address-\>addr* to `sockaddr_in` if *address-\>family* is `AF_INET`, or to
72`sockaddr_in6` if *address-\>family* is `AF_INET6`. For an example of how that
73data can be compared against refer to *docs/examples/block_ip.c*.
75If you want to pass in a socket with an already established connection, pass
76the socket back with this callback and then use CURLOPT_SOCKOPTFUNCTION(3) to
77signal that it already is connected.
79# DEFAULT
81The equivalent of this:
82~~~c
83 return socket(addr->family, addr->socktype, addr->protocol);
84~~~
86# %PROTOCOLS%
88# EXAMPLE
90~~~c
91/* make libcurl use the already established socket 'sockfd' */
93static curl_socket_t opensocket(void *clientp,
94 curlsocktype purpose,
95 struct curl_sockaddr *address)
97 curl_socket_t sockfd;
98 sockfd = *(curl_socket_t *)clientp;
99 /* the actual externally set socket is passed in via the OPENSOCKETDATA
100 option */
101 return sockfd;
104static int sockopt_callback(void *clientp, curl_socket_t curlfd,
105 curlsocktype purpose)
107 return CURL_SOCKOPT_ALREADY_CONNECTED;
110extern int sockfd; /* the already connected one */
112int main(void)
114 CURL *curl = curl_easy_init();
115 if(curl) {
116 CURLcode result;
117 /* libcurl thinks that you connect to the host
118 * and port that you specify in the URL option. */
119 curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
120 /* call this function to get a socket */
121 curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
122 curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
124 /* call this function to set options for the socket */
125 curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
127 result = curl_easy_perform(curl);
129 curl_easy_cleanup(curl);
130 }
132~~~
134# %AVAILABILITY%
136# RETURN VALUE
138curl_easy_setopt(3) returns a CURLcode indicating success or error.
140CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
141libcurl-errors(3).
Diagnostics4 git calls · 192 ms
CallStatusSizeTime0192 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit2 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=2
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=187
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2001.8 KiB187 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1892
git.response.cache=MISS
git.response.duration_ms=187
git.fetch.wants=4978d65f987f37479c8e3977b64a5edd52b18c87
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1892
git.pkt.payload.max=1871
git.sideband.band1.bytes=1870
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e373b6eefb22ce
Request
33488150…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format