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 http://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       fputc(ptr[i+c]>=0x20) && (ptr[i+c]<0x80)?ptr[i+c]:'.', stream);
 108
 109     fputc('\n', stream); /* newline */
 110   }
 111 }
 112
 113 static
 114 int my_trace(CURL *handle, curl_infotype type,
 115              char *data, size_t size,
 116              void *userp)
 117 {
 118   const char *text;
 119   (void)handle; /* prevent compiler warning */
 120
 121   switch (type) {
 122   case CURLINFO_TEXT:
 123     fprintf(stderr, "== Info: %s", data);
 124   default: /* in case a new one is introduced to shock us */
 125     return 0;
 126
 127   case CURLINFO_HEADER_OUT:
 128     text = "=> Send header";
 129     break;
 130   case CURLINFO_DATA_OUT:
 131     text = "=> Send data";
 132     break;
 133   case CURLINFO_SSL_DATA_OUT:
 134     text = "=> Send SSL data";
 135     break;
 136   case CURLINFO_HEADER_IN:
 137     text = "<= Recv header";
 138     break;
 139   case CURLINFO_DATA_IN:
 140     text = "<= Recv data";
 141     break;
 142   case CURLINFO_SSL_DATA_IN:
 143     text = "<= Recv SSL data";
 144     break;
 145   }
 146
 147   dump(text, stderr, (unsigned char *)data, size);
 148   return 0;
 149 }
 150
 151 int main(void)
 152 {
 153   CURL *curl;
 154   CURLcode res;
 155
 156   curl = curl_easy_init();
 157   if(curl) {
 158     curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace);
 159
 160     /* the DEBUGFUNCTION has no effect until we enable VERBOSE */
 161     curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
 162
 163     /* example.com is redirected, so we tell libcurl to follow redirection */
 164     curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
 165
 166     curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
 167     res = curl_easy_perform(curl);
 168     /* Check for errors */
 169     if(res != CURLE_OK)
 170       fprintf(stderr, "curl_easy_perform() failed: %s\n",
 171               curl_easy_strerror(res));
 172
 173     /* always cleanup */
 174     curl_easy_cleanup(curl);
 175   }
 176   return 0;
 177 }
 178 .fi
 179 .SH AVAILABILITY
 180 Always
 181 .SH RETURN VALUE
 182 Returns CURLE_OK
 183 .SH "SEE ALSO"
 184 .BR CURLOPT_VERBOSE "(3), " CURLOPT_DEBUGDATA "(3), "