Re: proposed new module careadlinkat (renamed from breadlinkat)

[Bruno Haible]

Hi Paul,

> +
> +   The PREADLINKAT function specifies how to read links.
> +

This specification is not complete: It does not explain what kind of function
pointer to pass here.

Also, it took me some time to understand how careadlinkatcwd is meant to be
used.

I'm therefore adding a few comments. Hope you can agree with it:


2011-04-09  Bruno Haible  <address@hidden>

        careadlinkat: Clarify specification.
        * lib/careadlinkat.h (careadlinkat): Clarify preadlinkat argument.
        (careadlinkatcwd): Add comment.
        * lib/careadlinkat.c (careadlinkat): Clarify preadlinkat argument.

--- lib/careadlinkat.h.orig     Sat Apr  9 18:33:14 2011
+++ lib/careadlinkat.h  Sat Apr  9 18:33:08 2011
@@ -38,7 +38,10 @@
    buffer managed by ALLOC.  It is the caller's responsibility to free
    the returned value if it is nonnull and is not BUFFER.
 
-   The PREADLINKAT function specifies how to read links.
+   The PREADLINKAT function specifies how to read links.  It operates
+   like POSIX readlinkat()
+   <http://pubs.opengroup.org/onlinepubs/9699919799/functions/readlink.html>
+   but can assume that its first argument is the same as FD.
 
    If successful, return the buffer address; otherwise return NULL and
    set errno.  */
@@ -50,8 +53,10 @@
                                             char *, size_t));
 
 /* Suitable values for careadlinkat's FD and PREADLINKAT arguments,
-   when doing a plain readlink.  */
+   when doing a plain readlink:
+   Pass FD = AT_FDCWD and PREADLINKAT = careadlinkatcwd.  */
 #if HAVE_READLINKAT
+/* AT_FDCWD is declared in <fcntl.h>, readlinkat in <unistd.h>.  */
 # define careadlinkatcwd readlinkat
 #else
 /* Define AT_FDCWD independently, so that the careadlinkat module does
--- lib/careadlinkat.c.orig     Sat Apr  9 18:33:14 2011
+++ lib/careadlinkat.c  Sat Apr  9 18:33:08 2011
@@ -65,7 +65,10 @@
    the returned value if it is nonnull and is not BUFFER.  A null
    ALLOC stands for the standard allocator.
 
-   The PREADLINKAT function specifies how to read links.
+   The PREADLINKAT function specifies how to read links.  It operates
+   like POSIX readlinkat()
+   <http://pubs.opengroup.org/onlinepubs/9699919799/functions/readlink.html>
+   but can assume that its first argument is the same as FD.
 
    If successful, return the buffer address; otherwise return NULL and
    set errno.  */


-- 
In memoriam Georg Elser <http://en.wikipedia.org/wiki/Georg_Elser>