Re: get_phys_pages.3 review

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hi William,

On 05/04/2015 07:11 PM, William Woodruff wrote:
> Just following up on my previous message, here's the updated
> page. If you think it's ready for addition, I'll submit the patch for
> it tonight.

I think you can submit the page, but see one comment below.

> .\" Copyright (c) 2015 William Woodruff (william-d4iiUcZhRQBWk0Htik3J/w@public.gmane.org)
> .\"
> .\" %%%LICENSE_START(VERBATIM)
> .\" Permission is granted to make and distribute verbatim copies of this
> .\" manual provided the copyright notice and this permission notice are
> .\" preserved on all copies.
> .\"
> .\" Permission is granted to copy and distribute modified versions of this
> .\" manual under the conditions for verbatim copying, provided that the
> .\" entire resulting derived work is distributed under the terms of a
> .\" permission notice identical to this one.
> .\"
> .\" Since the Linux kernel and libraries are constantly changing, this
> .\" manual page may be incorrect or out-of-date.  The author(s) assume no
> .\" responsibility for errors or omissions, or for damages resulting from
> .\" the use of the information contained herein.  The author(s) may not
> .\" have taken the same level of care in the production of this manual,
> .\" which is licensed free of charge, as they might when working
> .\" professionally.
> .\"
> .\" Formatted or processed versions of this manual, if unaccompanied by
> .\" the source, must acknowledge the copyright and authors of this work.
> .\" %%%LICENSE_END
> .\"
> .TH GET_PHYS_PAGES 3  2015-03-02 "GNU" "Linux Programmer's Manual"
> .SH NAME
> get_phys_pages, get_avphys_pages \- get total and available physical
> page counts
> .SH SYNOPSIS
> .nf
> .B "#include <sys/sysinfo.h>"
> .sp
> .B long int get_phys_pages(void);
> .B long int get_av_phys_pages(void);
> .SH DESCRIPTION
> The function
> .BR get_phys_pages ()
> returns the total number of physical pages of memory available on the
> system.
> 
> The function
> .BR get_avphys_pages ()
> returns the number of available physical pages of memory available on the
> system.

One too many "available" in that last sentence.

Thanks,

Michael


> .SH RETURN VALUE
> On success, these functions return a nonnegative value as given in
> DESCRIPTION.
> On failure, they return \-1 and set
> .I errno
> to indicate the cause of the error.
> .SH ERRORS
> .TP
> .B ENOSYS
> The system could not provide the required information
> (possibly because the
> .I /proc
> filesystem was not mounted).
> .SH CONFORMING TO
> These functions are GNU extensions.
> .SH NOTES
> These functions obtain the required information by scanning the
> .I MemTotal
> and
> .I MemFree
> fields of
> .IR /proc/meminfo .
> 
> The following
> .BR sysconf (3)
> calls provide a portable means of obtaining the same information as the
> functions described on this page.
> 
> .nf
>     total_pages = sysconf(_SC_PHYS_PAGES);    /* total pages */
>     avl_pages = sysconf(_SC_AVPHYS_PAGES);    /* available pages */
> .fi
> .SH EXAMPLE
> The following example shows how
> .BR get_phys_pages ()
> and
> .BR get_avphys_pages ()
> can be used.
> 
> .nf
> #include <stdio.h>
> #include <stdlib.h>
> #include <sys/sysinfo.h>
> 
> int
> main(int argc, char *argv[])
> {
>     printf("This system has %ld pages of physical memory and "
>             "%ld pages of physical memory available.\\n",
>             get_phys_pages(), get_avphys_pages());
>     exit(EXIT_SUCCESS);
> }
> .fi
> .SH SEE ALSO
> .BR sysconf (3)
> 
> 
> Best,
> William
> 
> On 05/04/2015 09:58 AM, William Woodruff wrote:
>> Hi Michael, William,
>>
>> On 05/04/2015 09:52 AM, Michael Kerrisk (man-pages) wrote:
>>> Hi William,
>>>
>>> On 05/04/2015 02:58 PM, J William Piggott wrote:
>>>> On 05/04/2015 04:08 AM, Michael Kerrisk (man-pages) wrote:
>>>>> Hello William,
>>>>>
>>>>> On 05/03/2015 11:06 PM, William Woodruff wrote:
>>>>
>>>>
>>>>>> returns the total number of physical pages of memory available on the
>>>>>> system.
>>>>>> .sp
>>>>>
>>>>> No need for .sp here. Just use a blank line for the para break.
>>>>
>>>> This is Groff specific behavior. From roff(7):
>>>>  ·      Never include empty or blank lines in a roff document.
>>>
>>> I'm not sure whether that text applies or not. But in any case,
>>> we've got hundreds of pages that happily use blank lines.
>>> If you mist, you can instead use ".PP", but ".sp" seems
>>> wrong to me.
>>
>> I'll follow your advice here. I've seen the rule about never using
>> blank lines in groff, but if other pages do it, I'll assume the behavior
>> is reasonable.
>>
>> Best,
>> William Woodruff
>>
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html