emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity

misc: Move Documentation to doc

Browse Source 
Signed-off-by: Craig Small <csmall@dropbear.xyz>
This commit is contained in:
Craig Small
2022-08-29 18:38:52 +10:00
parent d78f10cb1e
commit 406b6d311c
8 changed files with 5 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
doc/CodingStyle.md Normal file
View File

@@ -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.

97
doc/FAQ Normal file
View File

@@ -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.

145
doc/TODO Normal file
View File

@@ -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

92
doc/bugs.md Normal file
View File

@@ -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).

85
doc/howto-uClibc-buildroot-compilation.txt Normal file
View File

@@ -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

78
doc/libproc.supp Normal file
View File

@@ -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*
}

21
doc/translations.md Normal file
View File

@@ -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)/