Re: Difference in ln/ln -s semantics

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Vitali Lovich on 2/3/2009 12:30 PM:
> How about for symlinks: "When creating symbolic links, each TARGET path
> will be resolved relative to the parent directory of the symbolic link
> when it is accessed" below the "When creating hard links, each TARGET
> must exist." text.
> 
> Is it too sutble that this may be a problem for relative paths?  "ln"
> man page already contains a link to the symlink man page - but it's
> probably unlikely that someone using the tool is going to bother looking
> at the system call behind it.

How about the following patch?  I've pushed it to the next branch, to make
it easier to review.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkmTpbUACgkQ84KuGfSFAYC9RQCgy2yyUt5mgfu3sHVIuHUSfJmG
no4An0uZPww/cgLMZpuZkp0fcIc2sYSx
=CMlD
-----END PGP SIGNATURE-----

From 022889a4575390b656abf89b0e8f43ef03c1cc00 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Wed, 11 Feb 2009 21:09:09 -0700
Subject: [PATCH] ln: add details to --help text

* src/ln.c (usage): Mention more about symlink properties.
* doc/coreutils.texi (ln invocation): Likewise.
* THANKS: Update.
Reported by Vitali Lovich.

Signed-off-by: Eric Blake <address@hidden>
---
 THANKS             |    1 +
 doc/coreutils.texi |   25 ++++++++++++++++++++++++-
 src/ln.c           |    6 ++++--
 3 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/THANKS b/THANKS
index da1fc15..a3f9801 100644
--- a/THANKS
+++ b/THANKS
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index c3a1164..57497e9 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -8689,9 +8689,32 @@ ln invocation
 reading, writing, and so on) are passed the symbolic link file, the
 kernel automatically @dfn{dereferences} the link and operates on the
 target of the link.  But some operations (e.g., removing) work on the
-link file itself, rather than on its target.  @xref{Symbolic Links,,,
+link file itself, rather than on its target.  The owner, group, and
+mode of a symlink are not significant to file access performed through
+the link.  @xref{Symbolic Links,,,
 libc, The GNU C Library Reference Manual}.

+Symbolic links can contain arbitrary strings; a @dfn{dangling symlink}
+occurs when the string in the symlink does not resolve to a file.
+There are no restrictions against creating dangling symbolic links.
+There are trade-offs to using absolute or relative symlinks.  An
+absolute symlink always points to the same file, even if the directory
+containing the link is moved.  However, if the symlink is visible from
+more than one machine (such as on a networked file system), the file
+pointed to might not always be the same.  A relative symbolic link is
+resolved in relation to the directory that contains the link, and is
+often useful in referring to files on the same device without regards
+to what name that device is mounted on when accessed via networked
+machines.
+
+When creating a relative symlink in a different location than the
+current directory, the resolution of the symlink will be different
+than the resolution of the same string from the current directory.
+Therefore, many users prefer to first change directories to the
+location where the relative symlink will be created, so that
+tab-completion or other file resolution will find the same target as
+what will be placed in the symlink.
+
 The program accepts the following options.  Also see @ref{Common options}.

 @table @samp
diff --git a/src/ln.c b/src/ln.c
index 2dc5628..d0f9266 100644
--- a/src/ln.c
+++ b/src/ln.c
@@ -1,5 +1,5 @@
 /* `ln' program to create links between files.
-   Copyright (C) 1986, 1989-1991, 1995-2008 Free Software Foundation, Inc.
+   Copyright (C) 1986, 1989-1991, 1995-2009 Free Software Foundation, Inc.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -359,7 +359,9 @@ In the 1st form, create a link to TARGET with the name 
LINK_NAME.\n\
 In the 2nd form, create a link to TARGET in the current directory.\n\
 In the 3rd and 4th forms, create links to each TARGET in DIRECTORY.\n\
 Create hard links by default, symbolic links with --symbolic.\n\
-When creating hard links, each TARGET must exist.\n\
+When creating hard links, each TARGET must exist.  Symbolic links\n\
+can hold arbitrary text; if later resolved, a relative link is\n\
+interpreted in relation to its parent directory.\n\
 \n\
 "), stdout);
       fputs (_("\
-- 
1.6.1.2