Hello Nicholas, On 11/10/2015 12:13 PM, Nicholas Mc Guire wrote: > The manpage of getdirentries basically just repeats the limited information > from dirent.h and does not explain the content of the returned buffer. Agreed that an example in the page would be helpful. > Further it refers the reader to "the Linux library source code for details", > which is not really that helpful - a simple example including the need to > check available fields, and showing that the returned buffer contains > struct direntries would simplify things. There's a number of problems with the example program, starting with $ cc -Wall h.c h.c: In function ‘main’: h.c:31:17: warning: format ‘%llu’ expects argument of type ‘long long unsigned int’, but argument 3 has type ‘int’ [-Wformat=] ); Also, the program won't compile at all if _DIRENT_HAVE_D_TYPE happens to be undefined. There's also a rendering issue for the code when placed into a man page: the backslashes must be doubled (e.g., "\\n") > Signed-off-by: Nicholas Mc Guire <der.herr@xxxxxxx> > --- > > The ifdef ugliness is intentional as one actually can not write portable > code using getdirenties without checking these macros. > > man3/getdirentries.3 | 45 ++++++++++++++++++++++++++++++++++++++++++++- > 1 file changed, 44 insertions(+), 1 deletion(-) > > diff --git a/man3/getdirentries.3 b/man3/getdirentries.3 > index 2030e3a..962710f 100644 > --- a/man3/getdirentries.3 > +++ b/man3/getdirentries.3 > @@ -60,7 +60,50 @@ If an error occurs, \-1 is returned, and > .I errno > is set appropriately. > .SH ERRORS > -See the Linux library source code for details. > +.PP > +The returned buffer contains the struct dirent of the directory entries. > +The available fields depend on the macros defined in dirent.h and need to be checked > +A basic examples usage (based on libsysio) is shown below > +.SS Program source > +.nf > +#define _BSD_SOURCE > +#include <dirent.h> > +#include <stdio.h> > +#include <sys/types.h> > +#include <sys/stat.h> > +#include <fcntl.h> > + > +#define BUFSIZE 128 This seems on the small side. What if a filename entry is > 128 bytes long? > + > +int > +main(int argc, char *argv[]) > +{ > + ssize_t len; > + int fd; > + off_t base; > + char buf[BUFSIZE]; > + struct dirent *dp; > + > + fd = open(".", O_RDONLY); Better to use argv[1], rather than "." here. > + while ((len = getdirentries(fd, (char *)buf, BUFSIZE, &base)) > 0) { > + dp = (struct dirent *)buf; > + while (len > 0) { > + printf("%s:\n" > +#if defined _DIRENT_HAVE_D_TYPE > + "\t type %llu\n", > +#endif If _DIRENT_HAVE_D_TYPE is not defined, the code won't compile (missing comma in argument list). > + dp->d_name, > +#if defined _DIRENT_HAVE_D_TYPE > + dp->d_type > +#endif > + ); > + len -= dp->d_reclen; > + dp = (struct dirent *)((char *)dp + dp->d_reclen); > + } > + } > + return 0; > +} > +.fi > .SH ATTRIBUTES > For an explanation of the terms used in this section, see > .BR attributes (7). Thanks, 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