docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLOPT_DEBUGFUNCTION 3 "October 06, 2016" "libcurl 7.59.0" "curl_easy_setopt options"
  24
  25 .SH NAME
  26 CURLOPT_DEBUGFUNCTION \- debug callback
  27 .SH SYNOPSIS
  28 .nf
  29 #include <curl/curl.h>
  30
  31 typedef enum {
  32   CURLINFO_TEXT = 0,
  33   CURLINFO_HEADER_IN,    /* 1 */
  34   CURLINFO_HEADER_OUT,   /* 2 */
  35   CURLINFO_DATA_IN,      /* 3 */
  36   CURLINFO_DATA_OUT,     /* 4 */
  37   CURLINFO_SSL_DATA_IN,  /* 5 */
  38   CURLINFO_SSL_DATA_OUT, /* 6 */
  39   CURLINFO_END
  40 } curl_infotype;
  41
  42 int debug_callback(CURL *handle,
  43                    curl_infotype type,
  44                    char *data,
  45                    size_t size,
  46                    void *userptr);
  47
  48 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DEBUGFUNCTION,
  49                           debug_callback);
  50 .SH DESCRIPTION
  51 Pass a pointer to your callback function, which should match the prototype
  52 shown above.
  53
  54 \fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when
  55 \fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug
  56 information, as specified in the \fItype\fP argument. This function must
  57 return 0. The \fIdata\fP pointed to by the char * passed to this function WILL
  58 NOT be zero terminated, but will be exactly of the \fIsize\fP as told by the
  59 \fIsize\fP argument.
  60
  61 The \fIuserptr\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP.
  62
  63 Available curl_infotype values:
  64 .IP CURLINFO_TEXT
  65 The data is informational text.
  66 .IP CURLINFO_HEADER_IN
  67 The data is header (or header-like) data received from the peer.
  68 .IP CURLINFO_HEADER_OUT
  69 The data is header (or header-like) data sent to the peer.
  70 .IP CURLINFO_DATA_IN
  71 The data is protocol data received from the peer.
  72 .IP CURLINFO_DATA_OUT
  73 The data is protocol data sent to the peer.
  74 .IP CURLINFO_SSL_DATA_OUT
  75 The data is SSL/TLS (binary) data sent to the peer.
  76 .IP CURLINFO_SSL_DATA_IN
  77 The data is SSL/TLS (binary) data received from the peer.
  78 .SH DEFAULT
  79 NULL
  80 .SH PROTOCOLS
  81 All
  82 .SH EXAMPLE
  83 .nf
  84 static
  85 void dump(const char *text,
  86           FILE *stream, unsigned char *ptr, size_t size)
  87 {
  88   size_t i;
  89   size_t c;
  90   unsigned int width=0x10;
  91
  92   fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\\n",
  93           text, (long)size, (long)size);
  94
  95   for(i=0; i<size; i+= width) {
  96     fprintf(stream, "%4.4lx: ", (long)i);
  97
  98     /* show hex to the left */
  99     for(c = 0; c < width; c++) {
 100       if(i+c < size)
 101         fprintf(stream, "%02x ", ptr[i+c]);
 102       else
 103         fputs("   ", stream);
 104     }
 105
 106     /* show data on the right */
 107     for(c = 0; (c < width) && (i+c < size); c++) {
 108       char x = (ptr[i+c] >= 0x20 && ptr[i+c] < 0x80) ? ptr[i+c] : '.';
 109       fputc(x, stream);
 110     }
 111
 112     fputc('\\n', stream); /* newline */
 113   }
 114 }
 115
 116 static
 117 int my_trace(CURL *handle, curl_infotype type,
 118              char *data, size_t size,
 119              void *userp)
 120 {
 121   const char *text;
 122   (void)handle; /* prevent compiler warning */
 123   (void)userp;
 124
 125   switch (type) {
 126   case CURLINFO_TEXT:
 127     fprintf(stderr, "== Info: %s", data);
 128   default: /* in case a new one is introduced to shock us */
 129     return 0;
 130
 131   case CURLINFO_HEADER_OUT:
 132     text = "=> Send header";
 133     break;
 134   case CURLINFO_DATA_OUT:
 135     text = "=> Send data";
 136     break;
 137   case CURLINFO_SSL_DATA_OUT:
 138     text = "=> Send SSL data";
 139     break;
 140   case CURLINFO_HEADER_IN:
 141     text = "<= Recv header";
 142     break;
 143   case CURLINFO_DATA_IN:
 144     text = "<= Recv data";
 145     break;
 146   case CURLINFO_SSL_DATA_IN:
 147     text = "<= Recv SSL data";
 148     break;
 149   }
 150
 151   dump(text, stderr, (unsigned char *)data, size);
 152   return 0;
 153 }
 154
 155 int main(void)
 156 {
 157   CURL *curl;
 158   CURLcode res;
 159
 160   curl = curl_easy_init();
 161   if(curl) {
 162     curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
 163
 164     /* the DEBUGFUNCTION has no effect until we enable VERBOSE */
 165     curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
 166
 167     /* example.com is redirected, so we tell libcurl to follow redirection */
 168     curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
 169
 170     curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
 171     res = curl_easy_perform(curl);
 172     /* Check for errors */
 173     if(res != CURLE_OK)
 174       fprintf(stderr, "curl_easy_perform() failed: %s\\n",
 175               curl_easy_strerror(res));
 176
 177     /* always cleanup */
 178     curl_easy_cleanup(curl);
 179   }
 180   return 0;
 181 }
 182 .fi
 183 .SH AVAILABILITY
 184 Always
 185 .SH RETURN VALUE
 186 Returns CURLE_OK
 187 .SH "SEE ALSO"
 188 .BR CURLOPT_VERBOSE "(3), " CURLOPT_DEBUGDATA "(3), "