Re: [PATCH] getdirentries: Add a simple example rather than just referencing

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

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-kA1LtwSENNE@public.gmane.org>
> ---
> 
> 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-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html