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