xref: /curl/docs/libcurl/curl_multi_assign.md (revision 5a488251) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_multi_assign
5Section: 3
6Source: libcurl
7See-also:
8  - curl_multi_setopt (3)
9  - curl_multi_socket_action (3)
10Protocol:
11  - All
12Added-in: 7.15.5
13---
14
15# NAME
16
17curl_multi_assign - set data to associate with an internal socket
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd,
25                            void *sockptr);
26~~~
27
28# DESCRIPTION
29
30This function creates an association in the multi handle between the given
31socket and a private pointer of the application. This is designed for
32curl_multi_socket_action(3) uses.
33
34When set, the *sockptr* pointer is passed to all future socket callbacks
35for the specific *sockfd* socket.
36
37If the given *sockfd* is not already in use by libcurl, this function
38returns an error.
39
40libcurl only keeps one single pointer associated with a socket, so calling
41this function several times for the same socket makes the last set pointer get
42used.
43
44The idea here being that this association (socket to private pointer) is
45something that just about every application that uses this API needs and then
46libcurl can just as well do it since it already has the necessary
47functionality.
48
49It is acceptable to call this function from your multi callback functions.
50
51# %PROTOCOLS%
52
53# EXAMPLE
54
55~~~c
56int main(void)
57{
58  CURLM *multi = curl_multi_init();
59  void *ourstructp; /* pointer to our data */
60  curl_socket_t fd; /* file descriptor to associate our data with */
61
62  /* make our struct pointer associated with socket fd */
63  CURLMcode mc = curl_multi_assign(multi, fd, ourstructp);
64  if(mc)
65    printf("error: %s\n", curl_multi_strerror(mc));
66}
67~~~
68
69# TYPICAL USAGE
70
71In a typical application you allocate a struct or at least use some kind of
72semi-dynamic data for each socket that we must wait for action on when using
73the curl_multi_socket_action(3) approach.
74
75When our socket-callback gets called by libcurl and we get to know about yet
76another socket to wait for, we can use curl_multi_assign(3) to point out the
77particular data so that when we get updates about this same socket again, we
78do not have to find the struct associated with this socket by ourselves.
79
80# %AVAILABILITY%
81
82# RETURN VALUE
83
84The standard CURLMcode for multi interface error codes.
85