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