1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_IOCTLFUNCTION 5Section: 3 6Source: libcurl 7Protocol: 8 - All 9See-also: 10 - CURLOPT_IOCTLDATA (3) 11 - CURLOPT_SEEKFUNCTION (3) 12--- 13 14# NAME 15 16CURLOPT_IOCTLFUNCTION - callback for I/O operations 17 18# SYNOPSIS 19 20~~~c 21#include <curl/curl.h> 22 23typedef enum { 24 CURLIOE_OK, /* I/O operation successful */ 25 CURLIOE_UNKNOWNCMD, /* command was unknown to callback */ 26 CURLIOE_FAILRESTART, /* failed to restart the read */ 27 CURLIOE_LAST /* never use */ 28} curlioerr; 29 30typedef enum { 31 CURLIOCMD_NOP, /* no operation */ 32 CURLIOCMD_RESTARTREAD, /* restart the read stream from start */ 33 CURLIOCMD_LAST /* never use */ 34} curliocmd; 35 36curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp); 37 38CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLFUNCTION, ioctl_callback); 39~~~ 40 41# DESCRIPTION 42 43Pass a pointer to your callback function, which should match the prototype 44shown above. 45 46This callback function gets called by libcurl when something special 47I/O-related needs to be done that the library cannot do by itself. For now, 48rewinding the read data stream is the only action it can request. The 49rewinding of the read data stream may be necessary when doing an HTTP PUT or 50POST with a multi-pass authentication method. 51 52The callback MUST return *CURLIOE_UNKNOWNCMD* if the input *cmd* is 53not *CURLIOCMD_RESTARTREAD*. 54 55The *clientp* argument to the callback is set with the 56CURLOPT_IOCTLDATA(3) option. 57 58**This option is deprecated**. Do not use it. Use CURLOPT_SEEKFUNCTION(3) 59instead to provide seeking! If CURLOPT_SEEKFUNCTION(3) is set, this 60parameter is ignored when seeking. 61 62# DEFAULT 63 64By default, this parameter is set to NULL. Not used. 65 66# EXAMPLE 67 68~~~c 69#include <unistd.h> /* for lseek */ 70 71struct data { 72 int fd; /* our file descriptor */ 73}; 74 75static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp) 76{ 77 struct data *io = (struct data *)clientp; 78 if(cmd == CURLIOCMD_RESTARTREAD) { 79 lseek(io->fd, 0, SEEK_SET); 80 return CURLIOE_OK; 81 } 82 return CURLIOE_UNKNOWNCMD; 83} 84int main(void) 85{ 86 struct data ioctl_data; 87 CURL *curl = curl_easy_init(); 88 if(curl) { 89 curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); 90 curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); 91 } 92} 93~~~ 94 95# AVAILABILITY 96 97Added in 7.12.3. Deprecated since 7.18.0. 98 99# RETURN VALUE 100 101Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 102