diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CodingStyle.md | 27 | ||||
| -rw-r--r-- | doc/FAQ | 97 | ||||
| -rw-r--r-- | doc/TODO | 145 | ||||
| -rw-r--r-- | doc/bugs.md | 92 | ||||
| -rw-r--r-- | doc/libproc.supp | 78 |
5 files changed, 439 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. @@ -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/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* +} |