Date: 14 Oct 2002 20:32:17 -0700 From: "Gary W. Swearingen" <swear@attbi.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/44074: ln(1) manual clarifications [patch] Message-ID: <gk7kgk8ji6.kgk@localhost.localdomain>
next in thread | raw e-mail | index | archive | help
>Number: 44074
>Category: docs
>Synopsis: ln(1) manual clarifications [patch]
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Mon Oct 14 20:30:02 PDT 2002
>Closed-Date:
>Last-Modified:
>Originator: Gary W. Swearingen
>Release: FreeBSD 4.7-STABLE i386
>Organization:
none
>Environment:
n/a
================
>Description:
The "ln" manual is confusing. This was cause for a recent -questions
thread on the subject where that sentiment was confirmed by several
people. Here are some problems:
1) Lots of readers aren't familiar with its use of "target".
2) The "ls -l" output shows an arrow coming out of the target instead
of the more natural direction. This is not a problem with "ls", but
a problem with "ln" argument naming.
3) Code within the "ln" program itself calls the other argument the
"target". I say this only to provide some evidence for the manual's
confused naming.
4) It's not intuitive that the "source" should be the source of the
link (ie, the source of the "arrow") or the source of data when the
linked file is accessed -- opposite senses.
5) The seemingly arbitrary assignment of the terms "source file" and
"target file" to the arguments makes their order hard to remember.
6) The order of the two arguments is opposite from their order when
output by "ls -l". This is not necessarily bad, but it makes things
harder to remember and makes it important that the manual help readers
remember the correct order. Good terms and naming is important.
7) The "apropos" string in the "Name" section doesn't contain the
terms "symbolic", "soft", "hard", and those followed by "link",
which are likely to be searched for by apropos(1) users.
8) The last sentence of the first paragraph is more noise than help.
9) Soft links are much more commonly called that than the only term used
by the manual, "symbolic links". The use of "soft links" is better, not
only because it recognizes the more common usage, but becase it is two
fewer syllables and is a more natural antonym for "hard links". It
probably also makes more sense to most people as soft links seem softer
than hard links, but no more symbolic than hard links.
================
>How-To-Repeat:
n/a
================
>Fix:
1) The names of the soft link command arguments (eg, in the synopsis)
are changed to make clear what purpose the arguments serve and to make
the command read naturally as a command to the system.
ln to_filename from_filename
That is, "link to [first] file from [second] file".
The terms seem less arbitrary and are thus more easily remembered than
the "ln"-peculiar meanings of "source" and "target".
Note that during discussion, it seemed clear to me that any arugment
name which contained some form of the word "link" (as then proposed by
me and others) caused problems for some people. The proposed names
leave the word only in the command name where it belongs.
2) The names of the hard link command arguments are augmented to
emphasize two things to aid the memory: A) the file named by the first
argument must pre-exist. B) The command is not really creating
something called a link which sounds like somthing different that the
pre-existing file, but is just creating an alternate name (directory
entry) for the file named by the first arg.
link to_existing_filename from_alternate_filename
That is "link to existing file from alternate file".
3) The new synopsis looks like this:
ln [-fhinsv] to_filename [from_filename]
ln [-fhinsv] to_filename ... dir_filename
link to_existing_filename from_alternate_filename
Note that "filename" in the synopses could be "file" to make them read
even better, but it is better that the arguments retain their essential
descriptive power as names of filenames; they are not names of files.
This is partly because the objects being manipulated are directory
"filename" entries, not files which may or may not exist; in fact, the
filenames for files and links may contain arbritrary strings (like
directory entries created by touch(1)) and never name files at all.
It's also just generally good practice to name a filename as some kind
of filename and not as some kind of file, which it is not.
4) The description section's use of "source file" and "target file"
very-much echo the names of the arguments and so they are easily
replaced by new terms, "to filename" and "from filename". Some other
description is touched up to improve clarity.
5) Change "symbolic" to "soft" and add a note about the alternative
terms "symbolic link" and "symlink".
[.\" $FreeBSD: src/bin/ln/ln.1,v 1.11.2.7 2002/08/19 08:14:22 tjr Exp $]
--- /tmp/ln..orig.1 Sun Oct 13 17:33:39 2002
+++ /tmp/ln.1 Mon Oct 14 19:42:12 2002
@@ -41,38 +41,46 @@
.Sh NAME
.Nm ln ,
.Nm link
-.Nd make links
+.Nd make soft links (symbolic links, symlinks) and hard links
.Sh SYNOPSIS
.Nm
.Op Fl fhinsv
-.Ar source_file
-.Op Ar target_file
+.Ar to_filename
+.Op Ar from_filename
.Nm
.Op Fl fhinsv
-.Ar source_file ...
-.Ar target_dir
+.Ar to_filename ...
+.Ar dir_filename
.Nm link
-.Ar source_file Ar target_file
+.Ar to_existing_filename Ar from_alternate_filename
.Sh DESCRIPTION
The
.Nm
-utility creates a new directory entry (linked file) which has the
-same modes as the original file.
-It is useful for maintaining multiple copies of a file in many places
-at once without using up storage for the
-.Dq copies ;
-instead, a link
-.Dq points
-to the original copy.
-There are two types of links; hard links and symbolic links.
-How a link
-.Dq points
-to a file is one of the differences between a hard and symbolic link.
+utility creates a new filesystem entry which can refer to an existing file
+.Pq or multiple such entries with the second form .
+It is useful for maintaining multiple virtual copies of a file in many places
+while using filesystem storage for only one file.
+Two types of links may be made:
+.Nm ln
+can make
+.Em soft links
+or
+.Em hard links ,
+while
+.Nm link
+can make only hard links.
+Note that soft links are also called
+.Em symbolic links
+and
+.Em symlinks .
+The two types are described following the option descriptions.
.Pp
The options are as follows:
.Bl -tag -width flag
.It Fl f
-If the target file already exists,
+If the
+.Qq from
+file already exists,
then unlink it so that the link may occur.
(The
.Fl f
@@ -81,21 +89,25 @@
options.)
.It Fl h
If the
-.Ar target_file
+.Ar from_filename
or
-.Ar target_dir
-is a symbolic link, do not follow it. This is most useful with the
+.Ar dir_filename
+is a soft link, do not follow it. This is most useful with the
.Fl f
-option, to replace a symlink which may point to a directory.
+option, to replace a soft link which may point to a directory.
.It Fl i
Cause
.Nm
-to write a prompt to standard error if the target file exists.
+to write a prompt to standard error if the
+.Qq from
+file exists.
If the response from the standard input begins with the character
.Sq Li y
or
.Sq Li Y ,
-then unlink the target file so that the link may occur.
+then unlink the
+.Qq from
+file so that the link may occur.
Otherwise, do not attempt the link.
(The
.Fl i
@@ -109,7 +121,7 @@
.Nm
implementations.
.It Fl s
-Create a symbolic link.
+Create a soft link.
.It Fl v
Cause
.Nm
@@ -118,47 +130,50 @@
.Pp
By default,
.Nm
-makes
-.Em hard
-links.
-A hard link to a file is indistinguishable from the original directory entry;
+makes hard links.
+A hard link to a file is indistinguishable from the original filesystem entry;
any changes to a file are effectively independent of the name used to reference
the file.
+Unlike with soft links,
+both old and new filesystem entries become links to each other
+.Pq and to other files to which either is hard linked .
Hard links may not normally refer to directories and may not span filesystems.
.Pp
-A symbolic link contains the name of the file to
+A soft link contains the name of the file to
which it is linked. The referenced file is used when an
.Xr open 2
operation is performed on the link.
A
.Xr stat 2
-on a symbolic link will return the linked-to file; an
+on a soft link will return the linked-to file; an
.Xr lstat 2
must be done to obtain information about the link.
The
.Xr readlink 2
-call may be used to read the contents of a symbolic link.
-Symbolic links may span filesystems and may refer to directories.
+call may be used to read the contents of a soft link.
+Soft links may span filesystems and may refer to directories.
.Pp
Given one or two arguments,
.Nm
creates a link to an existing file
-.Ar source_file .
+.Ar to_filename .
If
-.Ar target_file
+.Ar from_filename
is given, the link has that name;
-.Ar target_file
+.Ar from_filename
may also be a directory in which to place the link;
otherwise it is placed in the current directory.
If only the directory is specified, the link will be made
to the last component of
-.Ar source_file .
+.Ar to_filename .
.Pp
Given more than two arguments,
.Nm
makes links in
-.Ar target_dir
-to all the named source files.
+.Ar dir_filename
+to all the named
+.Qq to
+files.
The links made will have the same name as the files being linked to.
.Pp
When the utility is called as
@@ -169,6 +184,16 @@
which performs a
.Xr link 2
operation using the two passed arguments.
+.Sh NOTES
+Soft links require careful use to ensure that the
+.Qq to
+filename is used rather than the
+.Qq from
+filename, and vice-versa.
+Their handling by programs is not completely standardized.
+Some often-followed conventions, notable exceptions,
+and related discussion may be found in
+.Xr symlink 7 .
.Sh SEE ALSO
.Xr link 2 ,
.Xr lstat 2 ,
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?gk7kgk8ji6.kgk>