misc: Move Documentation to doc

Signed-off-by: Craig Small <csmall@dropbear.xyz>

7 files changed, 545 insertions, 0 deletions

diff --git a/doc/CodingStyle.md b/doc/CodingStyle.md
new file mode 100644
index 0000000..3184e32
--- /dev/null
+++ b/doc/CodingStyle.md
@@ -0,0 +1,27 @@
+Most developers find Linux coding style easy to read, and there is
+really no reason to reinvent this practise, so procps-ng goes along
+with others.
+
+http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/CodingStyle
+
+In addition to Linux coding style this project has few additional
+wishes to contributors.
+
+* Many small patches are favoured over one big. Break down is done on
+  basis of logical functionality; for example #endif mark ups,
+  compiler warning and exit codes fixes all should be individual
+  small patches.
+
+* Use 'FIXME: ' in code comments, manual pages, autotools files,
+  scripts and so on to indicate something is wrong.  The reason we do
+  is as simple as being able to find easily where problem areas are.
+
+* In writing arithmetic comparisons, use "<" and "<=" rather than
+  ">" and ">=".  For some justification, read this:
+  http://thread.gmane.org/gmane.comp.version-control.git/3903/focus=4126
+
+* Be nice to translators. Don't change translatable strings if you
+  can avoid it.  If you must rearrange individual lines (e.g., in
+  multi-line --help strings), extract and create new strings, rather
+  than extracting and moving into existing blocks.  This avoids
+  making unnecessary work for translators.
diff --git a/doc/FAQ b/doc/FAQ
new file mode 100644
index 0000000..b2e5a24
--- /dev/null
+++ b/doc/FAQ
@@ -0,0 +1,97 @@
+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 2.6.xx and 3.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 so-name changed to libprocps.so
+
+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.
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 0000000..2611b28
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,145 @@
+-------------------------- 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 accessible.
+
+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 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
diff --git a/doc/bugs.md b/doc/bugs.md
new file mode 100644
index 0000000..71c48b5
--- /dev/null
+++ b/doc/bugs.md
@@ -0,0 +1,92 @@
+BUG REPORTS
+===========
+
+The following is information for reporting bugs. Please read
+the file as well as the documentation for the relevant program
+before posting. This document is more useful for advanced users
+and the people that package for the distributions.
+
+Also if you are an end-user of the programs and not the packager
+and are using a distribution, check their bug tracker first,
+you may find its a known bug already.
+
+
+Where to send
+-------------
+You can raise issues on the GitLab issues tracker which is
+located at https://gitlab.com/procps-ng/procps/issues You
+will need a GitLab login to do so.
+
+Alternatively send comments, bug reports, patches, etc.
+to the email list procps@freelists.org
+
+What to send
+------------
+It is much more useful to us 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
+
+The output of `ps --info` is often quite useful, even if the problem
+is not with ps itself. A lot of the utilities use the same library.
+
+Merge Requests
+--------------
+Merge requests are fine to use and give a central place for
+everyone involved to have a look. Merge requests are found
+on GitLab at https://gitlab.com/procps-ng/procps/merge_requests
+It is best to follow up your merge request with an email to
+the list saying what you have done.
+
+Patches
+-------
+While merge requests are preferred, patches are also welcome.
+Get latest version of the source from upstream git.
+
+> git clone git@gitlab.com:procps-ng/procps.git
+
+and use `git format-patch` format. It is fine to attach patches as
+compressed tar balls.  When you are about to send very large number
+of patches consider setting up your personal clone, and send a pull
+request.
+
+> git request-pull commit-id \
+>	git://gitorious.org/~yourlogin/procps/your-clone.git
+
+
+Kernel-Dependent Patches
+------------------------
+If you send 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/misc.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.
+
+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).
diff --git a/doc/howto-uClibc-buildroot-compilation.txt b/doc/howto-uClibc-buildroot-compilation.txt
new file mode 100644
index 0000000..0ca9e26
--- /dev/null
+++ b/doc/howto-uClibc-buildroot-compilation.txt
@@ -0,0 +1,85 @@
+From 61d22943abf8a31fbabedba42a13df7417a644e8 Mon Sep 17 00:00:00 2001
+From: Sami Kerola <kerolasa@iki.fi>
+Date: Tue, 17 Apr 2012 22:00:41 +0200
+Subject: [PATCH] New package: procps-ng
+
+This is an example how to add procps-ng to buildroot, to try upstream
+compilation.  I recommend you to 'git am' this patch to upstream
+buildroot git clone.
+
+Once the apply merge is done you need to run 'make menuconfig',
+choose Package Selection for the target --->, [*] Show packages that
+are also provided by busybox && System tools ---> [*] procps-ng.
+If you do not want to configure anything else save, exit and make.
+
+Notice that you almost certainly want to PROCPS_NG_VERSION
+procps-ng.mk file.
+
+Signed-off-by: Sami Kerola <kerolasa@iki.fi>
+---
+ package/Config.in              |    1 +
+ package/procps-ng/Config.in    |    8 ++++++++
+ package/procps-ng/procps-ng.mk |   24 ++++++++++++++++++++++++
+ 3 files changed, 33 insertions(+)
+ create mode 100644 package/procps-ng/Config.in
+ create mode 100644 package/procps-ng/procps-ng.mk
+
+diff --git a/package/Config.in b/package/Config.in
+index 5ae1c81..5fc2d7d 100644
+--- a/package/Config.in
++++ b/package/Config.in
+@@ -583,6 +583,7 @@ source "package/kmod/Config.in"
+ if BR2_PACKAGE_BUSYBOX_SHOW_OTHERS
+ source "package/module-init-tools/Config.in"
+ source "package/procps/Config.in"
++source "package/procps-ng/Config.in"
+ source "package/psmisc/Config.in"
+ source "package/rsyslog/Config.in"
+ source "package/sysklogd/Config.in"
+diff --git a/package/procps-ng/Config.in b/package/procps-ng/Config.in
+new file mode 100644
+index 0000000..deb1569
+--- /dev/null
++++ b/package/procps-ng/Config.in
+@@ -0,0 +1,8 @@
++config BR2_PACKAGE_PROCPS_NG
++	bool "procps-ng"
++	select BR2_PACKAGE_NCURSES
++	help
++	  Standard informational utilities and process-handling tools.
++	  Provides things like kill, ps, uptime, free, top, etc...
++
++	  https://gitorious.org/procps
+diff --git a/package/procps-ng/procps-ng.mk b/package/procps-ng/procps-ng.mk
+new file mode 100644
+index 0000000..0249b07
+--- /dev/null
++++ b/package/procps-ng/procps-ng.mk
+@@ -0,0 +1,24 @@
++#############################################################
++#
++# procps-ng
++#
++#############################################################
++
++PROCPS_NG_VERSION = 8c15d52bfddb582e5a43ce72f3d5d2d98f03b613
++PROCPS_NG_SITE = git://gitorious.org/procps/procps.git
++UTIL_LINUX_AUTORECONF = YES
++
++PROCPS_NG_DEPENDENCIES = ncurses
++
++define PROCPS_NG_AUTOGEN
++	AM_OPTS='--copy' $(@D)/autogen.sh
++endef
++
++PROCPS_NG_POST_PATCH_HOOKS += PROCPS_NG_AUTOGEN
++
++define PROCPS_NG_UNINSTALL_TARGET_CMDS
++	$(MAKE) DESTDIR=$(TARGET_DIR) uninstall -C $(FILE_DIR)
++endef
++
++$(eval $(call AUTOTARGETS))
++$(eval $(call AUTOTARGETS,host))
+--
+1.7.10
+
diff --git a/doc/libproc.supp b/doc/libproc.supp
new file mode 100644
index 0000000..d7f92d3
--- /dev/null
+++ b/doc/libproc.supp
@@ -0,0 +1,78 @@
+#
+#  This is a warning-suppression file for valgrind supplied by libproc
+#  to be used with the option: --suppressions=<path-for>/libproc.supp.
+#
+#  Memory leak warnings will only be encountered when a multi-threaded
+#  program has called the 'procps_pids' interface. That's because this
+#  library employs heap based memory in a thread safe manner. However,
+#  such memory will not be freed until the address space is reclaimed.
+#
+#  When a sibling thread using this 'procps_pids' API ends, or if some
+#  other thread in that address space calls 'pthread_cancel()' on such
+#  a thread, valgrind will warn that some memory is 'definitely lost'.
+#
+#  The majority of warnings depend on the 'pids_item' enumerators that
+#  have been specified using 'procps_pids_new' or 'procps_pids_reset'.
+#
+#  Single-threaded applications will not experience any such warnings.
+#
+
+## always present 'definitely lost' warnings
+#  2 blocks of 128k each
+{
+   HEAP_BASED_TLS_startup
+   Memcheck:Leak
+   ...
+   fun:openproc
+}
+
+## for most of the 'definitely lost' warnings
+#  up to 4 blocks ranging from 1024 to 2048 bytes each
+{
+   HEAP_BASED_TLS_input
+   Memcheck:Leak
+   ...
+   fun:file2str
+}
+
+## additional potential 'definitely lost' warnings
+#  48 bytes for each user
+{
+   HEAP_BASED_TLS_users
+   Memcheck:Leak
+   ...
+   fun:pwcache_get_user
+}
+#  48 bytes for each group
+{
+   HEAP_BASED_TLS_groups
+   Memcheck:Leak
+   ...
+   fun:pwcache_get_group
+}
+#  40 bytes for each tty
+{
+   HEAP_BASED_TLS_terminals
+   Memcheck:Leak
+   ...
+   fun:dev_to_tty
+}
+
+## remaining potential 'definitely lost' warnings
+#  16 bytes + sizeof name for each lxc container
+{
+   HEAP_BASED_TLS_lxc
+   Memcheck:Leak
+   ...
+   fun:lxc_containers
+}
+
+## in case an installed library has been stripped,
+## this will embrace all of the above warning categories
+{
+   HEAP_BASED_TLS_library
+   Memcheck:Leak
+   ...
+   obj:/usr/*lib*/libproc*
+   obj:/usr/local/*lib*/libproc*
+}
diff --git a/doc/translations.md b/doc/translations.md
new file mode 100644
index 0000000..5834078
--- /dev/null
+++ b/doc/translations.md
@@ -0,0 +1,21 @@
+Translations
+============
+
+There is a three-step process for translating man pages. Most
+of the work happens in the po-man directory.
+
+> make -C po-man translate-templates
+Creates the translation templates (the .pot files) for translators
+to use as a base. These, along with the tar file, should be sent
+to the tp-coorindator before release.
+
+> make get-trans
+rsyncs the latest translated (.po) files for both the programs and
+man pages.
+
+> make -C po-man translate-mans
+This is also called in the dist-hook and is where the translation
+magic happens. Take the original man page, the relevant .po file
+and produce a translated man page in that language.
+All of the man pages generated are found in
+po-man/(LANG)/man(SECTION)/