user/procps/BUGS

   1 BUG REPORTS
   2
   3 Please read this file before sending in a bug report or patch.
   4
   5 Also, PLEASE read the documentation first.  90% of the mail I get
   6 complaining about procps is due to the sender not having read the
   7 documentation!
   8
   9
  10 Where to send
  11 =============
  12 Send comments, bug reports, patches, etc., to albert@users.sf.net
  13
  14
  15 What to send
  16 ============
  17 It is much more useful to me if a program really crashes to recompile it
  18 with make "CFLAGS=-ggdb -O", run it with "gdb prog" and "run" and send
  19 me a stack trace ('bt' command).  That said, any bug report is still
  20 better than none.
  21
  22 strace and ltrace output are very helpful:
  23
  24         strace -o output-file ps --blah
  25         bzip2 output-file
  26
  27 I also like "ps --info" output, even if there isn't a ps problem.
  28
  29 Kernel-Dependent Patches
  30 ========================
  31 If you send me patches which are specific to *running* with a particular
  32 kernel version of /proc, please condition them with the runtime determined
  33 variable 'linux_version_code' from libproc/version.c.  It is the same
  34 number as the macro LINUX_VERSION_CODE for which the kernel /proc fs
  35 code was compiled.
  36
  37 A macro is provide in libproc/version.h to construct the code from its
  38 components, e.g.
  39   if (linux_version_code < LINUX_VERSION(2,5,41))
  40      /* blah blah blah */
  41 A startup call to set_linux_version may also be necessary.
  42
  43 Of course, if a bug is due to a change in kernel file formats, it would
  44 be best to first try to generalize the parsing, since the code is then
  45 more resilient against future change.
  46
  47 Also unified diffs (diff -u) are my preference, context diffs (diff -c )
  48 are kind of usable, and standard diffs (diff) are more useless than a
  49 generic text description of what you did.  Just use
  50         diff -Naurd oldfile newfile
  51 or
  52         diff -Naurd old-procps-dir new-procps-dir
  53 to create your diffs and you will make me happy.  Also make sure to
  54 include a description of what the diff is for or I'm likely to ignore
  55 it because of general lack of time...
  56
  57 It might be nice to get rid of miscellaneous compiler warnings, but
  58 don't bend over backwards to do it.
  59
  60
  61 Code Structure
  62 ==============
  63
  64 A goal is to encapsulate *all* parsing dependent on /proc
  65 file formats into the libproc library.  If the API is general enough
  66 it can hopefully stabilize and then /proc changes might only require
  67 updating libproc.so.  Beyond that having the set of utilities be simple
  68 command lines parsers and output formatters and encapsulating all kernel
  69 divergence in libproc is the way to go.
  70
  71 Hence if you are submitting a new program or are fixing an old one, keep
  72 in mind that adding files to libproc which encapsulate such things is
  73 more desirable than patching the actual driver program.  (well, except
  74 to move it toward the API of the library).