procps 010114

ps/HACKING

@@ -0,0 +1,53 @@
+Warning:
+
+This code must corrctly handle lots of picky little details to meet
+the Unix98 standard while simultaneously being as compatible as
+possible with the original Linux ps. Don't "fix" something without
+considering the impact on all the special-case code. For example,
+the "tty" format _must_ use "TT" as the header, even though the SysV
+output formats _must_ use "TTY".
+
+File overview:
+
+display.c     main(), debug code, iterates over processes
+escape.c      Does stuff like \202 and < to command and environment.
+global.c      Data + code to init it.
+help.c        Help message.
+output.c      Giant tables and lots of output functions.
+parser.c      Initial command parsing.
+select.c      want_this_proc() checks a process against flags & lists
+sortformat.c  Parses sort & format specifier lists. Picks output format.
+stacktrace.c  Debug code, not normally used.
+../proc/*     Library used to gather data.
+regression    Regression tests that ought to be run.
+common.h      Lots of interesting stuff.
+Makefile      Makefile
+p             Script used to test ps when the library is not installed.
+utf           Empty file used to test "ps ut?" unmangling behavior.
+ps.1          Man page.
+
+Compiling:
+
+Whatever you do, don't trust the Makefiles. They are severely broken.
+You can touch top.h and top won't be recompiled, or you can change
+library files and discover that the library and programs won't be
+recompiled.
+
+Operation:
+
+Unless the personality forces BSD parsing, parser.c tries to parse the
+command line as a mixed BSD+SysV+Gnu mess. On failure, BSD parsing is
+attempted. If BSD parsing fails _after_ SysV parsing has been attempted,
+the error message comes from the original SysV parse.
+
+Control goes to sortformat.c, which must pick apart ambiguous options
+like "O". Failure can reset the whole program and set PER_FORCE_BSD,
+which means a second trip through parser.c and sortformat.c.
+
+The choice of output format happens in sortformat.c. There is a switch()
+with all the valid format_flags combinations. The SysV and default
+options are NULL (unless overridden by personality), which causes a
+trip through SysV output format generation hackery. Note that the
+default format always goes through there, even if it is for BSD.
+Formats that came from the switch() (generally BSD, plus overrides)
+get mangled a bit to support various SysV output modifiers.