careadlinkat: Clarify specification.

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

diff --git a/ChangeLog b/ChangeLog
index af612efa9612e57f5b8b1fd9fb074e4707121b05..589f7ee0a8878a298921ec39087b7f466de8fa0d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2011-04-09  Bruno Haible  <bruno@clisp.org>
+
+       careadlinkat: Clarify specification.
+       * lib/careadlinkat.h (careadlinkat): Clarify preadlinkat argument.
+       (careadlinkatcwd): Add comment.
+       * lib/careadlinkat.c (careadlinkat): Clarify preadlinkat argument.
+
 2011-04-09  Bruno Haible  <bruno@clisp.org>
 
        areadlinkat: Avoid link error on many platforms.

diff --git a/lib/careadlinkat.c b/lib/careadlinkat.c
index 7a7806d121c60cbd731ebe9842660f5f6fa741db..01883db9ce5f4084858b63b2f6c56bfa5200a986 100644 (file)
--- a/lib/careadlinkat.c
+++ b/lib/careadlinkat.c
@@ -65,7 +65,10 @@ careadlinkatcwd (int fd, char const *filename, char *buffer,
    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.  */

diff --git a/lib/careadlinkat.h b/lib/careadlinkat.h
index be8670f2c9d8c4ab6307dd44dd48108f1839eff0..4f0184bbc333796fccd507aaf0364d8bb2856921 100644 (file)
--- a/lib/careadlinkat.h
+++ b/lib/careadlinkat.h
@@ -38,7 +38,10 @@ struct allocator;
    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 *careadlinkat (int fd, char const *filename,
                                             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