1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_ERRORBUFFER
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_DEBUGFUNCTION (3)
9  - CURLOPT_VERBOSE (3)
10  - curl_easy_strerror (3)
11  - curl_multi_strerror (3)
12  - curl_share_strerror (3)
13  - curl_url_strerror (3)
14Protocol:
15  - All
16---
17
18# NAME
19
20CURLOPT_ERRORBUFFER - error buffer for error messages
21
22# SYNOPSIS
23
24~~~c
25#include <curl/curl.h>
26
27CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ERRORBUFFER, char *buf);
28~~~
29
30# DESCRIPTION
31
32Pass a char pointer to a buffer that libcurl may use to store human readable
33error messages on failures or problems. This may be more helpful than just the
34return code from curl_easy_perform(3) and related functions. The buffer must
35be at least **CURL_ERROR_SIZE** bytes big.
36
37You must keep the associated buffer available until libcurl no longer needs
38it. Failing to do so might cause odd behavior or even crashes. libcurl might
39need it until you call curl_easy_cleanup(3) or you set the same option
40again to use a different pointer.
41
42Do not rely on the contents of the buffer unless an error code was returned.
43Since 7.60.0 libcurl initializes the contents of the error buffer to an empty
44string before performing the transfer. For earlier versions if an error code
45was returned but there was no error detail then the buffer was untouched.
46
47Consider CURLOPT_VERBOSE(3) and CURLOPT_DEBUGFUNCTION(3) to better
48debug and trace why errors happen.
49
50# DEFAULT
51
52NULL
53
54# EXAMPLE
55
56~~~c
57#include <string.h> /* for strlen() */
58int main(void)
59{
60  CURL *curl = curl_easy_init();
61  if(curl) {
62    CURLcode res;
63    char errbuf[CURL_ERROR_SIZE];
64
65    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
66
67    /* provide a buffer to store errors in */
68    curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf);
69
70    /* set the error buffer as empty before performing a request */
71    errbuf[0] = 0;
72
73    /* perform the request */
74    res = curl_easy_perform(curl);
75
76    /* if the request did not complete correctly, show the error
77    information. if no detailed error information was written to errbuf
78    show the more generic information from curl_easy_strerror instead.
79    */
80    if(res != CURLE_OK) {
81      size_t len = strlen(errbuf);
82      fprintf(stderr, "\nlibcurl: (%d) ", res);
83      if(len)
84        fprintf(stderr, "%s%s", errbuf,
85                ((errbuf[len - 1] != '\n') ? "\n" : ""));
86      else
87        fprintf(stderr, "%s\n", curl_easy_strerror(res));
88    }
89  }
90}
91~~~
92
93# AVAILABILITY
94
95Always
96
97# RETURN VALUE
98
99Returns CURLE_OK
100