Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3, revision 1.1.1.1
1.1 misho 1: .\" **************************************************************************
2: .\" * _ _ ____ _
3: .\" * Project ___| | | | _ \| |
4: .\" * / __| | | | |_) | |
5: .\" * | (__| |_| | _ <| |___
6: .\" * \___|\___/|_| \_\_____|
7: .\" *
8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
9: .\" *
10: .\" * This software is licensed as described in the file COPYING, which
11: .\" * you should have received as part of this distribution. The terms
12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13: .\" *
14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15: .\" * copies of the Software, and permit persons to whom the Software is
16: .\" * furnished to do so, under the terms of the COPYING file.
17: .\" *
18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19: .\" * KIND, either express or implied.
20: .\" *
21: .\" **************************************************************************
22: .\"
23: .TH CURLOPT_IOCTLFUNCTION 3 "March 23, 2020" "libcurl 7.70.0" "curl_easy_setopt options"
24:
25: .SH NAME
26: CURLOPT_IOCTLFUNCTION \- callback for I/O operations
27: .SH SYNOPSIS
28: .nf
29: #include <curl/curl.h>
30:
31: typedef enum {
32: CURLIOE_OK, /* I/O operation successful */
33: CURLIOE_UNKNOWNCMD, /* command was unknown to callback */
34: CURLIOE_FAILRESTART, /* failed to restart the read */
35: CURLIOE_LAST /* never use */
36: } curlioerr;
37:
38: typedef enum {
39: CURLIOCMD_NOP, /* no operation */
40: CURLIOCMD_RESTARTREAD, /* restart the read stream from start */
41: CURLIOCMD_LAST /* never use */
42: } curliocmd;
43:
44: curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp);
45:
46: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_IOCTLFUNCTION, ioctl_callback);
47: .SH DESCRIPTION
48: Pass a pointer to your callback function, which should match the prototype
49: shown above.
50:
51: This callback function gets called by libcurl when something special
52: I/O-related needs to be done that the library can't do by itself. For now,
53: rewinding the read data stream is the only action it can request. The
54: rewinding of the read data stream may be necessary when doing an HTTP PUT or
55: POST with a multi-pass authentication method.
56:
57: The callback MUST return \fICURLIOE_UNKNOWNCMD\fP if the input \fIcmd\fP is
58: not \fICURLIOCMD_RESTARTREAD\fP.
59:
60: The \fIclientp\fP argument to the callback is set with the
61: \fICURLOPT_IOCTLDATA(3)\fP option.
62:
63: This option is deprecated! Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP
64: instead to provide seeking! If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this
65: parameter will be ignored when seeking.
66: .SH DEFAULT
67: By default, this parameter is set to NULL. Not used.
68: .SH PROTOCOLS
69: Used with HTTP
70: .SH EXAMPLE
71: .nf
72: static curlioerr ioctl_callback(CURL *handle, int cmd, void *clientp)
73: {
74: struct data *io = (struct data *)clientp;
75: if(cmd == CURLIOCMD_RESTARTREAD) {
76: lseek(fd, 0, SEEK_SET);
77: current_offset = 0;
78: return CURLIOE_OK;
79: }
80: return CURLIOE_UNKNOWNCMD;
81: }
82: {
83: struct data ioctl_data;
84: curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback);
85: curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data);
86: }
87: .fi
88: .SH AVAILABILITY
89: Added in 7.12.3
90: .SH RETURN VALUE
91: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
92: .SH "SEE ALSO"
93: .BR CURLOPT_IOCTLDATA "(3), " CURLOPT_SEEKFUNCTION "(3), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>