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