From 75b7e407e8d4303930dbfad2df2f36b994f368ed Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 25 Mar 2014 18:08:45 +0200 Subject: [PATCH] Improve doc of file-symlink-p per bug #17073. doc/lispref/files.texi (Kinds of Files): Improve documentation of file-symlink-p. Add cross-references. --- doc/lispref/ChangeLog | 5 ++++ doc/lispref/files.texi | 54 +++++++++++++++++++++++++++++++++++------- 2 files changed, 51 insertions(+), 8 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 3dfc0dffd76..bf3c6f170ea 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-03-25 Eli Zaretskii + + * files.texi (Kinds of Files): Improve documentation of + file-symlink-p. (Bug#17073) Add cross-references. + 2014-03-24 Barry O'Reilly * markers.texi (Moving Marker Positions): The 2014-03-02 doc diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 3818c18f57a..278b49e51e0 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -950,22 +950,26 @@ as directories, symbolic links, and ordinary files. @defun file-symlink-p filename @cindex file symbolic links If the file @var{filename} is a symbolic link, the -@code{file-symlink-p} function returns the (non-recursive) link target -as a string. (Determining the file name that the link points to from -the target is nontrivial.) First, this function recursively follows -symbolic links at all levels of parent directories. - -If the file @var{filename} is not a symbolic link (or there is no such file), +@code{file-symlink-p} function returns its (non-recursive) link target +as a string. (The link target string is not necessarily the full +absolute file name of the target; determining the full file name that +the link points to is nontrivial, see below.) If the leading +directories of @var{filename} include symbolic links, this function +recursively follows them. + +If the file @var{filename} is not a symbolic link, or does not exist, @code{file-symlink-p} returns @code{nil}. +Here are a few examples of using this function: + @example @group -(file-symlink-p "foo") +(file-symlink-p "not-a-symlink") @result{} nil @end group @group (file-symlink-p "sym-link") - @result{} "foo" + @result{} "not-a-symlink" @end group @group (file-symlink-p "sym-link2") @@ -976,6 +980,40 @@ If the file @var{filename} is not a symbolic link (or there is no such file), @result{} "/pub/bin" @end group @end example + +Note that in the third example, the function returned @file{sym-link}, +but did not proceed to resolve it, although that file is itself a +symbolic link. This is what we meant by ``non-recursive'' above---the +process of following the symbolic links does not recurse if the link +target is itself a link. + +The string that this function returns is what is recorded in the +symbolic link; it may or may not include any leading directories. +This function does @emph{not} expand the link target to produce a +fully-qualified file name, and in particular does not use the leading +directories, if any, of the @var{filename} argument if the link target +is not an absolute file name. Here's an example: + +@example +@group +(file-symlink-p "/foo/bar/baz") + @result{} "some-file" +@end group +@end example + +@noindent +Here, although @file{/foo/bar/baz} was given as a fully-qualified file +name, the result is not, and in fact does not have any leading +directories at all. And since @file{some-file} might itself be a +symbolic link, you cannot simply prepend leading directories to it, +nor even naively use @code{expand-file-name} (@pxref{File Name +Expansion}) to produce its absolute file name. + +For this reason, this function is seldom useful if you need to +determine more than just the fact that a file is or isn't a symbolic +link. If you actually need the file name of the link target, use +@code{file-chase-links} or @code{file-truename}, described in +@ref{Truenames}. @end defun The next two functions recursively follow symbolic links at -- 2.39.2