other: move files to Documentation/ directory

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

Documentation/BUGS

@@ -0,0 +1,74 @@
+BUG REPORTS
+
+Please read this file before sending in a bug report or patch.
+
+Also, PLEASE read the documentation first.  90% of the mail I get
+complaining about procps-ng is due to the sender not having read the
+documentation!
+
+
+Where to send
+=============
+Send comments, bug reports, patches, etc., to albert@users.sf.net
+
+
+What to send
+============
+It is much more useful to me if a program really crashes to recompile it
+with make "CFLAGS=-ggdb -O", run it with "gdb prog" and "run" and send
+me a stack trace ('bt' command).  That said, any bug report is still
+better than none.
+
+strace and ltrace output are very helpful:
+
+        strace -o output-file ps --blah
+        bzip2 output-file
+
+I also like "ps --info" output, even if there isn't a ps problem.
+
+Kernel-Dependent Patches
+========================
+If you send me patches which are specific to *running* with a particular
+kernel version of /proc, please condition them with the runtime determined
+variable 'linux_version_code' from libproc/version.c.  It is the same
+number as the macro LINUX_VERSION_CODE for which the kernel /proc fs
+code was compiled.
+
+A macro is provide in libproc/version.h to construct the code from its
+components, e.g.
+  if (linux_version_code < LINUX_VERSION(2,5,41))
+     /* blah blah blah */
+A startup call to set_linux_version may also be necessary.
+
+Of course, if a bug is due to a change in kernel file formats, it would
+be best to first try to generalize the parsing, since the code is then
+more resilient against future change.
+
+Also unified diffs (diff -u) are my preference, context diffs (diff -c )
+are kind of usable, and standard diffs (diff) are more useless than a
+generic text description of what you did.  Just use
+	diff -Naurd oldfile newfile
+or
+	diff -Naurd old-procps-ng-dir new-procps-ng-dir
+to create your diffs and you will make me happy.  Also make sure to
+include a description of what the diff is for or I'm likely to ignore
+it because of general lack of time...
+
+It might be nice to get rid of miscellaneous compiler warnings, but
+don't bend over backwards to do it.
+
+
+Code Structure
+==============
+
+A goal is to encapsulate *all* parsing dependent on /proc
+file formats into the libproc library.  If the API is general enough
+it can hopefully stabilize and then /proc changes might only require
+updating libproc.so.  Beyond that having the set of utilities be simple
+command lines parsers and output formatters and encapsulating all kernel
+divergence in libproc is the way to go.
+
+Hence if you are submitting a new program or are fixing an old one, keep
+in mind that adding files to libproc which encapsulate such things is
+more desirable than patching the actual driver program.  (well, except
+to move it toward the API of the library).

Documentation/CodingStyle

@@ -0,0 +1,101 @@
+If you start a new file, you get to choose the style.
+If you change an existing file, follow the existing style.
+
+Hard tabs are OK, as long as you consider the tab stops to
+be every 8 characters. You can also use 2, 3, or 4 spaces.
+Tabs are kind of yucky, since cut-and-paste mangles them
+sometimes and they make "diff -Naurd old new" output less
+readable.
+
+Spaces within a line don't matter much, and won't be
+considered part of the style. Just make it readable:
+
+if(x){            // OK
+if( x ){           // OK
+if (x) {            // OK
+if(x==y && a==b){     // OK
+if(x == y && a == b){ // poor
+if(x==y&&a==b){       // poor
+
+This is evil:
+
+szWinStallman
+FoulCodingStyle (int iInsanity)
+  {
+     if (iInsanity)
+       {
+          GoHackEmacs () ;
+       }
+          else
+       {
+          SeekHelpForYourLisp () ;
+       }
+  }
+
+
+Curly braces belong at the end of a line. If you must, go ahead
+and make function bodies an exception to that rule. (as Linus does)
+
+Big fprintf() calls and similar go like this:
+
+fprintf(fd, "%d %d %d %d %d %d\n",
+  sdfsdf_sdfsdf + sdfs_iii,     // not an example of good names!
+  iijjij,
+  kjfkkj_sdfssss_sfff,
+  sdflkjfdskj + sdf - sfds,
+  jksss,
+  sfssss + wwwwfwfw
+);
+
+Keep these distinct: NULL, '\0', 0, 0.0
+
+Command-line parsers need to be bomb-proof. It is not acceptable
+to crash due to a messed up command-line. For an option "-x" that
+takes an argument, accept both "-x arg" and "-xarg". Remember to
+support "--" and "--version".
+
+Be extremely careful when handling data from other users.
+For example, it is a security hole if /proc/123/cmdline can
+overflow an array. It is often a security hole if you allow
+non-ASCII characters to be printed. Assuming the console is
+not in UTF-8 mode, all of these are bad: "\b\e\f\n\r\t\v\x9b".
+(the "\x9b" is valid in UTF-8 mode, but equivalent to "\e["
+when not in UTF-8 mode -- which gives control of terminal
+settings) It's best if you consider user-supplied data to
+be unsafe, since this makes for less work in case the code
+ends up needing to run setuid. Termcap data is user-supplied.
+Except for the above security issues, don't bother to check
+for something you can't handle... like printf() failing.
+It is expected that /dev exists and so on.
+
+Remember that a read() may return early, with partial data
+or with -1 and errno set to EINTR. You then must try again.
+
+char:      may be signed or unsigned by default
+int:       always 32-bit
+long long: always 64-bit
+pointer:   either 32-bit or 64-bit
+long:      same size as a pointer
+KLONG:     same size as a pointer or long IN THE KERNEL
+
+Functions used in just one file must be marked static.
+Use the "const" and "restrict" keywords wherever you can.
+
+Put main() at the bottom of a file so you don't need all
+those ugly forward declarations.
+
+Avoid the strcat() function. It is slow. For some odd
+reason, snprintf() is faster than sprintf().
+
+Reuse memory allocations when you can. When using realloc(),
+do your increments by more than one. 25% is a nice amount.
+
+Avoid compile-time choices. They make documentation difficult,
+and they are not friendly to binary distribution.
+
+Write programs that can handle a million processes without
+getting hopelessly slow. Allow for /proc/123/cmdline to
+be at least 128 kB.
+
+The LGPL license is strongly preferred. This allows use of
+the code in the library.

Documentation/FAQ

@@ -0,0 +1,99 @@
+Why does "ps -aux" complain about a bogus '-'?
+
+According to the POSIX and UNIX standards, the above command asks to display
+all processes with a TTY (generally the commands users are running) plus all
+processes owned by a user named "x". If that user doesn't exist, then ps will
+assume you really meant "ps aux". The warning is given to gently break you of a
+habit that will cause you trouble if a user named "x" were created.
+
+
+Why don't I see SMP (per-CPU) stats in top?
+
+You didn't enable it. Press '?' for built-in help or read the man page. Per-CPU
+stats are disabled by default because they take up too much space. Some Linux
+systems have hundreds of CPUs.
+
+
+Why do long usernames get printed as numbers?
+
+The UNIX and POSIX standards require that user names and group names be printed
+as decimal integers when there is not enough room in the column. Truncating the
+names, besides being a violation of the standard, would lead to confusion
+between names like MichelleRichards and MichelleRichardson. The UNIX and POSIX
+way to change column width is to rename the column:
+
+     ps -o pid,user=CumbersomeUserNames -o comm
+
+The easy way is to directly specify the desired width:
+
+     ps -o pid,user:19,comm
+
+
+Why is %CPU underreported for multi-threaded (Java, etc.) apps?
+
+You need to upgrade to the 2.6.10 kernel at least. Older kernels do not provide
+a reasonable way to get this information.
+
+
+Why do ps and top show threads individually?
+
+The 2.4.xx kernel does not provide proper support for grouping threads by
+process. Hacks exist to group them anyway, but such hacks will falsely group
+similar tasks and will fail to group tasks due to race conditions. The hacks
+are also slow. As none of this is acceptable in a critical system tool, task
+grouping is not currently available for the 2.4.xx kernel. The 2.6.xx kernel
+allows for proper thread grouping and reporting. To take advantage of this,
+your programs must use a threading library that features the CLONE_THREAD flag.
+The NPTL pthreads provided by recent glibc releases use CLONE_THREAD.
+
+
+What systems are supported?
+
+Linux 2.4.xx and 2.6.xx are commonly tested and expected to work well. SMP is
+well supported. Multi-node cluster views require a multi-node /proc filesystem;
+without that you will see a single-node view.
+
+
+Where to I send bug reports?
+
+You may use the Debian bug tracking system or send your report to
+procps@freelists.org (no subscription required) instead.
+
+
+Why are there so many procps projects?
+
+The original maintainer seems to have had little time for procps. Whatever his
+reasons, the project didn't get maintained. Starting in 1997, Albert Cahalan
+wrote a new ps program for the package. For the next few years, Albert quietly
+helped the Debian package maintainer fix bugs. In 2001, Rik van Riel decided to
+do something about what appeared to be the lack of a maintainer. He picked up
+the buggy old code in Red Hat's CVS and started adding patches. Meanwhile,
+other people have patched procps in a great many ways.
+
+In 2002, Albert moved procps to http://procps.sourceforge.net. This was done to
+ensure that years of testing and bug fixes would not be lost. The major version
+number was changed to 3, partly to avoid confusing users and partly because the
+top program had been redone.
+
+After development essentially stopped on sourceforge.net, in 2011 the project
+found a new home at http://gitorious.org/procps. This represents the Debian,
+Fedora and openSUSE fork of procps. To avoid confusion and potential name
+clashes the package is now known as procps-ng (next generation), the version
+number was raised to 3.3.0 and the library soname changed to libproc-ng-3.3.0.
+
+
+What is being done to procps-ng at its new home?
+
+All programs are in the process of being modernized, both in terms of coding
+style and supporting documentation. Autotools have been integrated and the
+library API has been expanded with many new fields supported such as control
+groups, supplementary groups, etc. The top program has been rewritten offering
+many new capabilities while providing performance improvements up to 300%.
+
+
+Why does ps get signal 17?
+
+No ps release has ever had this problem. Most likely your system has been
+broken into. You might want to install a more recent version of the OS. If
+you'd rather take your chances, simply upgrade procps.
+

Documentation/TODO

@@ -0,0 +1,151 @@
+-------------------------- general ------------------------
+
+Consider using glibc obstacks for memory allocation.
+
+Implement /usr/proc/bin tools like Solaris has.
+The prstat command is interesting, like top in batch mode.
+SCO has a pstat command.
+
+Don't these really belong in the procps-ng package?
+         killall pstree fuser lsof who
+(they are maintained elsewhere, which causes version problems)
+
+OpenBSD has a pfind command.
+
+Cache results of dev_to_tty.
+
+---------------------- kernel -------------------------
+
+Add an "adopted child" flag to mark processes that are not
+natural children of init. This can make --forest work better.
+
+Supply better data for top's CPU state display. Currently top has
+to subtract old numbers from new numbers and divide that result by
+the number of processors. The kernel won't even supply the number
+of processors in a portable way.
+
+Supply data for the ADDR and JOBC fields.
+
+Support & supply data for SL and RE.
+
+Add a /proc/*/tty symlink to eliminate guessing when /proc/*/fd is
+not accessable.
+
+Add /proc/*/.bindata files to avoid string parsing. It should be an array
+of 64-bit values on all machines. New entries go on the end and obsolete
+ones get filled in with something logical -- entries must never be deleted!
+
+Add all the stuff Solaris has. This would also replace ptrace.
+
+---------------------- watch --------------------------
+
+Tolerate UTF-8.
+
+Tolerate color, bold, underline, etc. #129334
+
+Tolerate stderr.  #420377 #155227 #225549
+
+Tolerate VT100 line-drawing characters. Maybe translate them.
+
+---------------------- w --------------------------
+
+The LOGIN@ column sometimes has a space in it. This makes correct
+scripting difficult.
+
+Time formats are demented.
+
+---------------------- vmstat --------------------------
+
+Extract /proc/diskstats parsing from vmstat into libproc somewhere.
+
+--------------------- libproc ----------------------
+
+Stop storing fields with duplicate info (often different
+units: kB and pages, seconds and jiffies) in the proc_t struct.
+
+Use own readdir code (assembly language) because glibc sucks ass.
+
+---------------------- top -------------------------
+
+Share more stuff with ps.
+
+don't truncate long usernames
+
+have a --config option
+
+---------------- ps for now, maybe move to libproc ------------------
+
+With forest output and a tty named /dev/this_is_my_tty, the position
+of the command name gets messed up. (we print too many spaces) (fixed?)
+
+Fix missing stuff for these formats: FB_j FB_l FB_v HP_f HP_l HP_fl JFMT OL_m
+(jobc,cpu,sl,re,cpu,prmgrp,m_swap,m_share,vm_lib,m_dt)
+Note that "cpu" has two meanings.
+
+Add Beowulf support. This is ugly, since the current patches use a
+daemon to collect info and add a HOST field after the PID field.
+
+Query optimizer, put cheap/required process selection first.
+
+Avoid reading both /proc/*/status and /proc/*/stat.
+
+Support printing the client hostname (the FROM that w(1) uses) in place
+of a pty.
+
+Disambiguate narrow tty info. (/dev/tty7 == /dev/pts/7 now)
+1------8     1--4
+ttyS2        S2
+ttyI31       I31
+pts/7        7        Short form could be /999.
+pts/9999     9999     Short form could just be trunctuated to /999.
+tty7         7        Short form could be vc-7.
+tty63        63       Short form could be vc63.
+
+Internationalization, as specified by XPG3, Volume 1, Commands and Utilities.
+(and suggested by Unix98) LC_TIME affects date format.
+
+----------------------- ps -----------------------
+
+Add an option to select all processes that a user can kill.
+(related to RUID, EUID, tty, etc. -- but maybe ignore root power)
+
+Add a nice display option for killing things.
+ruser,euser,ppid,pid,pmem,stime,args
+
+For RT stuff:
+pid,tid,class,rtprio,ni,pri,psr,pcpu,stat,wchan:14,comm
+
+For job control:
+stat,euid,ruid,tty,tpgid,sess,pgrp,ppid,pid,pcpu,comm
+
+Make the column alignment algorithm support this:
+    FOO BAR
+    8 44444
+    453  45
+    45 2989
+    63666 0
+    34  333
+(useful for the UNIX tty and time values, since the time might look
+like 100-10:40:32 for old processes and the tty might have extra room)
+
+Improve long sort/format specifiers documentation and fill in the missing
+code as much as the kernel can support. Make sure that memory amounts are in
+pages when they should be and in kB when they should be, not backwards.
+
+output encoding: UTF8 --nul --null
+
+Make BSD formats use non-standard BSD time format, at least when it
+doesn't violate the "no whitespace" rule.
+
+Better unmangling of '?' as a tty. The shell destroys '?' when there
+is a filename that matches. If the argument seems like garbage,
+check for a file that might have screwed up the '?'.
+
+If the 'O' option is given something already implied by 'O',
+assume the user wanted a sorting option.
+
+Conflict:
+Digital THREAD is user,pcpu,pri,scnt,wchan,usertime,systime
+AIX     THREAD is uname,pid,ppid,tid,S,C,PRI,scount,WCHAN,F,tty,bnd,comm
+AIX looks like this:
+         USER   PID  PPID  TID S  C PRI SC   WCHAN   FLAG   TTY BND  CMD