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