diff options
author | Eric Blake <ebb9@byu.net> | 2009-09-21 14:40:20 -0600 |
---|---|---|
committer | Eric Blake <ebb9@byu.net> | 2009-09-23 05:40:55 -0600 |
commit | 0510d19e64a0c3cfdd7ebe31866be9b45229590a (patch) | |
tree | fc5295aa5754612bdf8a5274f7d60816acee1d32 /doc | |
parent | 5835d9b52879c334f16e747c54be8ec9c62e8536 (diff) | |
download | gnulib-0510d19e64a0c3cfdd7ebe31866be9b45229590a.tar.gz |
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>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/posix-functions/fstatat.texi | 4 | ||||
-rw-r--r-- | doc/posix-functions/lstat.texi | 4 | ||||
-rw-r--r-- | doc/posix-functions/readlink.texi | 8 | ||||
-rw-r--r-- | doc/posix-functions/readlinkat.texi | 8 |
4 files changed, 24 insertions, 0 deletions
diff --git a/doc/posix-functions/fstatat.texi b/doc/posix-functions/fstatat.texi index d1c4c83419..b96fc4d54e 100644 --- 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 dbe31f8636..328b896c90 100644 --- 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 959f62d7a3..b1218f6c26 100644 --- 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 b64b443fd7..65f088fa59 100644 --- 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 |