Bug 194308

I don't think the terminology being used could be more confusing unless someone worked at it.  I know that I don't use ln enough for the calling sequence to stick in my mind, so I always have to go research it elsewhere because if I read the man page I know less when I'm done than when I started.

My proposed rewrite (details may be incorrect because I *really* cannot understand it as written and haven't the time to experiment)

SYNOPSIS
     ln	[-L | -P | -s [-F]] [-f	| -iw] [-hnv] real_file [new_alias]
     ln [options] real_file0 ... real_fileN dir_name
     link (no options allowed) real_file new_hard_alias

DESCRIPTION
The ln utility allows you to create aliased links to a file or a directory. ("Alias" here does not refer to the aliases in, e.g., csh, though they serve a similar purpose)  

Aliases are useful for 2 main purposes:  (a) accessing some file or directory from multiple locations; (b) getting around space or performance limitations by moving a file/subtree to a bigger/faster device while appearing to keep it in the same place.

There are 2 types of link alias:  hard and soft/symbolic.

Hard links are the default.  They are identical to regular directory entries (inodes) except that they usually point to some file outside the current directory.  But they cannot point at a directory itself, and they cannot point into a different filesystem.

Soft/symbolic links are a tiny fraction slower (they involve reading the link to find out where real_file is).  But they can point to a directory, and they can point into a different filesystem.

Both kinds of link are created with the same file modes as the real file.  The name used for the alias/link need not be the same as the name of the real file.

     The options are as	follows, and if you use contradictory options, the last one given will be the one that takes effect.

-F Not used by itself or for hard links.

-Fsf (default if you just specify -Fs) Deletes any existing file/directory with the chosen name and recreates it as a soft link.  It will not warn you.
 
-Fsi If the name you want to use for the new soft link (it need not be the same as the name of the real file) is already in use where you want to put it, ln will complain to stderr that it already exists and ask whether you want to delete it.  If you respond 'y' or 'Y', it will delete the file (which may be a directory and its contents) and create the new soft link.  If the name refers to a directory, don't respond 'y'/'Y' unless you've saved off the directory's contents or you know you don't care about them.  It will not warn you again.

-Fsw Complains if the real file doesn't exist, and stops without creating the soft link.

-L If real_file is actually a soft link, this option creates a hard link to the real real_file.  This is the default.

-P If real_file is actually a soft link, this option creates a hard link to the soft link, and the soft link continues to point to the real_file.


     -h	   If the alias exists and is a symbolic link, do not follow
	   it to the real_file.	 This is most useful with the -f option, to replace a symlink
	   which may point to a	directory.

     -n	   Same	as -h, for compatibility with other ln implementations.

     -s	   Create a soft/symbolic link.

     -v	   Cause ln to be verbose, showing files as they are processed.

     -w	   Warn	 if the real_file of a symbolic link does not currently exist.


An open(2) on a soft link opens the real_file.  A stat(2) returns information about the real_file.  An lstat(2) returns information about the soft alias/link, and a readlink(2) will read the contents of the soft alias/link.
 

     Given one name, ln creates a link to that real_file using the same name for the alias.

     Given two names, ln creates a link to that real_file using the alias name given UNLESS the second name refers to a directory, in which case the new alias will have the same name as real_file and will be put into that directory.

I have no idea what this means -> If only the directory is specified, the link will be made to the last component of real_file.

     When the utility is called	as link, exactly two arguments must be sup-
     plied, neither of which may specify a directory.  No options may be sup-
     plied in this simple mode of operation, which creates a hard link from alias to real_file.

EXAMPLES
     Make /home/src point to the /usr/src subtree (directory):

	   # ln	-s /usr/src /home/src

     Hard link /usr/local/bin/short_alias to /usr/local/bin/real_file_with_some_long_name:

	   # ln	/usr/local/bin/real_file_with_some_long_name /usr/local/bin/short_alias

     As	an exercise, try the following commands:

	   # ls	-i /bin/[
	   11553 /bin/[
	   # ls	-i /bin/test
	   11553 /bin/test

     Note that both files have the same	inode; that is,	/bin/[ is essentially
     an	alias for the test(1) command.	This hard link exists so test(1) may
     be	invoked	from shell scripts, for	example, using the if [	] construct.

     In	the next example, the second call to ln removes	the original foo and
     creates a replacement pointing to baz:

	   # mkdir bar baz
	   # ln	-s bar foo
	   # ln	-shf baz foo

     Without the -h option, this would instead leave foo pointing to bar and
     inside foo	create a new symlink baz pointing to itself.  This results
     from directory-walking.

     An	easy rule to remember is that the argument order for ln	is the same as
     for cp(1):	The first argument needs to exist (real_file), the second one is created (the_alias).