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

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

[Nicholas Mc Guire]

The manpage of getdirentries basically just repeats the limited information
from dirent.h and does not explain the content of the returned buffer.

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.

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
+
+int
+main(int argc, char *argv[])
+{
+    ssize_t len;
+    int fd;
+    off_t base;
+    char buf[BUFSIZE];
+    struct dirent *dp;
+
+    fd = open(".", O_RDONLY);
+    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
+                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).
-- 
2.1.4

--
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

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

[Michael Kerrisk (man-pages)]

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

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

[Nicholas Mc Guire]

On Fri, Dec 11, 2015 at 07:52:27PM +0100, Michael Kerrisk (man-pages) wrote:
> 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")
>
thanks for the feedback - looks like this needs some rework - will go 
fix things up and try a second - hopefully more useful version.

thx!
hofrat
--
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