Hi Mark,
On Thu, May 27, 2010 at 1:49 PM, Mark Hills <mark@xxxxxxxxxxx> wrote:
> On Mon, 24 May 2010, Michael Kerrisk wrote:
>
>> Your patches prompted me to add various other pieces to the man page.
>> Your comments welcome, if you have a chance to review.
>
> Sure, no problem.
>
> The extra detail to the descriptions is good, but I have some comments on
> the unmaintained ones:
>
>> .IR ru_ixrss " (unmaintained)"
>> On some systems, this is the integral of the text segment memory consumption,
>> expressed in kilobyte-seconds.
>> .TP
>> .IR ru_idrss " (unmaintained)"
>> On some systems, this is the integral of the data segment memory consumption,
>> expressed in kilobyte-seconds.
>> .TP
>> .IR ru_isrss " (unmaintained)"
>> On some systems, this is the integral of the stack memory consumption,
>> expressed in kilobyte-seconds.
>> .TP
> [...]
>> .IR ru_nswap " (unmaintained)"
>> On some systems, this is the number of swaps out of physical memory.
>> .TP
> [...]
>> .IR ru_msgsnd " (unmaintained)"
>> .\" On FreeBSD 6.2, this appears to measure messages sent on sockets
>> On some systems,
>> this field records the number of messages sent over sockets.
>> .TP
>> .IR ru_msgrcv " (unmaintained)"
>> .\" On FreeBSD 6.2, this appears to measure messages received on sockets
>> On some systems,
>> this field records the number of messages received over sockets.
>> .TP
>> .IR ru_nsignals " (unmaintained)"
>> On some systems, this field records the numner of signals received.
>> .TP
>
> In my changes I decided specifically to leave out the unmaintained fields.
> My reasoning was an assumption that the man page is to document the Linux
> getrusage() call. If something is unimplemented on Linux then a
> explanation of what it does or "appears to" do on another platform is not
> relevant, and will easily be misleading or out of date; that information
> can easily and definitively be found in documentation for the other
> platforms.
>
> Including them has opened a can of worms already: what is the difference
> between messages "sent on" sockets, or "sent over" sockets?
Hmmm -- that's just a language issue.
> There's a typo: "numner".
Thanks.
> Thanks for applying the patches.
I see your point, but on the other hand, people will always ask: why
are those fields there? The text was my attempt to address that
question. But, perhaps you are right. I've commented out my text, and
added a generic statement for each of the fields that it is currently
unused on Linux, and an overall statement about why the unmaintained
fields even appear in the structure.
Cheers,
Michael
--- a/man2/getrusage.2
+++ b/man2/getrusage.2
@@ -36,7 +36,7 @@
.\" document ru_maxrss
.\" 2010-05-24, mtk, enhanced description of various fields
.\"
-.TH GETRUSAGE 2 2010-05-24 "Linux" "Linux Programmer's Manual"
+.TH GETRUSAGE 2 2010-06-14 "Linux" "Linux Programmer's Manual"
.SH NAME
getrusage \- get resource usage
.SH SYNOPSIS
@@ -93,8 +93,11 @@ struct rusage {
.fi
.in
.PP
-Not all fields are completed; unmaintained fields are set to zero by
-the kernel. The fields are interpreted as follows:
+Not all fields are completed;
+unmaintained fields are set to zero by the kernel.
+(The unmaintained fields are provided for compatibility with other systems,
+and because they may one day be supported on Linux.)
+The fields are interpreted as follows:
.TP
.I ru_utime
This is the total amount of time spent executing in user mode,
@@ -115,16 +118,20 @@ this is the resident set size of the largest
child, not the maximum
resident set size of the process tree.
.TP
.IR ru_ixrss " (unmaintained)"
-On some systems, this is the integral of the text segment memory consumption,
-expressed in kilobyte-seconds.
+This field is currently unused on Linux.
+.\" On some systems,
+.\" this is the integral of the text segment memory consumption,
+.\" expressed in kilobyte-seconds.
.TP
.IR ru_idrss " (unmaintained)"
-On some systems, this is the integral of the data segment memory consumption,
-expressed in kilobyte-seconds.
+This field is currently unused on Linux.
+.\" On some systems, this is the integral of the data segment memory
consumption,
+.\" expressed in kilobyte-seconds.
.TP
.IR ru_isrss " (unmaintained)"
-On some systems, this is the integral of the stack memory consumption,
-expressed in kilobyte-seconds.
+This field is currently unused on Linux.
+.\" On some systems, this is the integral of the stack memory consumption,
+.\" expressed in kilobyte-seconds.
.TP
.I ru_minflt
The number of page faults serviced without any I/O activity; here
@@ -135,7 +142,8 @@ the list of pages awaiting reallocation.
The number of page faults serviced that required I/O activity.
.TP
.IR ru_nswap " (unmaintained)"
-On some systems, this is the number of swaps out of physical memory.
+This field is currently unused on Linux.
+.\" On some systems, this is the number of swaps out of physical memory.
.TP
.IR ru_inblock " (since Linux 2.6.22)"
The number of times the file system had to perform input.
@@ -144,17 +152,20 @@ The number of times the file system had to perform input.
The number of times the file system had to perform output.
.TP
.IR ru_msgsnd " (unmaintained)"
+This field is currently unused on Linux.
.\" On FreeBSD 6.2, this appears to measure messages sent over sockets
-On some systems,
-this field records the number of messages sent over sockets.
+.\" On some systems,
+.\" this field records the number of messages sent over sockets.
.TP
.IR ru_msgrcv " (unmaintained)"
+This field is currently unused on Linux.
.\" On FreeBSD 6.2, this appears to measure messages received over sockets
-On some systems,
-this field records the number of messages received over sockets.
+.\" On some systems,
+.\" this field records the number of messages received over sockets.
.TP
.IR ru_nsignals " (unmaintained)"
-On some systems, this field records the number of signals received.
+This field is currently unused on Linux.
+.\" On some systems, this field records the number of signals received.
.TP
.IR ru_nvcsw " (since Linux 2.6)"
The number of times a context switch resulted due to a process
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
