Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_HEADERFUNCTION(3)  curl_easy_setopt options  CURLOPT_HEADERFUNCTION(3)

NAME
       CURLOPT_HEADERFUNCTION -	callback that receives header data

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);

DESCRIPTION
       Pass a pointer to your callback function, which should match the	proto-
       type 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. buffer points to the delivered data, and the size
       of that data is nitems; size is always 1. Do not	assume that the	header
       line is null-terminated!

       The pointer named userdata is the one you set with the  CURLOPT_HEADER-
       DATA(3) 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  re-
       turn CURLE_WRITE_ERROR.

       A  complete  HTTP  header  that is passed to this function can be up to
       CURL_MAX_HTTP_HEADER (100K) bytes and includes the final	line  termina-
       tor.

       If this option is not set, or if	it is set to NULL, but CURLOPT_HEADER-
       DATA(3) is set to anything but NULL, the	function used  to  accept  re-
       sponse  data  will  be  used  instead. That is, it will be the function
       specified with CURLOPT_WRITEFUNCTION(3),	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 head-
       ers of all responses received after initiating a	request	and  not  just
       the  final response. This includes all responses	which occur during au-
       thentication negotiation. If you	need to	operate	on  only  the  headers
       from  the final response, you will need to collect headers in the call-
       back yourself and use HTTP status lines,	for example,  to  delimit  re-
       sponse 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.

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.

DEFAULT
       Nothing.

PROTOCOLS
       Used for	all protocols with headers or meta-data	 concept:  HTTP,  FTP,
       POP3, IMAP, SMTP	and more.

EXAMPLE
       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);
       }

AVAILABILITY
       Always

RETURN VALUE
       Returns CURLE_OK

SEE ALSO
       CURLOPT_HEADERDATA(3), CURLOPT_WRITEFUNCTION(3),

libcurl	7.74.0		       November	04, 2020     CURLOPT_HEADERFUNCTION(3)

NAME | SYNOPSIS | DESCRIPTION | LIMITATIONS | DEFAULT | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CURLOPT_HEADERFUNCTION&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help