NAME

     ln - make links between files


SYNOPSIS

     ln [options] source [dest]
     ln [options] source... directory

     POSIX options:  [-f]

     GNU options (shortest form):  [-bdfinsvF] [-S backup-suffix]
     [-V {numbered,existing,simple}] [--help] [--version] [--]


DESCRIPTION

     There are two concepts of `link'  in  Unix,  usually  called
     hard  link  and  soft link. A hard link is just a name for a
     file.  (And a file can have several  names.  It  is  deleted
     from  disk only when the last name is removed. The number of
     names is given by ls(1).  There is no such thing as an `ori-
     ginal'  name:  all  names have the same status. Usually, but
     not necessarily, all names  of  a  file  are  found  in  the
     filesystem that also contains its data.)

     A soft link (or symbolic link, or symlink)  is  an  entirely
     different animal: it is a small special file that contains a
     pathname.  Thus, soft links can point at files on  different
     filesystems  (possibly NFS mounted from different machines),
     and  need  not  point  to  actually  existing  files.   When
     accessed  (with  the  open(2)  or  stat(2)  system calls), a
     reference to a symlink is replaced by the  operating  system
     kernel  with a reference to the file named by the path name.
     (However, with  rm(1)  and  unlink(2)  the  link  itself  is
     removed,  not the file it points to.  There are special sys-
     tem calls lstat(2) and readlink(2) that read the status of a
     symlink  and  the  filename it points to.  For various other
     system calls there is some uncertainty and variation between
     operating  systems  as  to whether the operation acts on the
     symlink itself, or on the file pointed to.)

     ln makes links between files.  By  default,  it  makes  hard
     links;  with  the  -s  option, it makes symbolic (or `soft')
     links.

     If only one file is given,  it  links  that  file  into  the
     current  directory,  that is, creates a link to that file in
     the current directory, with name equal  to  (the  last  com-
     ponent of) the name of that file. (This is a GNU extension.)
     Otherwise, if the last argument names an existing directory,
     ln  will  create links to each mentioned source file in that
     directory, with a name equal to (the last component of)  the
     name  of  that source file.  (But see the description of the
     --no-dereference option below.) Otherwise, if only two files
     are  given, it creates a link named dest to the file source.
     It is an error if the last argument is not a  directory  and
     more than two files are given.

     By default, ln does not remove existing  files  or  existing
     symbolic links.  (Thus, it can be used for locking purposes:
     it will succeed only if dest did not exist already.)  But it
     can be forced to do so with the option -f.

     On existing implementations, if it is  at  all  possible  to
     make  a  hard  link  to a directory, this may be done by the
     superuser only. POSIX forbids the system  call  link(2)  and
     the  utility  ln to make hard links to directories (but does
     not forbid hard links to cross filesystem boundaries).


POSIX OPTIONS

     -f   Remove existing destination files.


GNU OPTIONS

     -d, -F, --directory
          Allow the super-user to make hard links to directories.

     -f, --force
          Remove existing destination files.

     -i, --interactive
          Prompt whether to remove existing destination files.

     -n, --no-dereference
          When given an explicit destination that is a symlink to
          a  directory,  treat  that  destination as if it were a
          normal file.
          When the destination is an actual directory (not a sym-
          link  to  one),  there  is  no  ambiguity.  The link is
          created in that directory.  But when the specified des-
          tination  is  a  symlink  to a directory, there are two
          ways to treat the user's request.   ln  can  treat  the
          destination  just  as  it  would a normal directory and
          create the link in it.  On the other hand, the destina-
          tion  can be viewed as a non-directory - as the symlink
          itself.  In that case, ln must delete  or  backup  that
          symlink  before  creating the new link.  The default is
          to treat a destination that is a symlink to a directory
          just like a directory.

     -s, --symbolic
          Make symbolic links instead of hard links.  This option
          merely produces an error message on systems that do not
          support symbolic links.

     -v, --verbose
          Print the name of each file before linking it.


GNU BACKUP OPTIONS

     The GNU versions of programs like cp, mv,  ln,  install  and
     patch  will  make a backup of files about to be overwritten,
     changed or destroyed if that is desired. That  backup  files
     are  desired  is indicated by the -b option. How they should
     be named is specified by the -V option.  In case the name of
     the backup file is given by the name of the file extended by
     a suffix, this suffix is specified by the -S option.

     -b, --backup
          Make backups of files that are about to be  overwritten
          or removed.

     -S SUFFIX, --suffix=SUFFIX
          Append SUFFIX to each backup file made.  If this option
          is not specified, the value of the SIMPLE_BACKUP_SUFFIX
          environment    variable    is     used.      And     if
          SIMPLE_BACKUP_SUFFIX is not set, the default is `~'.

     -V METHOD, --version-control=METHOD
          Specify how backup files are named. The METHOD argument
          can  be  `numbered' (or `t'), `existing' (or `nil'), or
          `never' (or `simple').  If this option  is  not  speci-
          fied,  the  value  of  the  VERSION_CONTROL environment
          variable is used.  And if VERSION_CONTROL is  not  set,
          the default backup type is `existing'.

          This  option  corresponds   to   the   Emacs   variable
          `version-control'.    The  valid  METHODs  are  (unique
          abbreviations are accepted):

          t, numbered
               Always make numbered backups.

          nil, existing
               Make numbered backups of files that  already  have
               them, simple backups of the others.

          never, simple
               Always make simple backups.


GNU STANDARD OPTIONS

     --help
          Print a usage message on standard output and exit  suc-
          cessfully.

     --version
          Print version information on standard output, then exit
          successfully.

     --   Terminate option list.


ENVIRONMENT

     The variables LANG, LC_ALL, LC_CTYPE  and  LC_MESSAGES  have
     the usual meaning.


CONFORMING TO

     POSIX 1003.2. However, POSIX 1003.2 (1996) does not  discuss
     soft  links.   Soft links were introduced by BSD, and do not
     occur in System V release 3 (and older) systems.


SEE ALSO

     ls(1),  rm(1),  link(2),  lstat(2),  open(2),   readlink(2),
     stat(2), unlink(2)


NOTES

     This page describes ln as found in the fileutils-3.16  pack-
     age;  other  versions  may differ slightly. Mail corrections
     and  additions  aeb@cwi.nl  and   aw@mail1.bet1.puv.fi   and
     ragnar@lightside.ddns.org  .   Report bugs in the program to
     fileutils-bugs@gnu.ai.mit.edu.