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