1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_CUSTOMREQUEST 5Section: 3 6Source: libcurl 7See-also: 8 - CURLINFO_EFFECTIVE_METHOD (3) 9 - CURLOPT_HTTPHEADER (3) 10 - CURLOPT_NOBODY (3) 11 - CURLOPT_REQUEST_TARGET (3) 12Protocol: 13 - HTTP 14 - FTP 15 - IMAP 16 - POP3 17 - SMTP 18--- 19 20# NAME 21 22CURLOPT_CUSTOMREQUEST - custom request method 23 24# SYNOPSIS 25 26~~~c 27#include <curl/curl.h> 28 29CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method); 30~~~ 31 32# DESCRIPTION 33 34Pass a pointer to a null-terminated string as parameter. 35 36When changing the request *method* by setting CURLOPT_CUSTOMREQUEST(3), you 37do not actually change how libcurl behaves or acts: you only change the actual 38string sent in the request. 39 40libcurl passes on the verbatim string in its request without any filter or 41other safe guards. That includes white space and control characters. 42 43Restore to the internal default by setting this to NULL. 44 45This option can be used to specify the request: 46 47## HTTP 48 49Instead of GET or HEAD when performing HTTP based requests. This is 50particularly useful, for example, for performing an HTTP DELETE request. 51 52For example: 53 54When you tell libcurl to do a HEAD request, but then specify a GET though a 55custom request libcurl still acts as if it sent a HEAD. To switch to a proper 56HEAD use CURLOPT_NOBODY(3), to switch to a proper POST use 57CURLOPT_POST(3) or CURLOPT_POSTFIELDS(3) and to switch to a proper 58GET use CURLOPT_HTTPGET(3). 59 60Many people have wrongly used this option to replace the entire request with 61their own, including multiple headers and POST contents. While that might work 62in many cases, it might cause libcurl to send invalid requests and it could 63possibly confuse the remote server badly. Use CURLOPT_POST(3) and 64CURLOPT_POSTFIELDS(3) to set POST data. Use CURLOPT_HTTPHEADER(3) 65to replace or extend the set of headers sent by libcurl. Use 66CURLOPT_HTTP_VERSION(3) to change HTTP version. 67 68## FTP 69 70Instead of LIST and NLST when performing FTP directory listings. 71 72## IMAP 73 74Instead of LIST when issuing IMAP based requests. 75 76## POP3 77 78Instead of LIST and RETR when issuing POP3 based requests. 79 80For example: 81 82When you tell libcurl to use a custom request it behaves like a LIST or RETR 83command was sent where it expects data to be returned by the server. As such 84CURLOPT_NOBODY(3) should be used when specifying commands such as 85**DELE** and **NOOP** for example. 86 87## SMTP 88 89Instead of a **HELP** or **VRFY** when issuing SMTP based requests. 90 91For example: 92 93Normally a multi line response is returned which can be used, in conjunction 94with CURLOPT_MAIL_RCPT(3), to specify an EXPN request. If the 95CURLOPT_NOBODY(3) option is specified then the request can be used to 96issue **NOOP** and **RSET** commands. 97 98The application does not have to keep the string around after setting this 99option. 100 101# DEFAULT 102 103NULL 104 105# EXAMPLE 106 107~~~c 108int main(void) 109{ 110 CURL *curl = curl_easy_init(); 111 if(curl) { 112 CURLcode res; 113 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); 114 115 /* DELETE the given path */ 116 curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE"); 117 118 res = curl_easy_perform(curl); 119 120 curl_easy_cleanup(curl); 121 } 122} 123~~~ 124 125# AVAILABILITY 126 127IMAP is supported since 7.30.0, POP3 since 7.26.0 and SMTP since 7.34.0. 128 129# RETURN VALUE 130 131Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or 132CURLE_OUT_OF_MEMORY if there was insufficient heap space. 133