1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_TRAILERFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_TRAILERDATA (3)
9  - CURLOPT_WRITEFUNCTION (3)
10---
11
12# NAME
13
14CURLOPT_TRAILERFUNCTION - callback for sending trailing headers
15
16# SYNOPSIS
17
18~~~c
19#include <curl.h>
20
21int curl_trailer_callback(struct curl_slist ** list, void *userdata);
22
23CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION,
24                          curl_trailer_callback *func);
25~~~
26
27# DESCRIPTION
28
29Pass a pointer to a callback function.
30
31This callback function is called once right before sending the final CR LF in
32an HTTP chunked transfer to fill a list of trailing headers to be sent before
33finishing the HTTP transfer.
34
35You can set the userdata argument with the CURLOPT_TRAILERDATA(3)
36option.
37
38The trailing headers included in the linked list must not be CRLF-terminated,
39because libcurl adds the appropriate line termination characters after each
40header item.
41
42If you use curl_slist_append(3) to add trailing headers to the *curl_slist*
43then libcurl duplicates the strings, and frees the *curl_slist* once the
44trailers have been sent.
45
46If one of the trailing header fields is not formatted correctly it is ignored
47and an info message is emitted.
48
49The return value can either be **CURL_TRAILERFUNC_OK** or
50**CURL_TRAILERFUNC_ABORT** which would respectively instruct libcurl to
51either continue with sending the trailers or to abort the request.
52
53If you set this option to NULL, then the transfer proceeds as usual
54without any interruptions.
55
56# DEFAULT
57
58NULL
59
60# PROTOCOLS
61
62HTTP
63
64# EXAMPLE
65~~~c
66static int trailer_cb(struct curl_slist **tr, void *data)
67{
68  /* libcurl frees the list */
69  *tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff");
70  return CURL_TRAILERFUNC_OK;
71}
72
73int main(void)
74{
75  CURL *curl = curl_easy_init();
76  if(curl) {
77    CURLcode res;
78
79    /* Set the URL of the request */
80    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
81    /* Now set it as a put */
82    curl_easy_setopt(curl, CURLOPT_PUT, 1L);
83
84    /* Assuming we have a function that returns the data to be pushed
85       Let that function be read_cb */
86    curl_easy_setopt(curl, CURLOPT_READFUNCTION, trailer_cb);
87
88    struct curl_slist *headers = NULL;
89    headers = curl_slist_append(headers, "Trailer: My-super-awesome-trailer");
90    res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
91
92    /* Set the trailers filling callback */
93    curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb);
94
95    /* Perform the transfer */
96    res = curl_easy_perform(curl);
97
98    curl_easy_cleanup(curl);
99
100    curl_slist_free_all(headers);
101  }
102}
103~~~
104# AVAILABILITY
105
106This option was added in curl 7.64.0 and is present if HTTP support is enabled.
107
108# RETURN VALUE
109
110Returns CURLE_OK.
111