first commit

curl/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3

@@ -0,0 +1,118 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <[email protected]>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.\"
+.TH CURLOPT_HEADERFUNCTION 3 "November 04, 2020" "libcurl 7.75.0" "curl_easy_setopt options"
+
+.SH NAME
+CURLOPT_HEADERFUNCTION \- callback that receives header data
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+size_t header_callback(char *buffer,
+                       size_t size,
+                       size_t nitems,
+                       void *userdata);
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback);
+.SH DESCRIPTION
+Pass a pointer to your callback function, which should match the prototype
+shown above.
+
+This function gets called by libcurl as soon as it has received header
+data. The header callback will be called once for each header and only
+complete header lines are passed on to the callback. Parsing headers is very
+easy using this. \fIbuffer\fP points to the delivered data, and the size of
+that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that the
+header line is null-terminated!
+
+The pointer named \fIuserdata\fP is the one you set with the
+\fICURLOPT_HEADERDATA(3)\fP option.
+
+This callback function must return the number of bytes actually taken care of.
+If that amount differs from the amount passed in to your function, it'll signal
+an error to the library. This will cause the transfer to get aborted and the
+libcurl function in progress will return \fICURLE_WRITE_ERROR\fP.
+
+A complete HTTP header that is passed to this function can be up to
+\fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator.
+
+If this option is not set, or if it is set to NULL, but
+\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to
+accept response data will be used instead. That is, it will be the function
+specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or
+NULL - the default, stream-writing function.
+
+It's important to note that the callback will be invoked for the headers of
+all responses received after initiating a request and not just the final
+response. This includes all responses which occur during authentication
+negotiation. If you need to operate on only the headers from the final
+response, you will need to collect headers in the callback yourself and use
+HTTP status lines, for example, to delimit response boundaries.
+
+For an HTTP transfer, the status line and the blank line preceding the response
+body are both included as headers and passed to this function.
+
+When a server sends a chunked encoded transfer, it may contain a trailer. That
+trailer is identical to an HTTP header and if such a trailer is received it is
+passed to the application using this callback as well. There are several ways
+to detect it being a trailer and not an ordinary header: 1) it comes after the
+response-body. 2) it comes after the final header line (CR LF) 3) a Trailer:
+header among the regular response-headers mention what header(s) to expect in
+the trailer.
+
+For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get
+called with the server responses to the commands that libcurl sends.
+.SH LIMITATIONS
+libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A
+folded header is a header that continues on a subsequent line and starts with
+a whitespace. Such folds will be passed to the header callback as a separate
+one, although strictly it is just a continuation of the previous line.
+.SH DEFAULT
+Nothing.
+.SH PROTOCOLS
+Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3,
+IMAP, SMTP and more.
+.SH EXAMPLE
+.nf
+static size_t header_callback(char *buffer, size_t size,
+                              size_t nitems, void *userdata)
+{
+  /* received header is nitems * size long in 'buffer' NOT ZERO TERMINATED */
+  /* 'userdata' is set with CURLOPT_HEADERDATA */
+  return nitems * size;
+}
+
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+  curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback);
+
+  curl_easy_perform(curl);
+}
+.fi
+.SH AVAILABILITY
+Always
+.SH RETURN VALUE
+Returns CURLE_OK
+.SH "SEE ALSO"
+.BR CURLOPT_HEADERDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "