curl/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3
Emanuele Torre 73b9d7eb0f
docs/libcurl: minor cleanups
I was reading curl_unescape(3) and I noticed that there was an extra
space after the open parenthesis in the SYNOPSIS; I removed the extra
space.

I also ran a few  grep -r  commands to find and remove extra spaces
after '(' in other files, and to find and replace uses of `T*' instead
of `T *'. Some of the instances of `T*` where unnecessary casts that I
removed.

I also fixed a comment that was misaligned in CURLMOPT_SOCKETFUNCTION.3.

And I fixed some formatting inconsistencies: in curl_unescape(3), all
function parameter were mentioned with bold text except length, that was
mentioned as 'length'; and, in curl_easy_unescape(3), all parameters
were mentioned in bold text except url that was italicised. Now they are
all mentioned in bold.
Documentation is not very consistent in how function parameter are
formatted: many pages italicise them, and others display them in bold
text; but I think it makes sense to at least be consistent with
formatting within the same page.

Closes #11027
2023-04-26 10:19:48 +02:00

122 lines
4.3 KiB
Groff

.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 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 https://curl.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.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLMOPT_SOCKETFUNCTION 3 "3 Nov 2016" libcurl libcurl
.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, /* describes the socket */
void *clientp, /* 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 is called, it uses this
callback to inform the application about updates in the socket (file
descriptor) status by doing none, one, or multiple calls to the
\fBsocket_callback\fP. The callback function gets status updates with changes
since the previous time the callback was called. If the given callback pointer
is set to NULL, no callback will be called.
libcurl then expects the application to monitor the sockets for the specific
activities and tell libcurl again when something happens on one of them. Tell
libcurl by calling \fIcurl_multi_socket_action(3)\fP.
.SH "CALLBACK ARGUMENTS"
\fIeasy\fP identifies the specific transfer for which this update is related.
\fIs\fP is the specific socket this function invocation concerns. If the
\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about
what activity on this socket the application is supposed to
monitor. Subsequent calls to this callback might update the \fBwhat\fP bits
for a socket that is already monitored.
The socket callback should return 0 on success, and -1 on error. If this
callback returns error, \fBall\fP transfers currently in progress in this
multi handle will be aborted and fail.
\fBclientp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP.
\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL.
The \fBwhat\fP parameter informs the callback on the status of the given
socket. It can hold one of these values:
.IP CURL_POLL_IN
Wait for incoming data. For the socket to become readable.
.IP CURL_POLL_OUT
Wait for outgoing data. For the socket to become writable.
.IP CURL_POLL_INOUT
Wait for incoming and outgoing data. For the socket to become readable or
writable.
.IP CURL_POLL_REMOVE
The specified socket/file descriptor is no longer used by libcurl for any
active transfer. It might soon be added again.
.SH DEFAULT
NULL (no callback)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp)
{
GlobalInfo *g = cbp;
SockInfo *fdp = sockp;
if(what == CURL_POLL_REMOVE) {
remsock(fdp);
}
else {
if(!fdp) {
addsock(s, e, what, g);
}
else {
setsock(fdp, s, e, what, g);
}
}
return 0;
}
main()
{
GlobalInfo setup;
/* ... use socket callback and custom pointer */
curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup);
}
.fi
.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) "