Date: 02 Feb 2003 12:31:45 -0800 From: "Gary W. Swearingen" <swear@attbi.com> To: FreeBSD-gnats-submit@FreeBSD.org Cc: Giorgos Keramidas <keramida@ceid.upatras.gr>, Adam Weinberger <adam@vectors.cx>, Oliver Fromme <olli@secnetix.de> Subject: docs/47818: ln(1) manpage is confusing Message-ID: <w2isw2ifv2.sw2@localhost.localdomain>
next in thread | raw e-mail | index | archive | help
>Number: 47818
>Category: docs
>Synopsis: ln(1) manpage is confusing
>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: Sun Feb 02 12:40:13 PST 2003
>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) Many newbies aren't familiar with its use of "target", or even with
the more common use of the term.
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" misnaming the argument.
3) The other argument is called "target" by code within the "ln" program
itself and by POSIX docs.
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. Better not use the term.
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 "ls -l" command shows an arrow coming out of the "target", using
the old ln(1)'s jargon. Arrows should go into targets. Better yet,
keep them in their quiver. (I.e, don't use the esoteric term.)
8) The "apropos" string in the "Name" section doesn't contain the
terms "symbolic", "soft", "hard", or the same followed by "link",
all of which are likely to be searched for by apropos(1) users.
9) The last sentence of the first paragraph is more noise than help.
10) The -h description is a little confusing about how a "target_file"
can point to a directory or how such a link could be followed by ln.
11) The beginning of the description doesn't mention the "link" command.
12) The descriptions could be better organized and otherwise improved.
================
>How-To-Repeat:
n/a
================
>Fix:
=========================
1) The names of the 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". Of course, with
-s, to_filename can be any string and need not refer to a file, but that
is a detail better left for the description instead of using an esoteric
term like "target" to refer also to an existing filename (without -s).
The terms seem less arbitrary than the ln(1)-peculiar meanings of
"source" and "target", and are thus more easily remembered.
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 is unconfusing.
2) The new synopsis looks like this:
ln [-fhinsv] to_filename {... directory_name | [from_filename]}
link to_filename {directory_name | from_filename}
Note that "filename" is used in the synopses because the argument
specifies a filename, but not necessarily a file; with -s, the filename
need not refer to a file; if may refer to a directory or to nothing.
3) 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".
4) Separating the hard and soft link cases was considered, but having
five synopsis lines and using more specific argument names (which has
its benefits), looked messy/confusing/redundant and gave too much to
decypher and think about.
5) Some other descriptions are reworked to improve clarity.
Preview results of this patch with something like this:
zcat /usr/share/man/man1/ln.1.gz >/tmp/ln.1
patch -s /tmp/ln.1 <this message>
groff -mandoc -Tascii /tmp/ln.1 | less
Patch this:
[.\" $FreeBSD: src/bin/ln/ln.1,v 1.11.2.7 2002/08/19 08:14:22 tjr Exp $]
with this:
--- /pr/work/ln..orig.1 Tue Jan 14 11:29:50 2003
+++ /pr/work/ln.1 Sun Feb 2 11:20:32 2003
@@ -41,65 +41,85 @@
.Sh NAME
.Nm ln ,
.Nm link
-.Nd make links
+.Nd make hard links and symbolic links (symlinks, soft links)
.Sh SYNOPSIS
.Nm
.Op Fl fhinsv
-.Ar source_file
-.Op Ar target_file
-.Nm
-.Op Fl fhinsv
-.Ar source_file ...
-.Ar target_dir
+.Ar to_filename Brq ... Ar directory_name | Op Ar from_filename
.Nm link
-.Ar source_file Ar target_file
+.Ar to_filename Brq Ar directory_name | Ar from_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.
-.Pp
-The options are as follows:
-.Bl -tag -width flag
+command creates new directory entries
+which generally refer to existing files
+so that each file may be accessed by another filename,
+possibly in another directory or filesystem.
+.\"so that multiple virtual copies of a file can exist
+.\"while using storage for only one file.
+The
+.Nm link
+command is equivalent to
+.Nm ,
+except that it must have exactly two arguments and no options;
+therefore, it is not described further.
+.Pp
+Two types of links may be created:
+.Em hard links
+by default, and
+.Em symbolic links
+when the
+.Fl s
+option is used.
+Symbolic links are often called
+.Em symlinks
+or sometimes
+.Em soft links .
+The two types are described following these option descriptions
+(in which the
+.Qq from
+file (i.e., link) to be created can be
+.Ar from_filename
+or a file in the
+.Ar directory_name
+directory):
+.Bl -tag -width ".Fl f"
.It Fl f
-If the target file already exists,
-then unlink it so that the link may occur.
+If the
+.Qq from
+file already exists, then replace it.
(The
.Fl f
-option overrides any previous
+option cancels any previous
.Fl i
options.)
.It Fl h
-If the
-.Ar target_file
-or
-.Ar target_dir
-is a symbolic link, do not follow it. This is most useful with the
+If
+.Ar directory_name
+is a symlink to a directory, do not follow it. This is useful with the
.Fl f
-option, to replace a symlink which may point to a directory.
+option, to replace the symlink.
+(By definition,
+.Ar from_filename
+is a file or a symlink to a file, which is never followed by
+.Nm . )
.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 remove the
+.Qq from
+file so that the link may occur.
Otherwise, do not attempt the link.
(The
.Fl i
-option overrides any previous
+option cancels any previous
.Fl f
options.)
.It Fl n
@@ -109,69 +129,93 @@
.Nm
implementations.
.It Fl s
-Create a symbolic link.
+Create a symlink, instead of a hard link.
.It Fl v
Cause
.Nm
to be verbose, showing files as they are processed.
.El
.Pp
-By default,
-.Nm
-makes
-.Em hard
-links.
-A hard link to a file is indistinguishable from the original directory entry;
-any changes to a file are effectively independent of the name used to reference
-the file.
-Hard links may not normally refer to directories and may not span filesystems.
+Hard links to a file are indistinguishable from the file and from each other,
+except for the filenames;
+in fact, each file in a filesystem appears as one or more hard link
+directory entries by which the file's data may be accessed.
+All of a file's hard links have the same file owner, group, modes, and flags,
+and changes made to one effect them all identically,
+except that removing one hard link leaves the others uneffected
+until the last hard link is removed, removing the file's data too.
+A hard link cannot be created for a file on another filesystem nor (with
+.Nm )
+for a directory.
+(But note that the
+.Qq \&.
+and
+.Qq \&..
+directories appear as hard links.)
.Pp
-A symbolic link contains the name of the file to
-which it is linked. The referenced file is used when an
+Symlinks contain the filename of a directory or file
+which may be on any filesystem (or which may not exist,
+a feature which is sometimes utilized
+to store miscellaneous data in a directory entry).
+Symlinks to one file may have different owners, groups, modes, and flags,
+and are not effected by changes or removal of the file or other symlinks.
+.Ss "Command Forms"
+.Bl -tag -width ""
+.It Nm Ar to_filename
+That creates a link to
+.Ar to_filename
+from
+.Ar basename ,
+where the latter is the base name
+.Xr ( basename 1 )
+of
+.Ar to_filename .
+.It Nm Ar to_filename Ar from_filename
+That creates a link to
+.Ar to_filename
+from
+.Ar from_filename .
+.It Nm Ar to_filename Ar ... Ar directory_name
+That create links to one or more instances of
+.Ar to_filename
+from one or more corresponding instances of
+.Ar directory_name/basename
+where
+.Ar basename
+is the base name
+.Xr ( basename 1 )
+of the corresponding
+.Ar to_filename .
+.El
+.Sh "NOTES"
+The handling of symlinks by other programs is not well standardized
+and tends to be poorly documented for seldom-used cases;
+e.g., some follow the symlink if its name is followed by
+.Qq / .
+See the
+.Xr symlink 7
+manpage for some often-followed conventions,
+notable exceptions, and related discussion.
+.Pp
+Hard links are created with
+.Xr link 2 .
+Symlinks are created with
+.Xr symlink 2 .
+When used on symlinks, the
.Xr open 2
-operation is performed on the link.
-A
+and
.Xr stat 2
-on a symbolic link will return the linked-to file; an
+functions operate on the linked-to file, while
.Xr lstat 2
-must be done to obtain information about the link.
+will access information about the symlink.
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.
-.Pp
-Given one or two arguments,
-.Nm
-creates a link to an existing file
-.Ar source_file .
-If
-.Ar target_file
-is given, the link has that name;
-.Ar target_file
-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 .
-.Pp
-Given more than two arguments,
-.Nm
-makes links in
-.Ar target_dir
-to all the named source files.
-The links made will have the same name as the files being linked to.
-.Pp
-When the utility is called as
-.Nm link ,
-exactly two arguments must be supplied,
-neither of which may specify a directory.
-No options may be supplied in this simple mode of operation,
-which performs a
-.Xr link 2
-operation using the two passed arguments.
+call may be used to read the contents of a symlink.
.Sh SEE ALSO
+.Xr basename 1 ,
.Xr link 2 ,
.Xr lstat 2 ,
+.Xr open 2 ,
.Xr readlink 2 ,
.Xr stat 2 ,
.Xr symlink 2 ,
@@ -183,17 +227,17 @@
.Fl n
and
.Fl v
-options are non-standard and their use in scripts is not recommended.
+options are non-standard and their omission from scripts is recommended.
They are provided solely for compatibility with other
.Nm
implementations.
.Sh STANDARDS
The
.Nm
-utility conforms to
+command conforms to
.St -p1003.2-92 .
.Pp
-The simplified
+The
.Nm link
command conforms to
.St -susv2 .
>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?w2isw2ifv2.sw2>