readlink: document portability issue with symlink length

Per comments in areadlink, ERANGE on a too-small buffer is
expected on some platforms; making the readlink module guarantee
GNU behavior of truncated contents is counter-productive, since
we would be duplicating areadlink to learn a-priori how large to
make the buffer, and since truncated contents are not as useful.

* doc/posix-functions/lstat.texi (lstat): Mention that some file
systems have bogus st_size on symlinks, and mention the
areadlink-with-size module.
* doc/posix-functions/fstatat.texi (fstatat): Likewise.
* doc/posix-functions/readlink.texi (readlink): Mention the
areadlink module, and ERANGE failure.
* doc/posix-functions/readlinkat.texi (readlinkat): Likewise.
* tests/test-readlink.c (main): Relax test for AIX, HP-UX.

Signed-off-by: Eric Blake <ebb9@byu.net>

diff --git a/ChangeLog b/ChangeLog
index 9337f56..618f1c9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2009-09-23  Eric Blake  <ebb9@byu.net>
 
+       readlink: document portability issue with symlink length
+       * doc/posix-functions/lstat.texi (lstat): Mention that some file
+       systems have bogus st_size on symlinks, and mention the
+       areadlink-with-size module.
+       * doc/posix-functions/fstatat.texi (fstatat): Likewise.
+       * doc/posix-functions/readlink.texi (readlink): Mention the
+       areadlink module, and ERANGE failure.
+       * doc/posix-functions/readlinkat.texi (readlinkat): Likewise.
+       * tests/test-readlink.c (main): Relax test for AIX, HP-UX.
+
        readlink: fix Solaris 9 bug with trailing slash
        * lib/readlink.c (rpl_readlink): Work around trailing slash bug.
        * m4/readlink.m4 (gl_FUNC_READLINK): Detect the bug.

diff --git a/doc/posix-functions/fstatat.texi b/doc/posix-functions/fstatat.texi
index d1c4c83..b96fc4d 100644 (file)
--- a/doc/posix-functions/fstatat.texi
+++ b/doc/posix-functions/fstatat.texi
@@ -31,4 +31,8 @@ not correctly report the size of files or block devices larger than 2
 GB.  The fix is to use the @code{AC_SYS_LARGEFILE} macro.
 @item
 On Windows platforms (excluding Cygwin), @code{st_ino} is always 0.
+@item
+On some filesystems, @code{st_size} contains bogus information for
+symlinks; use the gnulib module areadlink-with-size for a better way
+to get symlink contents.
 @end itemize

diff --git a/doc/posix-functions/lstat.texi b/doc/posix-functions/lstat.texi
index dbe31f8..328b896 100644 (file)
--- a/doc/posix-functions/lstat.texi
+++ b/doc/posix-functions/lstat.texi
@@ -35,4 +35,8 @@ portably replace @code{stat} via an object-like macro.  Therefore,
 expressions such as @code{(islnk ? lstat : stat) (name, buf)} are not
 portable, and should instead be written @code{islnk ? lstat (name,
 buf) : stat (name, buf)}.
+@item
+On some filesystems, @code{st_size} contains bogus information for
+symlinks; use the gnulib module areadlink-with-size for a better way
+to get symlink contents.
 @end itemize

diff --git a/doc/posix-functions/readlink.texi b/doc/posix-functions/readlink.texi
index 959f62d..b1218f6 100644 (file)
--- a/doc/posix-functions/readlink.texi
+++ b/doc/posix-functions/readlink.texi
@@ -31,4 +31,12 @@ directories, Cygwin sets @code{errno} to @code{ENOENT} or @code{EIO} instead of
 When @code{readlink} is called on a file that is not a symbolic link:
 Irix may set @code{errno} to @code{ENXIO} instead of @code{EINVAL}.  Cygwin
 may set errno to @code{EACCES} instead of @code{EINVAL}.
+@item
+Symlink contents do not always have a trailing null byte, and there is
+no indication if symlink contents were truncated if the return value
+matches the length.  Furthermore, AIX 5.1 and HP-UX 11 set
+@code{errno} to @code{ERANGE} rather than returning truncated
+contents, and Linux sets @code{errno} to @code{EINVAL} if the
+requested length is zero.  Use the gnulib module areadlink for
+improved ability to read symlink contents.
 @end itemize

diff --git a/doc/posix-functions/readlinkat.texi b/doc/posix-functions/readlinkat.texi
index b64b443..65f088f 100644 (file)
--- a/doc/posix-functions/readlinkat.texi
+++ b/doc/posix-functions/readlinkat.texi
@@ -28,4 +28,12 @@ directories, Cygwin sets @code{errno} to @code{ENOENT} or @code{EIO} instead of
 When @code{readlink} is called on a file that is not a symbolic link:
 Irix may set @code{errno} to @code{ENXIO} instead of @code{EINVAL}.  Cygwin
 may set errno to @code{EACCES} instead of @code{EINVAL}.
+@item
+Symlink contents do not always have a trailing null byte, and there is
+no indication if symlink contents were truncated if the return value
+matches the length.  Furthermore, AIX 5.1 and HP-UX 11 set
+@code{errno} to @code{ERANGE} rather than returning truncated
+contents, and Linux sets @code{errno} to @code{EINVAL} if the
+requested length is zero.  Use the gnulib module areadlink for
+improved ability to read symlink contents.
 @end itemize

diff --git a/tests/test-readlink.c b/tests/test-readlink.c
index f0f921e..97a6788 100644 (file)
--- a/tests/test-readlink.c
+++ b/tests/test-readlink.c
@@ -97,10 +97,21 @@ main ()
   {
     size_t len = strlen (BASE "dir");
     /* When passing too small of a buffer, expect the truncated
-       length.  However, a size of 0 is not portable enough to
-       test.  */
-    ASSERT (readlink (BASE "link", buf, 1) == 1);
-    ASSERT (buf[0] == BASE[0]);
+       length, or an ERANGE failure.  However, a size of 0 is not
+       portable enough to test.  */
+    ssize_t result;
+    errno = 0;
+    result = readlink (BASE "link", buf, 1);
+    if (result == -1)
+      {
+       ASSERT (errno == ERANGE);
+       ASSERT (buf[0] == (char) 0xff);
+      }
+    else
+      {
+       ASSERT (result == 1);
+       ASSERT (buf[0] == BASE[0]);
+      }
     ASSERT (buf[1] == (char) 0xff);
     ASSERT (readlink (BASE "link", buf, len) == len);
     ASSERT (strncmp (buf, BASE "dir", len) == 0);