docs/BUGS

   1                                   _   _ ____  _
   2                               ___| | | |  _ \| |
   3                              / __| | | | |_) | |
   4                             | (__| |_| |  _ <| |___
   5                              \___|\___/|_| \_\_____|
   6
   7 BUGS
   8
   9  1. Bugs
  10   1.1 There are still bugs
  11   1.2 Where to report
  12   1.3 What to report
  13   1.4 libcurl problems
  14   1.5 Who will fix the problems
  15   1.6 How to get a stack trace
  16   1.7 Bugs in libcurl bindings
  17
  18 ==============================================================================
  19
  20 1.1 There are still bugs
  21
  22   Curl and libcurl have grown substantially since the beginning. At the time
  23   of writing (January 2013), there are about 83,000 lines of source code, and
  24   by the time you read this it has probably grown even more.
  25
  26   Of course there are lots of bugs left. And lots of misfeatures.
  27
  28   To help us make curl the stable and solid product we want it to be, we need
  29   bug reports and bug fixes.
  30
  31 1.2 Where to report
  32
  33   If you can't fix a bug yourself and submit a fix for it, try to report an as
  34   detailed report as possible to a curl mailing list to allow one of us to
  35   have a go at a solution. You can optionally also post your bug/problem at
  36   curl's bug tracking system over at
  37
  38         https://github.com/curl/curl/issues
  39
  40   Please read the rest of this document below first before doing that!
  41
  42   If you feel you need to ask around first, find a suitable mailing list and
  43   post there. The lists are available on https://curl.haxx.se/mail/
  44
  45 1.3 What to report
  46
  47   When reporting a bug, you should include all information that will help us
  48   understand what's wrong, what you expected to happen and how to repeat the
  49   bad behavior. You therefore need to tell us:
  50
  51    - your operating system's name and version number
  52
  53    - what version of curl you're using (curl -V is fine)
  54
  55    - versions of the used libraries that libcurl is built to use
  56
  57    - what URL you were working with (if possible), at least which protocol
  58
  59   and anything and everything else you think matters. Tell us what you
  60   expected to happen, tell use what did happen, tell us how you could make it
  61   work another way. Dig around, try out, test. Then include all the tiny bits
  62   and pieces in your report. You will benefit from this yourself, as it will
  63   enable us to help you quicker and more accurately.
  64
  65   Since curl deals with networks, it often helps us if you include a protocol
  66   debug dump with your bug report. The output you get by using the -v or
  67   --trace options.
  68
  69   If curl crashed, causing a core dump (in unix), there is hardly any use to
  70   send that huge file to anyone of us. Unless we have an exact same system
  71   setup as you, we can't do much with it. Instead we ask you to get a stack
  72   trace and send that (much smaller) output to us instead!
  73
  74   The address and how to subscribe to the mailing lists are detailed in the
  75   MANUAL file.
  76
  77 1.4 libcurl problems
  78
  79   First, post all libcurl problems on the curl-library mailing list.
  80
  81   When you've written your own application with libcurl to perform transfers,
  82   it is even more important to be specific and detailed when reporting bugs.
  83
  84   Tell us the libcurl version and your operating system. Tell us the name and
  85   version of all relevant sub-components like for example the SSL library
  86   you're using and what name resolving your libcurl uses. If you use SFTP or
  87   SCP, the libssh2 version is relevant etc.
  88
  89   Showing us a real source code example repeating your problem is the best way
  90   to get our attention and it will greatly increase our chances to understand
  91   your problem and to work on a fix (if we agree it truly is a problem).
  92
  93   Lots of problems that appear to be libcurl problems are actually just abuses
  94   of the libcurl API or other malfunctions in your applications. It is advised
  95   that you run your problematic program using a memory debug tool like
  96   valgrind or similar before you post memory-related or "crashing" problems to
  97   us.
  98
  99 1.5 Who will fix the problems
 100
 101   If the problems or bugs you describe are considered to be bugs, we want to
 102   have the problems fixed.
 103
 104   There are no developers in the curl project that are paid to work on bugs.
 105   All developers that take on reported bugs do this on a voluntary basis. We
 106   do it out of an ambition to keep curl and libcurl excellent products and out
 107   of pride.
 108
 109   But please do not assume that you can just lump over something to us and it
 110   will then magically be fixed after some given time. Most often we need
 111   feedback and help to understand what you've experienced and how to repeat a
 112   problem. Then we may only be able to assist YOU to debug the problem and to
 113   track down the proper fix.
 114
 115   We get reports from many people every month and each report can take a
 116   considerable amount of time to really go to the bottom with.
 117
 118 1.6 How to get a stack trace
 119
 120   First, you must make sure that you compile all sources with -g and that you
 121   don't 'strip' the final executable. Try to avoid optimizing the code as
 122   well, remove -O, -O2 etc from the compiler options.
 123
 124   Run the program until it cores.
 125
 126   Run your debugger on the core file, like '<debugger> curl core'. <debugger>
 127   should be replaced with the name of your debugger, in most cases that will
 128   be 'gdb', but 'dbx' and others also occur.
 129
 130   When the debugger has finished loading the core file and presents you a
 131   prompt, enter 'where' (without the quotes) and press return.
 132
 133   The list that is presented is the stack trace. If everything worked, it is
 134   supposed to contain the chain of functions that were called when curl
 135   crashed. Include the stack trace with your detailed bug report. It'll help a
 136   lot.
 137
 138 1.7 Bugs in libcurl bindings
 139
 140   There will of course pop up bugs in libcurl bindings. You should then
 141   primarily approach the team that works on that particular binding and see
 142   what you can do to help them fix the problem.
 143
 144   If you suspect that the problem exists in the underlying libcurl, then
 145   please convert your program over to plain C and follow the steps outlined
 146   above.