Currently there is not a section 5 manpage for the ps_strings structure. The ps_strings(5) from BSDi's man pages could be used as base. Reference: http://forums.freebsd.org/showthread.php?t=40913.
Created attachment 144666 [details] ps_strings.3 Added initial ps_string.3
I think there are only very few or no applications that should be using ps_strings. To alter ps(1) output, applications should call setproctitle(3); in fact, writing to ps_strings will usually not work because the kernel preferably returns a cached version of the arguments which can be modified by setproctitle(3) (see sysctl kern.ps_arg_cache_limit). Current uses of ps_strings, mostly by debuggers, are to find the auxiliary vector and the signal trampoline on older kernels that lack the KERN_PROC_AUXV and KERN_PROC_SIGTRAMP sysctls. Internal use of ps_strings, such as by setproctitle(3) and libprocstat, need not be documented in a man page. Therefore, I think a ps_strings(3) man page is inappropriate. The comments in <sys/exec.h> say things similar to the proposed man page and should be updated.
For me rewrite from scratch the man page isn't a problem, but I need some guidance. I opened this PR because a user requested it and disappeared since them. Furthermore, Chris Torek didn't review it despite he should be interested in the documentation of ps_strings() If you consider that it's best to close this PR instead wait other feedbacks, please just do it. Everything is in your hands :)
Do the comments in sys/exec.h need to be revised? If they are complete, I think we can close this issue.
Definitely I agree that it's more appropriate or preferible modify sys/exec.h according to the current use of ps_strings.
Created attachment 145049 [details] update comments in <sys/exec.h> I was thinking of changing the comments like this.
Do you think we can add something useful of the discussion [1] as a comment or point out to it? I think it clarifies the matter, if Warren is agree, commit it and close this PR. [1] https://lists.freebsd.org/pipermail/freebsd-hackers/2013-August/043279.html
I'm a little reluctant to remove most of the existing notes. How about adding the new line about preferring the other sysctls first, but leaving the existing comment after it?
Created attachment 145426 [details] update comments in <sys/exec.h> This patch retains more text from the original comment. I do think the text encouraging programs to write to ps_strings should go away.
I think we could add the following comment (written by kib@): "setproctitle() always informs the kernel with sysctl and sets the pointers in ps_strings. kern.proc.args sysctl first tries the p_args, and falls back to reading ps_strings and following the pointers if p_args is NULL."
Created attachment 145522 [details] updated exec.h
(In reply to Warren Block from comment #11) > Created attachment 145522 [details] > updated exec.h Warren, I like your last review. As far as I'm concerned, this request can be marked as resolved. Thanks for work on this :)
Created attachment 145540 [details] update exec.h, second revision Latest revision.
A commit references this bug: Author: wblock Date: Fri Aug 8 22:30:42 UTC 2014 New revision: 269743 URL: http://svnweb.freebsd.org/changeset/base/269743 Log: Update the comments in exec.h with help from jilles. PR: 180970 Submitted by: Carlos Jacobo Puga Medina <cjpugmed@gmail.com> Reviewed by: jilles MFC after: 1 week Changes: head/sys/sys/exec.h
Comments in exec.h updated instead of adding a man page. Thanks!