Hello William, On 05/03/2015 11:06 PM, William Woodruff wrote: > Hello all, > > I've drafted a man page for two glib functions that haven't been > documented by the man-pages project yet: get_phys_pages(3) and > get_avphys_pages(3). > > This is my first whole file contribution, so I was hoping I could > get some suggestions/pointers before submitting the actual patch :). > > I based it largely on get_nprocs(3) manual page. Thanks for tackling this. Some comments below. > Copied below: > > .\" Copyright (c) 2015 William Woodruff (william@xxxxxxxxxxxx) > .\" > .\" %%%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. > .sp No need for .sp here. Just use a blank line for the para break. > The function > .BR get_avphys_pages () > returns the number of available physical pages of memory available on the > system. > .SH RETURN VALUE > As given in DESCRIPTION. Change this to: [[ 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. ]] Taking a look at the glibc source reveals the following possible errno value: [[ .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 I think it might also be useful to note some details about the implementation here, since it relies on /proc, which may not be available in some unusual configurations. How about this paragraph, to give the reader a clue: [[ These functions obtain the required information by scanning the .I MemTotal and .I MemFree fields of the file .IR /proc/meminfo . ]] > The following > .BR sysconf (3) > calls make use of the functions documented on this page to return the same > information. It's good that you add this piece, but I think the above text could be recast to give the reader an important hint: [[ The following .BR sysconf (3) provide a portable means of obtaining the same information as the functions described on this page. ]] > .sp Use a blank line here, not ".sp" > .nf > total_pages = sysconf(_SC_PHYS_PAGES); /* total pages of memory */ > avl_pages = sysconf(_SC_AVPHYS_PAGES); /* available pages of memory*/ > .fi The two code lines above render wider than 80 characters. Best to shorten the comments by removing the "of memory" in both lines. > .SH EXAMPLE > The following example shows how > .BR get_phys_pages () > and > .BR get_avphys_pages () > can be used. > .sp > .nf > #include <stdio.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()); > return 0; I prefer exit(EXIT_SUCCESS); here, in which case you'll also need to include <stdlib.h>. > } > .fi Add: [[ .SH SEE ALSO .BR sysconf (3) ]] Cheers, Michael -- 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html