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