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