[Bug 194308] New: The man page for ln(1) is extremely confusing

[bugzilla-noreply at freebsd.org]

https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=194308

            Bug ID: 194308
           Summary: The man page for ln(1) is extremely confusing
           Product: Documentation
           Version: Latest
          Hardware: Any
                OS: Any
            Status: Needs Triage
          Severity: Affects Many People
          Priority: ---
         Component: Documentation
          Assignee: freebsd-doc at FreeBSD.org
          Reporter: scratch65535 at att.net

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).

-- 
You are receiving this mail because:
You are the assignee for the bug.