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
