curl_formget_callback append);
.fi
.SH DESCRIPTION
-curl_formget() is used to serialize data previously built/appended with
-\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named
-\fIuserp\fP which is passed as the first argument to the curl_formget_callback
-function.
+curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It
+accepts a void pointer as second argument named \fIuserp\fP which is passed as
+the first argument to the curl_formget_callback function.
-.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf,
-.BI " size_t " len ");"
+.nf
+ typedef size_t (*curl_formget_callback)(void *userp, const char *buf,
+ size_t len);"
+.fi
The curl_formget_callback is invoked for each part of the HTTP POST chain. The
character buffer passed to the callback must not be freed. The callback should
A "date" is a string containing several items separated by whitespace. The
order of the items is immaterial. A date string may contain many flavors of
items:
-.TP 0.8i
-.B calendar date items
+.IP "calendar date items"
Can be specified several ways. Month names can only be three-letter English
abbreviations, numbers can be zero-prefixed and the year may use 2 or 4
digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6.
-.TP
-.B time of the day items
+.IP "time of the day items"
This string specifies the time on a given day. You must specify it with 6
digits with two colons: HH:MM:SS. If there is no time given in a provided date
string, 00:00:00 is assumed. Example: 18:19:21.
-.TP
-.B time zone items
+.IP "time zone items"
Specifies international time zone. There are a few acronyms supported, but in
general you should instead use the specific relative time compared to
UTC. Supported formats include: -1200, MST, +0100.
-.TP
-.B day of the week items
+.IP "day of the week items"
Specifies a day of the week. Days of the week may be spelled out in full
(using English): `Sunday', `Monday', etc or they may be abbreviated to their
first three letters. This is usually not info that adds anything.
-.TP
-.B pure numbers
+.IP "pure numbers"
If a decimal number of the form YYYYMMDD appears, then YYYY is read as the
year, MM as the month number and DD as the day of the month, for the specified
calendar date.
To replace strdup()
.IP "void *calloc_callback(size_t nmemb, size_t size);"
To replace calloc()
-.PP
+
This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer
to that man page for documentation.
.SH CAUTION
is added to the part.
Supported encoding schemes are:
-.br
+
"\fIbinary\fP": the data is left unchanged, the header is added.
-.br
+
"\fI8bit\fP": header added, no data change.
-.br
+
"\fI7bit\fP": the data is unchanged, but is each byte is checked
to be a 7-bit value; if not, a read error occurs.
-.br
+
"\fIbase64\fP": Data is converted to base64 encoding, then split in
CRLF-terminated lines of at most 76 characters.
-.br
+
"\fIquoted-printable\fP": data is encoded in quoted printable lines of
at most 76 characters. Since the resulting size of the final data cannot be
determined prior to reading the original data, it is left as unknown, causing
In the absence of a mime type and if needed by the protocol specifications,
a default mime type is determined by the context:
-.br
+
- If set as a custom header, use this value.
-.br
+
- application/form-data for an HTTP form post.
-.br
+
- If a remote file name is set, the mime type is taken from the file name
extension, or application/octet-stream by default.
-.br
+
- For a multipart part, multipart/mixed.
-.br
+
- text/plain in other cases.
.SH EXAMPLE
.nf
.SH "Flag characters"
The character % is followed by zero or more of the following flags:
-.TP
-.B #
+
+.IP #
The value should be converted to its "alternate form".
-.TP
-.B 0
+.IP 0
The value should be zero padded.
-.TP
-.B -
+.IP -
The converted value is to be left adjusted on the field boundary. (The
default is right justification.) The converted value is padded on the right
with blanks, rather than on the left with blanks or zeros. A '-' overrides a
\&'0' if both are given.
-.TP
-.B ' '
+.IP ' '
(a space) A blank should be left before a positive number (or empty string)
produced by a signed conversion.
-.TP
-.B +
+.IP +
A sign (+ or -) should always be placed before a number produced by a signed
conversion. By default, a sign is used only for negative numbers. A '+'
overrides a space if both are used.
\fBG\fP conversions, or the maximum number of characters to be printed from a
string for \fBs\fP and \fBS\fP conversions.
.SH "Length modifier"
-.TP
-.B h
+.IP h
A following integer conversion corresponds to a \fIshort\fP or \fIunsigned
short\fP argument.
-.TP
-.B l
+.IP l
(ell) A following integer conversion corresponds to a \fIlong\fP or
\fIunsigned long\fP argument, or a following n conversion corresponds to a
pointer to a long argument
-.TP
-.B ll
+.IP ll
(ell-ell). A following integer conversion corresponds to a \fIlong long\fP or
\fIunsigned long long\fP argument, or a following n conversion corresponds to
a pointer to a long long argument.
-.TP
-.B q
+.IP q
A synonym for \fBll\fP.
-.TP
-.B L
+.IP L
A following a, A, e, E, f, F, g, or G conversion corresponds to a long double
argument.
-.TP
-.B z
+.IP z
A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP
argument.
.SH "Conversion specifiers"
A character that specifies the type of conversion to be applied. The
conversion specifiers and their meanings are:
-.TP
-.B d, i
+.IP "d, i"
The int argument is converted to signed decimal notation. The precision, if
any, gives the minimum number of digits that must appear; if the converted
value requires fewer digits, it is padded on the left with zeros. The default
precision is 1. When 0 is printed with an explicit precision 0, the output is
empty.
-.TP
-.B o, u, x, X
+.IP "o, u, x, X"
The unsigned int argument is converted to unsigned octal (o), unsigned decimal
(u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters
\fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are
of digits that must appear; if the converted value requires fewer digits, it
is padded on the left with zeros. The default precision is 1. When 0 is
printed with an explicit precision 0, the output is empty.
-.TP
-.B e, E
+.IP "e, E"
The double argument is rounded and output in the style \fB"[-]d.ddde±dd"\fP
-.TP
-.B f, F
+.IP "f, F"
The double argument is rounded and output to decimal notation in the style
\fB"[-]ddd.ddd"\fP.
-.TP
-.B g, G
+.IP "g, G"
The double argument is converted in style f or e.
-.TP
-.B c
+.IP "c"
The int argument is converted to an unsigned char, and the resulting character
is written.
-.TP
-.B s
+.IP "s"
The \fIconst char *\fP argument is expected to be a pointer to an array of
character type (pointer to a string). Characters from the array are written up
to (but not including) a terminating null byte. If a precision is specified,
no more than the number specified are written. If a precision is given, no
null byte need be present; if the precision is not specified, or is greater
than the size of the array, the array must contain a terminating null byte.
-.TP
-.B p
+.IP "p"
The \fIvoid *\fP pointer argument is printed in hexadecimal.
-.TP
-.B n
+.IP "n"
The number of characters written so far is stored into the integer pointed to
by the corresponding argument.
-.TP
-.B %
-A '%' is written. No argument is converted.
+.IP "%"
+A '%' symbol is written. No argument is converted.
.SH EXAMPLE
.nf
const char *name = "John";
int curl_strnequal(const char *str1, const char *str2, size_t length);
.fi
.SH DESCRIPTION
-The
-.B curl_strequal()
-function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case
-of the characters. It returns a non-zero (TRUE) integer if the strings are
-identical.
-.sp
+The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and
+\fIstr2\fP, ignoring the case of the characters. It returns a non-zero (TRUE)
+integer if the strings are identical.
+
The \fBcurl_strnequal()\fP function is similar, except it only compares the
first \fIlength\fP characters of \fIstr1\fP.
-.sp
+
These functions are provided by libcurl to enable applications to compare
strings in a truly portable manner. There are no standard portable case
insensitive string comparison functions. These two work on all platforms.
.RS
.IP """alt-svc"""
\fIfeatures\fP mask bit: CURL_VERSION_ALTSVC
-.br
+
HTTP Alt-Svc parsing and the associated options (Added in 7.64.1)
.IP """AsynchDNS"""
\fIfeatures\fP mask bit: CURL_VERSION_ASYNCHDNS
-.br
+
libcurl was built with support for asynchronous name lookups, which allows
more exact timeouts (even on Windows) and less blocking when using the multi
interface. (added in 7.10.7)
.IP """brotli"""
\fIfeatures\fP mask bit: CURL_VERSION_BROTLI
-.br
+
supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0)
.IP """Debug"""
\fIfeatures\fP mask bit: CURL_VERSION_DEBUG
-.br
+
libcurl was built with debug capabilities (added in 7.10.6)
.IP """gsasl"""
\fIfeatures\fP mask bit: CURL_VERSION_GSASL
-.br
+
libcurl was built with libgsasl and thus with some extra SCRAM-SHA
authentication methods. (added in 7.76.0)
.IP """GSS-API"""
\fIfeatures\fP mask bit: CURL_VERSION_GSSAPI
-.br
+
libcurl was built with support for GSS-API. This makes libcurl use provided
functions for Kerberos and SPNEGO authentication. It also allows libcurl
to use the current user credentials without the app having to pass them on.
(Added in 7.38.0)
.IP """HSTS"""
\fIfeatures\fP mask bit: CURL_VERSION_HSTS
-.br
+
libcurl was built with support for HSTS (HTTP Strict Transport Security)
(Added in 7.74.0)
.IP """HTTP2"""
\fIfeatures\fP mask bit: CURL_VERSION_HTTP2
-.br
+
libcurl was built with support for HTTP2.
(Added in 7.33.0)
.IP """HTTP3"""
\fIfeatures\fP mask bit: CURL_VERSION_HTTP3
-.br
+
HTTP/3 and QUIC support are built-in (Added in 7.66.0)
.IP """HTTPS-proxy"""
\fIfeatures\fP mask bit: CURL_VERSION_HTTPS_PROXY
-.br
+
libcurl was built with support for HTTPS-proxy.
(Added in 7.52.0)
.IP """IDN"""
\fIfeatures\fP mask bit: CURL_VERSION_IDN
-.br
+
libcurl was built with support for IDNA, domain names with international
letters. (Added in 7.12.0)
.IP """IPv6"""
\fIfeatures\fP mask bit: CURL_VERSION_IPV6
-.br
+
supports IPv6
.IP """Kerberos"""
\fIfeatures\fP mask bit: CURL_VERSION_KERBEROS5
-.br
+
supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and
SOCKSv5 proxy. (Added in 7.40.0)
.IP """Largefile"""
\fIfeatures\fP mask bit: CURL_VERSION_LARGEFILE
-.br
+
libcurl was built with support for large files. (Added in 7.11.1)
.IP """libz"""
\fIfeatures\fP mask bit: CURL_VERSION_LIBZ
-.br
+
supports HTTP deflate using libz (Added in 7.10)
.IP """MultiSSL"""
\fIfeatures\fP mask bit: CURL_VERSION_MULTI_SSL
-.br
+
libcurl was built with multiple SSL backends. For details, see
\fIcurl_global_sslset(3)\fP.
(Added in 7.56.0)
.IP """NTLM"""
\fIfeatures\fP mask bit: CURL_VERSION_NTLM
-.br
+
supports HTTP NTLM (added in 7.10.6)
.IP """NTLM_WB"""
\fIfeatures\fP mask bit: CURL_VERSION_NTLM_WB
-.br
+
libcurl was built with support for NTLM delegation to a winbind helper.
(Added in 7.22.0)
.IP """PSL"""
\fIfeatures\fP mask bit: CURL_VERSION_PSL
-.br
+
libcurl was built with support for Mozilla's Public Suffix List. This makes
libcurl ignore cookies with a domain that is on the list.
(Added in 7.47.0)
.IP """SPNEGO"""
\fIfeatures\fP mask bit: CURL_VERSION_SPNEGO
-.br
+
libcurl was built with support for SPNEGO authentication (Simple and Protected
GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8)
.IP """SSL"""
\fIfeatures\fP mask bit: CURL_VERSION_SSL
-.br
+
supports SSL (HTTPS/FTPS) (Added in 7.10)
.IP """SSPI"""
\fIfeatures\fP mask bit: CURL_VERSION_SSPI
-.br
+
libcurl was built with support for SSPI. This is only available on Windows and
makes libcurl use Windows-provided functions for Kerberos, NTLM, SPNEGO and
Digest authentication. It also allows libcurl to use the current user
credentials without the app having to pass them on. (Added in 7.13.2)
.IP """threadsafe"""
\fIfeatures\fP mask bit: CURL_VERSION_THREADSAFE
-.br
+
libcurl was built with thread-safety support (Atomic or SRWLOCK) to protect
curl initialization. (Added in 7.84.0) See \fIlibcurl-thread(3)\fP
.IP """TLS-SRP"""
\fIfeatures\fP mask bit: CURL_VERSION_TLSAUTH_SRP
-.br
+
libcurl was built with support for TLS-SRP (in one or more of the built-in TLS
backends). (Added in 7.21.4)
.IP """TrackMemory"""
\fIfeatures\fP mask bit: CURL_VERSION_CURLDEBUG
-.br
+
libcurl was built with memory tracking debug capabilities. This is mainly of
interest for libcurl hackers. (added in 7.19.6)
.IP """Unicode"""
\fIfeatures\fP mask bit: CURL_VERSION_UNICODE
-.br
+
libcurl was built with Unicode support on Windows. This makes non-ASCII
characters work in filenames and options passed to libcurl. (Added in 7.72.0)
.IP """UnixSockets"""
\fIfeatures\fP mask bit: CURL_VERSION_UNIX_SOCKETS
-.br
+
libcurl was built with support for Unix domain sockets.
(Added in 7.40.0)
.IP """zstd"""
\fIfeatures\fP mask bit: CURL_VERSION_ZSTD
-.br
+
supports HTTP zstd content encoding using zstd library (Added in 7.72.0)
.IP none
\fIfeatures\fP mask bit: CURL_VERSION_CONV
-.br
+
libcurl was built with support for character conversions, as provided by the
CURLOPT_CONV_* callbacks. Always 0 since 7.82.0. (Added in 7.15.4)
.IP none
\fIfeatures\fP mask bit: CURL_VERSION_GSSNEGOTIATE
-.br
+
supports HTTP GSS-Negotiate (added in 7.10.6, deprecated in 7.38.0)
.IP none
\fIfeatures\fP mask bit: CURL_VERSION_KERBEROS4
-.br
+
supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0.
.RE
.SH "Converting from deprecated form API to MIME API"
Four rules have to be respected in building the multi-part:
-.br
+
- The easy handle must be created before building the multi-part.
-.br
+
- The multi-part is always created by a call to curl_mime_init(handle).
-.br
+
- Each part is created by a call to curl_mime_addpart(multipart).
-.br
+
- When complete, the multi-part must be bound to the easy handle using
\fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP.
.fi
.SH DESCRIPTION
Provides AWS V4 signature authentication on HTTP(S) header.
-.PP
+
Pass a char * that is the collection of specific arguments are used for
creating outgoing authentication headers. The format of the \fIparam\fP
option is:
.IP provider1[:provider2[:region[:service]]]
-.IP provider1,\ provider2
+.IP "provider1, provider2"
The providers arguments are used for generating some authentication parameters
such as "Algorithm", "date", "request type" and "signed headers".
.IP region
.IP service
The argument is a function provided by a cloud.
It is extracted from the host name specified in the URL if omitted.
-.PP
+
NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4.
Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same
as calling this with \fB"aws:amz"\fP in parameter.
-.PP
+
Example with "Test:Try", when curl uses the algorithm, it generates
\fB"TEST-HMAC-SHA256"\fP for "Algorithm", \fB"x-try-date"\fP and
\fB"X-Try-Date"\fP for "date", \fB"test4_request"\fP for "request type",
\fB"SignedHeaders=content-type;host;x-try-date"\fP for "signed headers"
-.PP
+
If you use just "test", instead of "test:try", test is used for every
generated string.
.SH DEFAULT
This option overrides the other auth types you might have set in
\fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth
method special. This method cannot be combined with other auth types.
-.PP
+
A sha256 checksum of the request payload is used as input to the signature
calculation. For POST requests, this is a checksum of the provided
\fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it's the checksum of an empty buffer.
For requests like PUT, you can provide your own checksum in an HTTP header named
\fBx-provider2-content-sha256\fP.
-.PP
+
For \fBaws:s3\fP, a \fBx-amz-content-sha256\fP header is added to every request
if not already present. For s3 requests with unknown payload, this header takes
the special value "UNSIGNED-PAYLOAD".
projects / thirdparty / curl.git / commitdiff
